@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/epic/epic-decide.ts

@@ -2,6 +2,7 @@ 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 { size_estimate } from '#scripts/issue/size-estimate'
 import { epic_decision } from './epic-decision'
 import { epic_parse } from './epic-parse'
 import { epic_read } from './epic-read'
@@ -9,7 +10,8 @@ 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.
+// `needs-decision` label removed. The text is the caller's; placing it is this command's. A record
+// that states a size estimate line also replaces each child's own estimate line with it.
 //
 // **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.
@@ -33,10 +35,20 @@ function untracked_error(epic_number: number, untracked: ReadonlyArray<number>):
 	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.`
 }
 
+// A size estimate is one child's: stated in a record about several, it would overwrite each child's
+// own with one figure, so the record is refused before anything is written.
+function size_error(input: DecideInput): string | undefined {
+	if (input.children.length === 1 || size_estimate.stated_line(input.decision) === undefined) {
+		return undefined
+	}
+
+	return `The record states a size estimate but names ${format_list(input.children)}; an estimate is one child's, so record it with \`--decide\` for that child alone. 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)
+	const record_error = epic_decision.find_decision_error(input.decision) ?? size_error(input)
 	if (record_error !== undefined) return { error: record_error }
 	const subject = await epic_read.read_subject(input.epic_number)
 
@@ -74,13 +86,37 @@ async function has_comment(child: number, decision: string): Promise<boolean | u
 	return comments?.some((comment) => comment.body.trim() === decision.trim())
 }
 
+async function try_edit_body(child: number, body: string): Promise<boolean> {
+	try {
+		await git_gh_command.issue_edit_body(String(child), body)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// joshuafolkken/kit#5758: a record that states a size estimate line restates the child's own, so
+// `lane:plan` reads the widened scope rather than the estimate filed before the decision. `false` when
+// the child cannot be read or written, as a failed comment is, so a rerun finishes it.
+async function restate_size(child: number, decision: string): Promise<boolean> {
+	const line = size_estimate.stated_line(decision)
+	if (line === undefined) return true
+	const subject = await epic_read.read_subject(child)
+	if (subject === undefined) return false
+	const body = subject.body ?? ''
+	const restated = size_estimate.restated(body, line)
+
+	return restated === body || (await try_edit_body(child, restated))
+}
+
 // 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
+	if (!is_commented || !(await restate_size(child, decision))) return false
 
 	return await git_gh_command.issue_clear_label(String(child), NEEDS_DECISION_LABEL)
 }

package/scripts/epic/epic-fetch.ts

@@ -1,6 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import type { IssueReadFailure } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_issue_batch_graphql } from '#scripts/gh/git-gh-issue-batch-graphql'
+import { git_gh_issue_batch_read } from '#scripts/gh/git-gh-issue-batch-read'
+import type { IssueRead, IssueReadFailure } from '#scripts/gh/git-gh-issue-read'
 import { issue_sample_prime } from '#scripts/issue/issue-sample-prime'
+import { epic_child_source, type ChildSource } from './epic-child-source'
 import { epic_cross_repo } from './epic-cross-repo'
 import type { EpicChild, IssueReference } from './epic-graph'
 import { epic_issue, type EpicIssue } from './epic-issue'
@@ -9,9 +12,10 @@ import { epic_relation_recheck } from './epic-relation-recheck'
 
 // Reading an epic and its children from GitHub.
 //
-// All execution state lives on GitHub and nowhere else — no local state file. A run interrupted
-// halfway is resumed by asking again, which is the whole reason `epic:next` can be the base of an
-// unattended run.
+// All execution state lives on GitHub and nowhere else — no local state file; the closed-child
+// record `backlog:next` passes in is a cache of GitHub's answer, never a source of its own. A run
+// interrupted halfway is resumed by asking again, which is the whole reason `epic:next` can be the
+// base of an unattended run.
 
 const CHILD_LIMIT = 200
 
@@ -120,16 +124,14 @@ interface ChildRead {
 	is_unreachable: boolean
 }
 
-async function fetch_child_read(
-	issue_number: number,
-	repo: string,
-	scope?: string,
-): Promise<ChildRead> {
-	const read = await git_gh_command.issue_get_state_and_relations_classified(
-		String(issue_number),
-		scope,
-	)
+const NOT_READ: ChildRead = { child: undefined, is_unreachable: false }
 
+async function read_rest(issue_number: number, scope?: string): Promise<IssueRead> {
+	return await git_gh_command.issue_get_state_and_relations_classified(String(issue_number), scope)
+}
+
+// `read` is the batch's answer for this child (`read_children`), or its REST read.
+async function to_child_read(read: IssueRead, repo: string): Promise<ChildRead> {
 	if (read.kind !== 'read') {
 		return { child: undefined, is_unreachable: git_gh_command.is_unreachable_read(read) }
 	}
@@ -141,6 +143,27 @@ async function fetch_child_read(
 	return { child: parsed === undefined ? undefined : to_child(parsed, repo), is_unreachable: false }
 }
 
+// Children of one repository read together, the batched way (`git-gh-issue-batch-read.ts`).
+async function read_children(
+	issue_numbers: ReadonlyArray<number>,
+	repo: string,
+	scope?: string,
+): Promise<Map<number, ChildRead>> {
+	const reads = await git_gh_issue_batch_read.read_each(issue_numbers, {
+		repo: scope,
+		from_json: git_gh_issue_batch_graphql.answered,
+		read_rest: async (issue_number) => await read_rest(issue_number, scope),
+	})
+	const entries = await Promise.all(
+		reads.map(async ([issue_number, read]): Promise<[number, ChildRead]> => [
+			issue_number,
+			await to_child_read(read, repo),
+		]),
+	)
+
+	return new Map(entries)
+}
+
 // One child's state, labels and native relations. A child that cannot be read is reported as
 // missing rather than assumed closed: assuming would let an epic advance past a child nobody looked
 // at.
@@ -149,7 +172,7 @@ async function fetch_child(
 	repo: string,
 	scope?: string,
 ): Promise<EpicChild | undefined> {
-	const read = await fetch_child_read(issue_number, repo, scope)
+	const read = await to_child_read(await read_rest(issue_number, scope), repo)
 
 	return read.child
 }
@@ -190,16 +213,66 @@ function is_body_unreachable(failure: IssueReadFailure | undefined): boolean {
 	return failure !== undefined && git_gh_command.is_unreachable_read(failure)
 }
 
-// Every child the epic's task list tracks, in the order the body lists them.
+// A child the source already answered is primed exactly as a read one is, and asks nothing else.
+async function known_or_read(
+	issue_number: number,
+	known: ReadonlyMap<number, EpicChild>,
+	fresh: ReadonlyMap<number, ChildRead>,
+): Promise<ChildRead> {
+	const child = known.get(issue_number)
+	if (child === undefined) return fresh.get(issue_number) ?? NOT_READ
+
+	await issue_sample_prime.prime([child.body])
+
+	return { child, is_unreachable: false }
+}
+
+// Every child, in the order given: the ones the source knows from it, the rest read together.
+async function answer_children(
+	issue_numbers: ReadonlyArray<number>,
+	known: ReadonlyMap<number, EpicChild>,
+	repo: string,
+	scope?: string,
+): Promise<ReadonlyArray<ChildRead>> {
+	const unknown = issue_numbers.filter((issue_number) => !known.has(issue_number))
+	const fresh = await read_children(unknown, repo, scope)
+
+	return await Promise.all(
+		issue_numbers.map(async (issue_number) => await known_or_read(issue_number, known, fresh)),
+	)
+}
+
+// A closed child answered without a read that an open sibling waits on is read again: reopened, it
+// holds that sibling, as it did when every child was read.
+async function recheck_blockers(
+	reads: ReadonlyArray<ChildRead>,
+	child_numbers: ReadonlyArray<number>,
+	known: ReadonlyMap<number, EpicChild>,
+	repo: string,
+): Promise<ReadonlyArray<ChildRead>> {
+	const waited = epic_child_source.waited_closed(to_children(reads), known, repo)
+	if (waited.size === 0) return reads
+
+	const fresh = await read_children([...waited], repo)
+
+	return reads.map((read, index) => fresh.get(child_numbers[index] ?? 0) ?? read)
+}
+
+// Every child the epic's task list tracks, in the order the body lists them. Given a `source`, a
+// child it already knows is not read again (`epic-child-source.ts`).
 async function fetch_children(
 	child_numbers: ReadonlyArray<number>,
 	repo: string,
 	scope?: string,
+	source?: ChildSource,
 ): Promise<FetchedChildren> {
 	const limited = child_numbers.slice(0, CHILD_LIMIT)
-	const reads = await Promise.all(
-		limited.map(async (issue_number) => await fetch_child_read(issue_number, repo, scope)),
-	)
+	const now_ms = Date.now()
+	const known = epic_child_source.known(source, repo, now_ms)
+	const answered = await answer_children(limited, known, repo, scope)
+	const reads = await recheck_blockers(answered, limited, known, repo)
+
+	epic_child_source.remember_closed(source, repo, to_children(reads), now_ms)
 
 	return {
 		children: to_children(reads),
@@ -212,8 +285,27 @@ async function fetch_children(
 	}
 }
 
-// The children that live in other repositories, read by naming that repository in the read's REST
-// path (`repos/<owner>/<repo>/issues/<n>`). No local checkout is needed: their state is a GitHub
+// Each repository's children in one batch of their own, answered in the order given.
+async function read_external(
+	allowed: ReadonlyArray<ExternalChild>,
+): Promise<ReadonlyArray<ChildRead>> {
+	const repos = [...new Set(allowed.map((child) => child.repo))]
+	const batches = await Promise.all(
+		repos.map(async (repo) => {
+			const issue_numbers = allowed
+				.filter((child) => child.repo === repo)
+				.map((child) => child.number)
+
+			return await read_children(issue_numbers, repo, repo)
+		}),
+	)
+
+	return allowed.map((child) => batches[repos.indexOf(child.repo)]?.get(child.number) ?? NOT_READ)
+}
+
+// The children that live in other repositories, read by naming that repository — in one GraphQL
+// batch per repository, and in the REST path (`repos/<owner>/<repo>/issues/<n>`) for a child the
+// batch left unanswered. No local checkout is needed: their state is a GitHub
 // fact, and requiring a clone to learn it is what kept the auto-close from ever running on such an
 // epic.
 //
@@ -225,9 +317,7 @@ async function fetch_external_children(
 	const allowed = external.filter((child) =>
 		epic_cross_repo.is_same_owner_repo(child.repo, current_owner),
 	)
-	const reads = await Promise.all(
-		allowed.map(async (child) => await fetch_child_read(child.number, child.repo, child.repo)),
-	)
+	const reads = await read_external(allowed)
 
 	// A repository the owner restriction refused is reported as unreadable rather than dropped: an
 	// epic must not read as complete while a child nobody may look at is still open.
@@ -336,6 +426,7 @@ async function fetch_epic(
 	epic_number: number,
 	repo: string,
 	current_repo: string = repo,
+	source?: ChildSource,
 ): Promise<EpicSnapshot> {
 	const scope = scope_for(repo, current_repo)
 	const epic_body = await fetch_epic_body(epic_number, scope)
@@ -343,7 +434,7 @@ async function fetch_epic(
 	// runs in. Derived from the epic's own repository instead, a qualified reference to somebody else's
 	// epic would make their whole organization readable.
 	const owner = epic_cross_repo.owner_of(current_repo)
-	const local = await fetch_children(epic_body.child_numbers, repo, scope)
+	const local = await fetch_children(epic_body.child_numbers, repo, scope, source)
 	const remote = await fetch_external_children(epic_body.external, owner)
 
 	return await to_snapshot(epic_body, { repo, current_repo }, local, remote)
@@ -363,6 +454,7 @@ const epic_fetch = {
 	missing_children,
 	fetch_child,
 	fetch_children,
+	fetch_external_children,
 	fetch_epic,
 }
 

package/scripts/epic/epic-graph.ts

@@ -28,6 +28,7 @@ import {
 // The author fields (`AuthorFields`) are read only by `backlog:next`, which offers a child only when
 // its author has write access (joshuafolkken/kit#4633); absent on rows built without a read.
 interface EpicChild extends AuthorFields {
+	is_resumable?: boolean | undefined
 	number: number
 	repo: string
 	state: 'OPEN' | 'CLOSED'

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

@@ -1,7 +1,9 @@
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
-import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_etag_read } from '#scripts/gh/git-gh-etag-read'
 import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { json_value } from '#scripts/lib/json-value'
 import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+import { z } from 'zod'
 
 // 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
@@ -15,36 +17,75 @@ import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 const STALE_MINUTES = 90
 const TIMELINE_PAGE = 100
 
-const LABELED_FILTER = `.[] | select(.event == "labeled" and (.label.name | ascii_downcase) == "${IN_PROGRESS_LABEL}") | .created_at`
+const LABELED_EVENT = 'labeled'
+const UNPARSED_TIMELINE_MESSAGE = 'timeline did not parse'
+
+const label_schema = z.object({ name: z.string() })
+
+const timeline_schema = z.array(
+	z.object({
+		event: z.string().nullish(),
+		created_at: z.string().nullish(),
+		label: label_schema.nullish(),
+	}),
+)
+
+type TimelineEvent = z.infer<typeof timeline_schema>[number]
 
 // The newest time the label was applied. `absent` is a timeline holding no such event — the label is
 // older than what the timeline keeps — and `unread` is a timeline that could not be read at all. Kept
 // apart because only the first is a reason to call the label stale.
 type LabeledAt = { kind: 'at'; at: string } | { kind: 'absent' } | { kind: 'unread' }
 
+function parse_events(raw: string): Array<unknown> {
+	const events = json_value.parse_array(raw)
+
+	if (events === undefined) throw new Error(UNPARSED_TIMELINE_MESSAGE)
+
+	return events
+}
+
+// The timeline in one page while it fits in one, sent with the previous process's ETag: `epic:next`
+// offers every minute, and a holder's timeline rarely moves between offers (joshuafolkken/kit#6636).
+async function read_timeline(path: string): Promise<Array<unknown>> {
+	return parse_events(await git_gh_etag_read.read_listing(path, TIMELINE_PAGE))
+}
+
+function is_in_progress_labeling(event: TimelineEvent): boolean {
+	return event.event === LABELED_EVENT && event.label?.name.toLowerCase() === IN_PROGRESS_LABEL
+}
+
 async function read_labeled_at(issue: number, repo: string): Promise<LabeledAt> {
 	try {
-		const raw = await git_gh_exec.exec_gh_api({
-			path: `${git_gh_api_path.issue_api_path(String(issue), repo)}/timeline?per_page=${String(TIMELINE_PAGE)}`,
-			should_paginate: true,
-			jq_filter: LABELED_FILTER,
-		})
-		const at = raw.split('\n').findLast((line) => line.trim() !== '')
-
-		return at === undefined ? { kind: 'absent' } : { kind: 'at', at }
+		const path = `${git_gh_api_path.issue_api_path(String(issue), repo)}/timeline?per_page=${String(TIMELINE_PAGE)}`
+		const events = timeline_schema.parse(await read_timeline(path))
+		const at = events.findLast((event) => is_in_progress_labeling(event))?.created_at
+
+		return typeof at === 'string' ? { kind: 'at', at } : { kind: 'absent' }
 	} catch {
 		return { kind: 'unread' }
 	}
 }
 
+function minutes_since(at: string, now: Date): number {
+	return Math.floor((now.getTime() - Date.parse(at)) / MS_PER_MINUTE)
+}
+
+// Whether the label is past the window. An unread timeline is never stale: nothing is known about it.
+function is_stale(labeled_at: LabeledAt, now: Date): boolean {
+	if (labeled_at.kind === 'unread') return false
+	if (labeled_at.kind === 'absent') return true
+
+	return minutes_since(labeled_at.at, now) > STALE_MINUTES
+}
+
 function age_text(labeled_at: LabeledAt, now: Date): string {
 	if (labeled_at.kind === 'unread') return 'label age unread'
 	if (labeled_at.kind === 'absent') return `${IN_PROGRESS_LABEL} older than the timeline — stale`
 
-	const minutes = Math.floor((now.getTime() - Date.parse(labeled_at.at)) / MS_PER_MINUTE)
-	const stale = minutes > STALE_MINUTES ? ' — stale' : ''
+	const stale = is_stale(labeled_at, now) ? ' — stale' : ''
 
-	return `${IN_PROGRESS_LABEL} for ${String(minutes)} min${stale}`
+	return `${IN_PROGRESS_LABEL} for ${String(minutes_since(labeled_at.at, now))} min${stale}`
 }
 
 async function read_ages(
@@ -66,6 +107,7 @@ async function read_ages(
 const epic_label_age = {
 	STALE_MINUTES,
 	read_labeled_at,
+	is_stale,
 	age_text,
 	read_ages,
 }

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

@@ -0,0 +1,75 @@
+import type { OpenIssueData } from '#scripts/git/git-schemas'
+import { has_any_label, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_room, type LaneRoom, type LaneUse } from '#scripts/lane/lane-room'
+import type { BusyRead } from './epic-busy'
+
+interface OccupancyRead {
+	read: BusyRead
+	use?: LaneUse
+}
+
+const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
+
+function is_local(issue: OpenIssueData, lanes: ReadonlyArray<LaneInfo>): boolean {
+	return lanes.some((lane) => lane.issue === String(issue.number))
+}
+
+// Unknown state or seat ownership is never evidence that a labelled holder stopped.
+function confirmed_stopped(lanes: ReadonlyArray<LaneInfo>, room: LaneRoom): ReadonlySet<string> {
+	const occupied = new Set(room.occupied.map((lane) => lane.issue))
+
+	return new Set(
+		lanes
+			.filter((lane) => !lane.seat_held && lane.seat_problem === undefined)
+			.map((lane) => lane.issue)
+			.filter(
+				(issue) =>
+					room.idle.includes(issue) && !room.unknown.includes(issue) && !occupied.has(issue),
+			),
+	)
+}
+
+function reconcile(
+	issues: ReadonlyArray<OpenIssueData>,
+	lanes: ReadonlyArray<LaneInfo>,
+	room: LaneRoom,
+): OccupancyRead {
+	const stopped = confirmed_stopped(lanes, room)
+	// Only epic_solo_stale's reconfirmed release may drop a solo holder across a cut.
+	const holders = issues.filter(
+		(issue) => has_any_label(issue.labels, SOLO_LABELS) || !stopped.has(String(issue.number)),
+	)
+	const remote = holders.filter((issue) => !is_local(issue, lanes)).length
+	const occupied = new Set(room.occupied.map((lane) => lane.issue))
+	const unknown = holders.filter(
+		(issue) => room.unknown.includes(String(issue.number)) && !occupied.has(String(issue.number)),
+	).length
+	const use = {
+		...room.use,
+		occupied: room.use.occupied + remote + unknown,
+		seated: room.use.seated + remote,
+	}
+
+	return { read: holders.length > 0 ? { kind: 'busy', issues: holders } : { kind: 'idle' }, use }
+}
+
+// Reuse the board/drive snapshot only for this repository's locally registered holders.
+// Unseen machines and failed local reads retain the label-based conservative answer.
+async function read(reading: BusyRead, is_this_checkout: boolean): Promise<OccupancyRead> {
+	if (!is_this_checkout || reading.kind !== 'busy') return { read: reading }
+
+	try {
+		const lanes = await lane_registry.list_lanes()
+		if (reading.issues.every((issue) => !is_local(issue, lanes))) return { read: reading }
+
+		return reconcile(reading.issues, lanes, await lane_room.read(lanes))
+	} catch {
+		return { read: reading }
+	}
+}
+
+const epic_lane_occupancy = { read }
+
+export { epic_lane_occupancy }
+export type { OccupancyRead }

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

@@ -8,6 +8,7 @@ import {
 } from './epic-candidate-confirm'
 import { epic_graph, type EpicChild } from './epic-graph'
 import { epic_label_age } from './epic-label-age'
+import { epic_lane_occupancy, type OccupancyRead } from './epic-lane-occupancy'
 import { epic_rank } from './epic-rank'
 import type { EpicVerdict } from './epic-report'
 import { epic_solo } from './epic-solo'
@@ -17,7 +18,7 @@ import { epic_triage, type TriageVerdict } from './epic-triage'
 // Which children a repository has room to start right now.
 //
 // A lane is its own checkout, so the question is how many are free — the repository's occupancy
-// counted from GitHub, compared against `lane_capacity`'s limit.
+// read from GitHub and reconciled with the local snapshot against `lane_capacity`'s limit.
 //
 // **The pool takes several sources, and none of them is an epic.** `RepoPool` is a candidate list
 // with the context needed to confirm it. `epic:next` builds one per named epic and passes them all;
@@ -88,6 +89,18 @@ async function merge_waiting_holders(read: BusyRead, request: LaneRequest): Prom
 	)
 }
 
+async function room_in(occupancy: OccupancyRead, request: LaneRequest): Promise<number> {
+	if (occupancy.use !== undefined) {
+		return lane_capacity.free_lanes(request.limit, occupancy.use.occupied, occupancy.use.seated)
+	}
+
+	return free_lanes(
+		occupancy.read,
+		request.limit,
+		await merge_waiting_holders(occupancy.read, request),
+	)
+}
+
 function wanted_of(request: LaneRequest, free: number): number {
 	return request.is_all_lanes ? free : Math.min(ONE_LANE, free)
 }
@@ -216,11 +229,17 @@ async function collect(
 // `run:solo` child never opens a lane beside another one on either path.
 function solo_offer(
 	answer: { children: ReadonlyArray<EpicChild>; verdict: EpicVerdict },
-	read: BusyRead,
+	occupancy: OccupancyRead,
 	request: LaneRequest,
 	ages: ReadonlyMap<number, string>,
 ): LaneOffer {
-	const { offered, notice = '' } = epic_solo.select(answer.children, read, request.repo)
+	const { read, use } = occupancy
+	const { offered, notice = '' } = epic_solo.select(
+		answer.children,
+		read,
+		request.repo,
+		use?.occupied,
+	)
 
 	if (offered.length === NO_LANES && answer.children.length > NO_LANES) {
 		return { children: [], verdict: WAIT_VERDICT, notice }
@@ -254,35 +273,52 @@ function triage_offer(pools: ReadonlyArray<RepoPool>, request: LaneRequest): Lan
 	}
 }
 
-async function offer_for_repo(
-	pools: ReadonlyArray<RepoPool>,
+function full_notice(
+	occupancy: OccupancyRead,
 	request: LaneRequest,
-): Promise<LaneOffer> {
-	const triage = triage_offer(pools, request)
+	ages: ReadonlyMap<number, string>,
+): string {
+	if (occupancy.use === undefined) {
+		return epic_busy.busy_reason(occupancy.read, request.repo, request.limit, ages)
+	}
 
-	if (triage !== undefined) return triage
+	return `${String(occupancy.use.occupied)} of ${String(request.limit)} lanes in use in ${request.repo}; ${String(occupancy.use.seated)} port seats held. No lane is free, so nothing is offered here.`
+}
 
-	const { read, notice } = await epic_solo_stale.release(
+async function offer_after_triage(
+	pools: ReadonlyArray<RepoPool>,
+	request: LaneRequest,
+): Promise<LaneOffer> {
+	const released = await epic_solo_stale.release(
 		await epic_busy.read_repository(request.repo),
 		request.repo,
 	)
 
-	if (notice !== undefined) console.error(notice)
+	if (released.notice !== undefined) console.error(released.notice)
 
-	const free = free_lanes(read, request.limit, await merge_waiting_holders(read, request))
+	const occupancy = await epic_lane_occupancy.read(released.read, request.is_this_checkout)
+	const { read } = occupancy
+	const free = await room_in(occupancy, request)
 	const ages = await holder_ages(read, request.repo)
 
 	if (free === NO_LANES) {
 		return {
 			children: [],
 			verdict: WAIT_VERDICT,
-			notice: epic_busy.busy_reason(read, request.repo, request.limit, ages),
+			notice: full_notice(occupancy, request, ages),
 		}
 	}
 
 	const for_repo = dedupe_pools(pools.map((pool) => ranked_in(pool, request.repo)))
 
-	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request, ages)
+	return solo_offer(await collect(for_repo, wanted_of(request, free)), occupancy, request, ages)
+}
+
+async function offer_for_repo(
+	pools: ReadonlyArray<RepoPool>,
+	request: LaneRequest,
+): Promise<LaneOffer> {
+	return triage_offer(pools, request) ?? (await offer_after_triage(pools, request))
 }
 
 // A `--repo` compared against the repository this command runs in, case-insensitively as GitHub

package/scripts/epic/epic-main.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
+import { epic_command } from './epic'
+
+// The `josh epic` entry, kept apart from `epic.ts` because `run:split` imports that one: a bundle is
+// one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186). `process.exitCode` rather than `process.exit()`, so the report on standard
+// output drains first.
+//
+// A `gh` failure carries its stderr as the message, which is the useful part; printing it alone
+// keeps a routine "not authenticated" or "label not found" from arriving as a stack trace.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+	const FAILURE_EXIT_CODE = 1
+
+	try {
+		process.exitCode = await epic_command.run(process.argv.slice(ARGV_OFFSET))
+	} catch (error) {
+		console.error(`✖ ${error_text.message_of(error)}`)
+		process.exitCode = FAILURE_EXIT_CODE
+	}
+}

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

@@ -7,10 +7,8 @@ import { epic_next } from './epic-next'
 // 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.
+// `.env` is read here, inside the guard, so a developer's own `.env` cannot decide what the unit
+// tests see (`josh-environment-file.ts`).
 //
 // `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