@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/epic/epic-close.ts

@@ -1,5 +1,10 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { epic_child_schema, epic_issue_schema, type EpicChildData } from '#scripts/git/git-schemas'
+import {
+	epic_child_schema,
+	epic_issue_schema,
+	type EpicChildData,
+	type EpicIssueData,
+} from '#scripts/git/git-schemas'
 import { cutoff_cause, cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import {
 	parse_json_array_or_undefined,
@@ -37,6 +42,7 @@ interface EpicIssue {
 	children: Array<number>
 	external_children: Array<ExternalChild>
 	has_declared_order: boolean
+	is_reopened: boolean
 }
 
 interface SiblingState {
@@ -44,8 +50,12 @@ interface SiblingState {
 	has_blocked_by: boolean
 }
 
-function to_epic_issue(raw: { number: number; body?: string | undefined }): EpicIssue {
+// GitHub's `state_reason` for an open issue that was closed once and reopened.
+const REOPENED = 'reopened'
+
+function to_epic_issue(raw: EpicIssueData): EpicIssue {
 	return {
+		is_reopened: raw.stateReason === REOPENED,
 		number: raw.number,
 		children: epic_parse.parse_task_list_issue_numbers(raw.body),
 		external_children: epic_parse.parse_external_task_list_children(raw.body),
@@ -98,30 +108,32 @@ function to_sibling_state(raw_json: string | undefined): SiblingState {
 	}
 }
 
-async function inspect_sibling(sibling: number, repo?: string): Promise<SiblingState> {
-	return to_sibling_state(await git_gh_command.issue_get_state_and_relations(String(sibling), repo))
-}
+type ChildRead = SiblingState & { is_readable: boolean }
 
-// A cross-repository child, read by naming its repository in the read's REST path. `is_readable`
-// is what decides whether the epic may close at all: closing while a child's state is unknown is
-// exactly what the old refusal prevented, and reading them is the only thing that changed.
-async function inspect_external(
-	child: ExternalChild,
-): Promise<SiblingState & { is_readable: boolean }> {
+// A same-repository child carries no `repo`; a cross-repository one names it.
+type ChildReference = Omit<ExternalChild, 'repo'> & { repo?: string | undefined }
+
+// A child read by number, naming its repository in the REST path when it lives in another one.
+// `is_readable` is what decides whether the epic may close at all: closing while a child's state is
+// unknown is exactly what the refusal prevents. A failed read is told apart from an open child
+// rather than read as one, which left a finished epic open with nothing in the output (#4560). A
+// read whose answer carries no state is a failed read too.
+async function inspect_child(child: ChildReference): Promise<ChildRead> {
 	const raw = await git_gh_command.issue_get_state_and_relations(String(child.number), child.repo)
 
-	return { ...to_sibling_state(raw), is_readable: raw !== undefined }
+	return { ...to_sibling_state(raw), is_readable: parse_child(raw)?.state !== undefined }
 }
 
 // The merged Issue is excluded rather than queried: GitHub applies `closes #N` asynchronously, so
 // reading its state immediately after the merge races with that propagation.
-async function inspect_siblings(
-	epic: EpicIssue,
-	merged_number: number,
-): Promise<Array<SiblingState>> {
-	const siblings = epic.children.filter((child) => child !== merged_number)
+async function inspect_children(epic: EpicIssue, merged_number: number): Promise<Array<ChildRead>> {
+	const siblings: Array<ChildReference> = epic.children
+		.filter((child) => child !== merged_number)
+		.map((number) => ({ number }))
 
-	return await Promise.all(siblings.map(async (sibling) => await inspect_sibling(sibling)))
+	return await Promise.all(
+		[...siblings, ...epic.external_children].map(async (child) => await inspect_child(child)),
+	)
 }
 
 // `pnpm josh epic --ordered` and `--add` record the declared chain themselves, through the REST
@@ -165,9 +177,8 @@ const CASCADE_DEPTH_NOTE = `⚠️  Epic auto-close cascade reached its ${String
 
 // **An unreadable comment listing does not stop the close.** It is announced and closed exactly as
 // it was before the duplicate check existed, because refusing here would strand the epic: nothing
-// re-triggers the auto-close once every child is closed — `resolve_and_close` only evaluates epics
-// holding the issue that just merged, and that merge has already happened. One rate-limited read
-// would leave a finished epic open until somebody noticed.
+// re-triggers the auto-close until some later child close sweeps the open epics, and that close may
+// never come. One rate-limited read would leave a finished epic open until somebody noticed.
 //
 // The direction is chosen on what each mistake costs, and they are not symmetric. Announcing twice
 // costs one redundant comment and nothing else, because the epic *closes* — which is what ends a loop
@@ -209,38 +220,26 @@ async function close_epic(epic: EpicIssue): Promise<boolean> {
 	return await close_epic_with(epic_number, comment)
 }
 
-// The cross-repository children's states, and whether every one of them could be read. An epic with
-// a child whose state is unknown keeps the old handling — left open for manual closing.
-async function inspect_external_children(
-	epic: EpicIssue,
-): Promise<{ states: Array<SiblingState>; is_complete: boolean }> {
-	if (epic.external_children.length === 0) return { states: [], is_complete: true }
-	const results = await Promise.all(
-		epic.external_children.map(async (child) => await inspect_external(child)),
-	)
+// The manual-close request is made only when every child that was read is closed: while one is still
+// open the batch is unfinished anyway, and asking for a manual close would invite closing it early.
+function warn_when_unread_blocks_close(epic: EpicIssue, states: ReadonlyArray<ChildRead>): void {
+	if (states.some((state) => state.is_readable && !state.is_closed)) return
 
-	return {
-		states: results.map((result) => ({
-			is_closed: result.is_closed,
-			has_blocked_by: result.has_blocked_by,
-		})),
-		is_complete: results.every((result) => result.is_readable),
-	}
+	console.info(
+		`⚠️  Epic ${session_cite.issue(epic.number)} has a child whose state could not be read; ${CLOSE_MANUALLY}`,
+	)
 }
 
+// An epic with a child whose state is unknown is left open for manual closing, and says so.
 async function close_epic_when_complete(epic: EpicIssue, merged_number: number): Promise<boolean> {
-	const external = await inspect_external_children(epic)
+	const states = await inspect_children(epic, merged_number)
 
-	if (!external.is_complete) {
-		console.info(
-			`ℹ️  Epic ${session_cite.issue(epic.number)} has a child in another repository whose state could not be read; ${CLOSE_MANUALLY}`,
-		)
+	if (states.some((state) => !state.is_readable)) {
+		warn_when_unread_blocks_close(epic, states)
 
 		return false
 	}
 
-	const states = [...(await inspect_siblings(epic, merged_number)), ...external.states]
-
 	warn_when_order_unrecorded(epic, states)
 
 	if (states.some((state) => !state.is_closed)) return false
@@ -315,22 +314,74 @@ async function close_next_level(
 	return next
 }
 
-// Breadth-first up the nesting: level 0 closes the epics holding the merged issue, and each closed
-// epic becomes the next level's completed child, so a fully-finished parent closes in the same pass.
-async function cascade_close(
+// Breadth-first up the nesting: each closed epic becomes the next level's completed child, so a
+// fully-finished parent closes in the same pass. `false` when the depth cap stopped the walk.
+async function cascade_from(
 	open_epics: ReadonlyArray<EpicIssue>,
-	merged_number: number,
-): Promise<void> {
-	const evaluated = new Set<number>()
-	let frontier: ReadonlyArray<number> = [merged_number]
+	start: ReadonlyArray<number>,
+	evaluated: Set<number>,
+): Promise<boolean> {
+	let frontier = start
 
 	for (let depth = 0; depth < MAX_CASCADE_DEPTH; depth++) {
-		if (frontier.length === 0) return
+		if (frontier.length === 0) return true
 		// eslint-disable-next-line no-await-in-loop -- the cascade closes one level before reading the next
 		frontier = await close_next_level(open_epics, frontier, evaluated)
 	}
 
 	if (frontier.length > 0) console.info(CASCADE_DEPTH_NOTE)
+
+	return frontier.length === 0
+}
+
+// An epic listing no child has nothing to be complete: with no state to read, the completion check
+// would close it — a prose epic, or one whose task list is not written yet.
+function tracks_children(epic: EpicIssue): boolean {
+	return epic.children.length + epic.external_children.length > 0
+}
+
+// Every open epic the cascade did not reach, closed when each child is: an epic whose last child
+// closed outside every josh path — an `already-done` child `run:merge` parked and a person closed by
+// hand (#4564) — is found by the next close of any child. An epic is marked evaluated only once it
+// closes, so a parent read before its child epic closed here is evaluated again by that cascade.
+//
+// A reopened epic is left out: a person reopening a finished epic has said it is not done, and only
+// a close of one of its own children — the cascade above — may close it again.
+function is_sweep_target(epic: EpicIssue, evaluated: ReadonlySet<number>): boolean {
+	return !evaluated.has(epic.number) && !epic.is_reopened && tracks_children(epic)
+}
+
+async function sweep_unreached(
+	open_epics: ReadonlyArray<EpicIssue>,
+	merged_number: number,
+	evaluated: Set<number>,
+): Promise<Array<number>> {
+	const closed: Array<number> = []
+	const unreached = open_epics.filter((epic) => is_sweep_target(epic, evaluated))
+
+	for (const epic of unreached) {
+		// eslint-disable-next-line no-await-in-loop -- a closed epic joins the evaluated set the cascade reads
+		if (await close_epic_isolated(epic, merged_number)) closed.push(epic.number)
+	}
+
+	for (const number of closed) evaluated.add(number)
+
+	return closed
+}
+
+// Level 0 closes the epics holding the merged issue; the sweep then closes any other finished epic.
+// A cascade stopped at the depth cap asks for a manual close, so the sweep does not run past it.
+async function cascade_close(
+	open_epics: ReadonlyArray<EpicIssue>,
+	merged_number: number,
+): Promise<void> {
+	const evaluated = new Set<number>()
+
+	if (!(await cascade_from(open_epics, [merged_number], evaluated))) return
+
+	const swept = await sweep_unreached(open_epics, merged_number, evaluated)
+
+	await cascade_from(open_epics, swept, evaluated)
 }
 
 const UNREADABLE_EPIC_LIST_MESSAGE =
@@ -363,9 +414,15 @@ async function resolve_and_close_safely(merged_number: number): Promise<void> {
 /**
  * Close every open epic whose task list is fully complete once `issue_number` closed.
  *
- * Requires `is_merged`: the linked Issue is treated as closed without being queried, which only
- * holds once the PR actually merged. On a `--no-merge` run that Issue is still open, so skipping
- * this guard would close an epic whose batch is not finished.
+ * **The one entry every child close goes through** (#4560): `followup` after its merge,
+ * `josh issue:measured` after its own close, and `run:merge` for every child it counts as merged —
+ * which also catches a merge GitHub left OPEN. Running it
+ * twice for one child is harmless: a closed epic is no longer in the open listing. Every other open
+ * epic is swept too, so one whose last child closed outside these paths closes here (#4564).
+ *
+ * Requires `is_merged` — the child is known closed: the linked Issue is treated as closed without
+ * being queried. On a `--no-merge` run that Issue is still open, so skipping this guard would close
+ * an epic whose batch is not finished.
  */
 async function close_completed_epics(input: {
 	issue_number: string | undefined

package/scripts/epic/epic-cross-repo.ts

@@ -2,6 +2,7 @@ import { repo_map_logic } from '#scripts/discovery/repo-map-logic'
 import { repo_origin } from '#scripts/discovery/repo-origin'
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { json_value } from '#scripts/lib/json-value'
 import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { propagate_publish } from '#scripts/propagate/propagate-publish'
 import { derive_versions_endpoint } from '#scripts/version/version-command-config'
@@ -209,14 +210,10 @@ function to_answer(repo: string, fields: ManifestFields): ManifestAnswer {
 }
 
 function to_manifest(repo: string, stdout: string): ManifestAnswer {
-	try {
-		const parsed: unknown = JSON.parse(stdout.trim())
-		if (typeof parsed !== 'object' || parsed === null) return { kind: 'unreadable' }
+	const parsed = json_value.parse_or_undefined(stdout.trim())
+	if (typeof parsed !== 'object' || parsed === null) return { kind: 'unreadable' }
 
-		return to_answer(repo, parsed)
-	} catch {
-		return { kind: 'unreadable' }
-	}
+	return to_answer(repo, parsed)
 }
 
 // Why the read failed, asked only when it did. The status line is the protocol rather than prose, so

package/scripts/epic/epic-decide.ts

@@ -0,0 +1,119 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { issue_read } from '#scripts/issue/issue-read'
+import { session_cite } from '#scripts/issue/session-cite'
+import { epic_decision } from './epic-decision'
+import { epic_parse } from './epic-parse'
+import { epic_read } from './epic-read'
+import type { EpicSubject } from './epic-validate'
+
+// `josh epic --decide <E> <N...> --decision-file <path|->` — record a decision about children the epic
+// already tracks: the epic's `## Decisions` entry, a comment on each child, and each child's
+// `needs-decision` label removed. The text is the caller's; placing it is this command's.
+//
+// **A rerun writes nothing twice.** The entry and each comment are looked for before they are
+// written, so a run that stopped half way is finished by running it again.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface DecideInput {
+	epic_number: number
+	children: ReadonlyArray<number>
+	decision: string
+}
+
+function format_list(numbers: ReadonlyArray<number>): string {
+	return numbers.map((issue_number) => session_cite.issue(issue_number)).join(', ')
+}
+
+// A child the epic does not track is refused before anything is written: placing it is `--add`'s,
+// which records the same decision in the same call.
+function untracked_error(epic_number: number, untracked: ReadonlyArray<number>): string {
+	return `${format_list(untracked)} not tracked by ${session_cite.issue(epic_number)}; place it with \`pnpm josh epic --add ${String(epic_number)} <N> --decision-file <path>\`. Nothing was written.`
+}
+
+// The epic the decision goes to, or why nothing is written: a record `append_decision` would refuse
+// (checked before any read), an unreadable epic, or a child it does not track.
+async function read_decision_target(input: DecideInput): Promise<EpicSubject | { error: string }> {
+	const record_error = epic_decision.find_decision_error(input.decision)
+	if (record_error !== undefined) return { error: record_error }
+	const subject = await epic_read.read_subject(input.epic_number)
+
+	if (subject === undefined) {
+		return { error: `Could not read issue ${session_cite.issue(input.epic_number)}.` }
+	}
+
+	const tracked = epic_parse.parse_task_list_issue_numbers(subject.body)
+	const untracked = input.children.filter((child) => !tracked.includes(child))
+
+	return untracked.length === 0 ? subject : { error: untracked_error(input.epic_number, untracked) }
+}
+
+async function record_on_epic(subject: EpicSubject, decision: string): Promise<string> {
+	const epic = session_cite.issue(subject.number)
+
+	if (epic_decision.has_decision(subject.body, decision)) {
+		return `📝 ${epic} already records this decision.`
+	}
+
+	const body = epic_decision.append_decision(subject.body ?? '', decision)
+
+	await git_gh_command.issue_edit_body(String(subject.number), body)
+
+	return `📝 Decision recorded in ${epic}'s \`## Decisions\`.`
+}
+
+// `undefined` when the comments could not be read: posting then risks the duplicate this exists to
+// prevent, so the child is reported as not recorded and a rerun finishes it.
+async function has_comment(child: number, decision: string): Promise<boolean | undefined> {
+	const comments = await issue_read.parse_comments(
+		await git_gh_command.issue_list_comments(String(child)),
+	)
+
+	return comments?.some((comment) => comment.body.trim() === decision.trim())
+}
+
+// The label goes only once the child carries the record, so a failed comment leaves it parked.
+async function record_on_child(child: number, decision: string): Promise<boolean> {
+	const has_record = await has_comment(child, decision)
+	if (has_record === undefined) return false
+	const is_commented =
+		has_record || (await git_gh_command.issue_try_comment(String(child), decision))
+	if (!is_commented) return false
+
+	return await git_gh_command.issue_clear_label(String(child), NEEDS_DECISION_LABEL)
+}
+
+function format_child_report(total: number, failures: number): string {
+	if (failures === 0) return epic_decision.format_decision_report({ total, failures })
+
+	return `⚠️  ${String(failures)} of ${String(total)} child issue(s) could not be given the comment or lose \`${NEEDS_DECISION_LABEL}\`; rerun the same command — nothing is written twice.`
+}
+
+async function decide(input: DecideInput): Promise<number> {
+	const epic = await read_decision_target(input)
+
+	if ('error' in epic) {
+		console.error(`✖ ${epic.error}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(await record_on_epic(epic, input.decision))
+	const recorded = await Promise.all(
+		input.children.map(async (child) => await record_on_child(child, input.decision)),
+	)
+	const failures = recorded.filter((is_recorded) => !is_recorded).length
+
+	console.info(format_child_report(input.children.length, failures))
+
+	return failures === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+const epic_decide = {
+	decide,
+}
+
+export { epic_decide }
+export type { DecideInput }

package/scripts/epic/epic-decision.ts

@@ -153,8 +153,17 @@ function read_recorded_reasons(body: string | undefined): string {
 	].join('\n')
 }
 
+// Whether `## Decisions` already carries this record, compared as `append_decision` writes it — so a
+// rerun of `epic --decide` after a partial failure appends nothing a second time.
+function has_decision(body: string | undefined, record: string): boolean {
+	if (body === undefined) return false
+
+	return read_section(body, DECISIONS_HEADING_PATTERN).includes(record.trimEnd())
+}
+
 const epic_decision = {
 	append_decision,
+	has_decision,
 	append_replacements,
 	read_recorded_reasons,
 	find_decision_error,

package/scripts/epic/epic-fetch.ts

@@ -1,5 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { IssueReadFailure } from '#scripts/gh/git-gh-issue-read'
+import { issue_sample_gate } from '#scripts/issue/issue-sample-gate'
 import { epic_cross_repo } from './epic-cross-repo'
 import type { EpicChild, IssueReference } from './epic-graph'
 import { epic_issue, type EpicIssue } from './epic-issue'
@@ -21,6 +22,7 @@ function to_child(parsed: EpicIssue, repo: string): EpicChild {
 		state: epic_issue.normalize_state(parsed.state),
 		labels: epic_issue.label_names(parsed),
 		blocked_by: epic_issue.blocker_references_of(parsed, repo),
+		body: parsed.body,
 	}
 }
 
@@ -132,6 +134,8 @@ async function fetch_child_read(
 
 	const parsed = epic_issue.parse_epic_issue(read.json)
 
+	await issue_sample_gate.prime([parsed?.body])
+
 	return { child: parsed === undefined ? undefined : to_child(parsed, repo), is_unreachable: false }
 }
 

package/scripts/epic/epic-graph.ts

@@ -29,6 +29,8 @@ interface EpicChild {
 	state: 'OPEN' | 'CLOSED'
 	labels: ReadonlyArray<string>
 	blocked_by: ReadonlyArray<IssueReference>
+	// Read only to hold a child until its declared start time; absent on rows built without a read.
+	body?: string | undefined
 }
 
 // What is wrong with the graph. Both stop the run — neither is something to pick a winner for.

package/scripts/epic/epic-issue.ts

@@ -2,6 +2,7 @@ import { git_gh_issue_rest } from '#scripts/gh/git-gh-issue-rest'
 import { blocked_by_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
+import { REPOSITORY_SEGMENT_SOURCE } from './epic-parse'
 import type { IssueReference } from './epic-reference'
 
 // The shapes one issue is read as, and the argument every epic command takes.
@@ -116,7 +117,10 @@ interface EpicReference {
 	number: number
 }
 
-const QUALIFIED_REFERENCE = /^([\w.-]+\/[\w.-]+)#(\d+)$/u
+const QUALIFIED_REFERENCE = new RegExp(
+	String.raw`^(${REPOSITORY_SEGMENT_SOURCE}\/${REPOSITORY_SEGMENT_SOURCE})#(\d+)$`,
+	'u',
+)
 const QUALIFIED_REPO_GROUP = 1
 const QUALIFIED_NUMBER_GROUP = 2
 

package/scripts/epic/epic-label-age.ts

@@ -1,6 +1,7 @@
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 
 // How long each lane holder has carried `in-progress`. The stale-label rule
 // in `backlogrun-progress.md` is applied by age, and until this read the age was a hand-written
@@ -12,7 +13,6 @@ import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
 
 // Matches the `Stale \`in-progress\`` row of the table in `backlogrun-progress.md`.
 const STALE_MINUTES = 90
-const MS_PER_MINUTE = 60_000
 const TIMELINE_PAGE = 100
 
 const LABELED_FILTER = `.[] | select(.event == "labeled" and (.label.name | ascii_downcase) == "${IN_PROGRESS_LABEL}") | .created_at`

package/scripts/epic/epic-lane-offer.ts

@@ -1,4 +1,5 @@
 import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { lane_snapshot_trace } from '#scripts/lane/lane-snapshot-trace'
 import { epic_busy, type BusyRead } from './epic-busy'
 import {
 	epic_candidate_confirm,
@@ -39,11 +40,13 @@ interface RepoPool {
 
 // What is being asked of one repository. `is_all_lanes` is the caller's appetite rather than the
 // repository's capacity: `epic:next --repo` prints a single token unless `--lanes` was passed, so a
-// caller written against the one-child contract keeps getting exactly one child.
+// caller written against the one-child contract keeps getting exactly one child. `is_this_checkout`
+// says whether `repo` is the repository this command runs in, whose ship records are the ones read.
 interface LaneRequest {
 	repo: string
 	limit: number
 	is_all_lanes: boolean
+	is_this_checkout: boolean
 }
 
 // The answer for one repository: the children to start, the verdict standing in their place when
@@ -62,8 +65,27 @@ function is_held(read: BusyRead): boolean {
 	return read.kind === 'unreadable' || read.kind === 'truncated'
 }
 
-function free_lanes(read: BusyRead, limit: number): number {
-	return is_held(read) ? NO_LANES : lane_capacity.free_lanes(limit, epic_busy.occupied_lanes(read))
+function free_lanes(read: BusyRead, limit: number, merge_waiting: number): number {
+	if (is_held(read)) return NO_LANES
+
+	const holders = epic_busy.occupied_lanes(read)
+
+	// A merge-waiting holder frees its place under the limit but keeps its port seat
+	// (`lane_capacity.free_lanes`).
+	return lane_capacity.free_lanes(limit, holders - merge_waiting, holders)
+}
+
+// **A holder whose detached ship waits on its merge holds no lane** — the count `backlog:drive` makes
+// for the pool (`backlog-occupied.ts`), so a named epic's lanes are offered the place too
+// (joshuafolkken/kit#4466). It keeps `in-progress` until the merge. The ship records read are this
+// checkout's, so a `--repo` naming another repository is discounted nothing: its holder numbers
+// would be matched against this repository's unrelated ships.
+async function merge_waiting_holders(read: BusyRead, request: LaneRequest): Promise<number> {
+	if (read.kind !== 'busy' || !request.is_this_checkout) return NO_LANES
+
+	return await lane_snapshot_trace.count_merge_waiting(
+		read.issues.map((issue) => String(issue.number)),
+	)
 }
 
 function wanted_of(request: LaneRequest, free: number): number {
@@ -247,7 +269,7 @@ async function offer_for_repo(
 
 	if (notice !== undefined) console.error(notice)
 
-	const free = free_lanes(read, request.limit)
+	const free = free_lanes(read, request.limit, await merge_waiting_holders(read, request))
 	const ages = await holder_ages(read, request.repo)
 
 	if (free === NO_LANES) {
@@ -263,9 +285,22 @@ async function offer_for_repo(
 	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request, ages)
 }
 
+// A `--repo` compared against the repository this command runs in, case-insensitively as GitHub
+// names it.
+function lane_request(
+	asked: Pick<LaneRequest, 'repo' | 'is_all_lanes'>,
+	limit: number,
+	current_repo: string,
+): LaneRequest {
+	const is_this_checkout = asked.repo.toLowerCase() === current_repo.toLowerCase()
+
+	return { ...asked, limit, is_this_checkout }
+}
+
 const epic_lane_offer = {
 	combine_verdicts,
 	dedupe_pools,
+	lane_request,
 	offer_for_repo,
 }
 

package/scripts/epic/epic-next-main.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { epic_next } from './epic-next'
+
+// The `josh epic:next` entry, kept apart from `epic-next.ts` because other modules import that one: a
+// bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+//
+// `.env` is read here rather than through the dispatcher's `tsx_arguments`: declaring any would
+// disqualify this command from in-process dispatch, and an unattended `epicrun` asks it every sixty
+// seconds for the whole life of a run (`josh-environment-file.ts` records the measurement). Inside the
+// guard, so a developer's own `.env` cannot decide what the unit tests see.
+//
+// `process.exitCode` rather than `process.exit()`, for the reason `scripts/cost-runtime/cost-main.ts`
+// records: the answer goes to standard output and a write to a pipe is asynchronous on macOS, so
+// exiting can tear the process down before it drains. This command's contract is
+// `answer=$(pnpm josh epic:next <E>)`, which is exactly that pipe.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	josh_environment_file.load_environment_file()
+	process.exitCode = await epic_next.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/epic/epic-next.ts

@@ -1,9 +1,6 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_citation } from '#scripts/rules/issue-citation'
@@ -31,7 +28,6 @@ import { epic_report, type EpicNextResult } from './epic-report'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // Asking for every free lane (`--lanes`) is opt-in, so the answer stays one token for a caller that
 // has not been changed. `--repo` alone prints exactly one number.
 const OPTIONS = { repo: { type: 'string' }, lanes: { type: 'boolean' } } as const
@@ -351,11 +347,13 @@ async function report_epics(
 	const choice = await lane_capacity.lane_limit()
 	if (choice.kind === 'problem') return refuse(choice.problem)
 
-	return await report(
-		views,
-		{ repo: options.repo, limit: choice.limit, is_all_lanes: options.is_all_lanes ?? false },
+	const request = epic_lane_offer.lane_request(
+		{ repo: options.repo, is_all_lanes: options.is_all_lanes ?? false },
+		choice.limit,
 		current_repo,
 	)
+
+	return await report(views, request, current_repo)
 }
 
 // One view per named epic, classified against one shared registry read. `running` is every named
@@ -416,14 +414,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await run_epics(options)
 }
 
-// `process.exitCode` rather than `process.exit()`, for the reason `scripts/cost-runtime/cost-cli.ts` records:
-// the answer goes to standard output and a write to a pipe is asynchronous on macOS, so exiting can
-// tear the process down before it drains. This command's contract is `answer=$(pnpm josh epic:next
-// <E>)`, which is exactly that pipe.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const epic_next = {
 	EXTERNAL_NOTICE,
 	FOREIGN_EPIC,
@@ -433,19 +423,11 @@ const epic_next = {
 	parse_options,
 	refuse_reads,
 	views_of,
+	run,
 	run_epics,
 	decide,
 	report,
 }
 
-// `.env` is read here rather than through the dispatcher's `tsx_arguments`: declaring any would
-// disqualify this command from in-process dispatch, and an unattended `epicrun` asks it every sixty
-// seconds for the whole life of a run (`josh-environment-file.ts` records the measurement). Inside the guard
-// rather than in `main`, so a developer's own `.env` cannot decide what the unit tests see.
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	josh_environment_file.load_environment_file()
-	await main(process.argv.slice(ARGV_OFFSET))
-}
-
 export type { NextOptions }
 export { epic_next }