@joshuafolkken/kit 1.872.0

package/scripts/epic/epic-index.ts

@@ -0,0 +1,209 @@
+import { git_epic_parse } from '#scripts/git/git-epic-parse'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
+import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { z } from 'zod'
+
+// Which epic tracks which issue — the one answer, in one place (joshuafolkken/kit#1633).
+//
+// `epic:bundle` has asked it since joshuafolkken/kit#873, to keep an issue an epic already tracks
+// from being recommended a second one. The `auto-ok` pickup needs the same answer for the opposite
+// reason: an issue tracked by an epic that will offer it must run through that epic's order and
+// never be picked up standalone. Two callers, one question, so the read and the index live here
+// rather than in either command — a second copy would drift the first time the task-list shape
+// moved. `withheld_children` below is where the *second* half of that answer lives: which of the
+// tracked children the standalone half actually has to hold back.
+
+const epic_schema = z.object({ number: z.number(), body: z.string().nullable() })
+
+interface FetchedEpics {
+	epics: Array<{ number: number; body: string }>
+	// The listing can be cut short. An epic past the cut is invisible, so an issue it tracks reads as
+	// tracked by nothing — which is a duplicate epic for `epic:bundle` and an out-of-order run for the
+	// `auto-ok` pickup. Both callers report it rather than answering as if the listing were complete.
+	cutoff: ScanCutoff
+}
+
+// Which epics track each issue, from the epics' own task lists. **A child can be named by more than
+// one** (joshuafolkken/kit#1694): a task list expresses at most one epic per row, and nothing stops
+// two epics writing the same row — `epic_lane_offer.dedupe_pools` has handled exactly that collision
+// on the `epic:next` side since it was written. So the tracking is recorded whole here, and each
+// caller collapses it for its own question rather than losing the other epics at build time.
+//
+// A child a single epic lists twice repeats that epic's number, which neither caller distinguishes
+// from listing it once.
+function build_tracking_index(
+	epics: ReadonlyArray<{ number: number; body: string }>,
+): Map<number, ReadonlyArray<number>> {
+	const index = new Map<number, ReadonlyArray<number>>()
+
+	for (const epic of epics) {
+		for (const child of git_epic_parse.parse_task_list_issue_numbers(epic.body)) {
+			index.set(child, [...(index.get(child) ?? []), epic.number])
+		}
+	}
+
+	return index
+}
+
+// Which *one* epic tracks each issue — `epic:bundle`'s question, which asks whether the issue is
+// already in an epic and names it. The last epic to list the child wins, exactly as it did when this
+// was built by a single `index.set` per row, so a collision answers as it always has.
+function build_epic_index(
+	epics: ReadonlyArray<{ number: number; body: string }>,
+): Map<number, number> {
+	const index = new Map<number, number>()
+
+	for (const [child, tracked_by] of build_tracking_index(epics)) {
+		const winner = tracked_by.at(-1)
+		if (winner !== undefined) index.set(child, winner)
+	}
+
+	return index
+}
+
+const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
+
+// Which epics in the opted-in listing stand for their children. An epic that carries `auto-ok` is a
+// row of that listing which also carries `epic`, so no second read of an epic's labels is made.
+function opted_in_epic_numbers(issues: ReadonlyArray<OpenIssueData>): ReadonlySet<number> {
+	return new Set(
+		issues.filter((issue) => has_any_label(issue.labels, EPIC_LABELS)).map((issue) => issue.number),
+	)
+}
+
+// The reverse of the tracking index — which children each epic lists, keyed by the epic. `index`
+// answers child → its tracking epics; the closure walk below needs epic → its children, so the
+// mapping is inverted once here rather than scanned per step.
+function push_child(map: Map<number, Array<number>>, parent: number, child: number): void {
+	map.set(parent, [...(map.get(parent) ?? []), child])
+}
+
+function invert_tracking(
+	index: ReadonlyMap<number, ReadonlyArray<number>>,
+): Map<number, Array<number>> {
+	const children_of = new Map<number, Array<number>>()
+
+	for (const [child, parents] of index) {
+		for (const parent of parents) push_child(children_of, parent, child)
+	}
+
+	return children_of
+}
+
+// An epic's children that are themselves epics — the only edges the closure walk follows. A child is
+// an epic when it lists children of its own, so it is a key of the inverted index; a plain leaf child
+// is never chased, and a childless nested epic has nothing to expand and drops out with no cost.
+function child_epics_of(
+	children_of: ReadonlyMap<number, ReadonlyArray<number>>,
+	epic: number,
+): ReadonlyArray<number> {
+	return (children_of.get(epic) ?? []).filter((child) => children_of.has(child))
+}
+
+// Every epic an `auto-ok` root opts in — the root itself and, transitively, every nested epic reached
+// through its task list and theirs in turn (joshuafolkken/kit#2244). A person puts `auto-ok` on a root
+// to approve everything under it, and the direct-children-only reading (joshuafolkken/kit#1668) stopped
+// one level short: a grandchild fell out as "not opted in", though the same reasoning that admits the
+// child admits it. So the root's approval is read down the whole subtree rather than one level of it.
+//
+// **Unlimited depth, and it terminates.** The epic graph is finite — every node is an open epic, capped
+// at the listing limit — so no depth bound is needed to stop the walk; the `visited` set turns a cycle
+// or a self-reference into a node already seen rather than an edge walked again, and an epic reachable
+// through two roots is added once by that same set.
+function reachable_epic_numbers(
+	index: ReadonlyMap<number, ReadonlyArray<number>>,
+	opted_in: ReadonlyArray<OpenIssueData>,
+): ReadonlySet<number> {
+	const children_of = invert_tracking(index)
+	const visited = new Set<number>()
+	const stack = [...opted_in_epic_numbers(opted_in)]
+
+	while (stack.length > 0) {
+		const epic = stack.pop()
+		if (epic === undefined || visited.has(epic)) continue
+		visited.add(epic)
+		stack.push(...child_epics_of(children_of, epic).filter((child) => !visited.has(child)))
+	}
+
+	return visited
+}
+
+// **Which wins when an epic's declared order and a child's own `auto-ok` disagree — the single
+// source** (joshuafolkken/kit#1668, narrowing joshuafolkken/kit#1633).
+//
+// The epic wins wherever the epic is actually going to offer the child, and only there. So the
+// standalone half withholds a tracked child when the epic tracking it carries `auto-ok`: that epic's
+// `blocked-by` graph sequences its children, and offering the child standalone as well would both
+// skip that order and hand the same issue over twice.
+//
+// It withholds nothing when the tracking epic is **not** opted in. joshuafolkken/kit#1633 dropped
+// that child too, on the ground that the standalone path read none of the ordering graph — which has
+// since stopped being true: `auto_ok_cli.is_runnable` refuses a candidate whose `blockedBy` is still
+// open, and `josh epic --ordered` records an epic's declared order as exactly those native
+// relations. So the order survives the standalone route, while the old rule left a person's `auto-ok`
+// on the child silently inert — no path offered it at all, because the epic side never reads an epic
+// that did not opt in.
+// **It answers with the epic, not merely with membership**, because the withholding and the sentence
+// `backlog:plan` prints about it have to come from one answer. Handing the scope layer the whole
+// index instead let it name an epic that was not withholding anything — the same misreport, moved.
+//
+// **Any one opted-in epic withholds the child** (joshuafolkken/kit#1694). It reads the whole tracking
+// rather than one collapsed winner because the two are not the same answer when two epics name the
+// same child: collapsed, an opted-in epic that merely came earlier in the listing is gone, the child
+// reads as tracked by nobody who would offer it, and the standalone half hands it over while the
+// opted-in epic hands it over too. The epic named as the reason is the first opted-in one in listing
+// order — any of them is withholding it, and picking by position keeps the sentence deterministic.
+//
+// **The opted-in set is the transitive closure, not one level of it** (joshuafolkken/kit#2244). A
+// child of a nested epic is withheld from the standalone half exactly when that nested epic is one the
+// backlog is going to offer — which, since the closure reaches it, it now is. Withholding only the
+// direct roots' children here would leave a nested epic's child offered both through the epic and
+// standalone, the double-offer this whole rule exists to prevent.
+function withheld_children(
+	index: ReadonlyMap<number, ReadonlyArray<number>>,
+	opted_in: ReadonlyArray<OpenIssueData>,
+): ReadonlyMap<number, number> {
+	const epics = reachable_epic_numbers(index, opted_in)
+	const withheld = new Map<number, number>()
+
+	for (const [child, tracked_by] of index) {
+		const epic = tracked_by.find((candidate) => epics.has(candidate))
+		if (epic !== undefined) withheld.set(child, epic)
+	}
+
+	return withheld
+}
+
+// The epics currently open, so an issue can be matched to the one already tracking it.
+//
+// A failed read is reported rather than treated as "there are no epics": without the list, every
+// tracked child reads as untracked, and both callers then act confidently on an answer built from a
+// response nobody parsed.
+async function fetch_epics(limit: number): Promise<FetchedEpics | undefined> {
+	const { json, is_capped } = await git_gh_command.issue_list_by_label(EPIC_LABEL, limit)
+	if (json === undefined) return undefined
+	// Not `parse_json_array_safe`: it answers `[]` for a response that is not JSON at all, which is
+	// indistinguishable from "no epics are open" — the silent absence this whole rule is about.
+	const rows = parse_json_array_or_undefined(json, epic_schema)
+	if (rows === undefined) return undefined
+
+	return {
+		cutoff: cutoff_of(rows.length, limit, is_capped),
+		epics: rows.map((row) => ({ number: row.number, body: row.body ?? '' })),
+	}
+}
+
+const epic_index = {
+	build_epic_index,
+	build_tracking_index,
+	fetch_epics,
+	opted_in_epic_numbers,
+	reachable_epic_numbers,
+	withheld_children,
+}
+
+export { epic_index, epic_schema }
+export type { FetchedEpics }

package/scripts/epic/epic-issue.ts

@@ -0,0 +1,172 @@
+import type { IssueReference } from '#scripts/git/git-epic-reference'
+import { git_gh_issue_rest } from '#scripts/git/git-gh-issue-rest'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { blocked_by_schema } from '#scripts/git/schemas'
+import { z } from 'zod'
+
+// The shapes one issue is read as, and the argument every epic command takes.
+//
+// The read goes through `gh api` (REST) since joshuafolkken/kit#1024; `git-gh-issue-rest.ts` maps
+// the response back into the field names `gh issue view --json …` used, so the shapes below are
+// the ones they always were.
+//
+// Single-sourced because three commands read the same JSON and take the same argument. Each had its
+// own copy of the schema, the `blockedBy` unwrapping and the number parser, which is three places to
+// fix the next time `gh` changes shape — and the one place a divergence would not be noticed
+// (joshuafolkken/kit#862).
+
+const label_schema = z.object({ name: z.string() })
+
+const CLOSED = 'CLOSED'
+const OPEN = 'OPEN'
+const UNKNOWN_STATE = 'UNKNOWN'
+const PULL_REQUEST_SEGMENT = '/pull/'
+
+// Every field any epic command reads. Only `number` is required: a child reported with a field
+// missing is still a child, and dropping it would hide it from the view a decision is made from.
+// `body` is nullable as a guard: REST answers JSON null for an issue with none, and
+// `git-gh-issue-rest.ts` already maps that to an empty string before this schema sees it.
+const epic_issue_schema = z.object({
+	number: z.number(),
+	title: z.string().default(''),
+	body: z
+		.string()
+		.nullable()
+		.default('')
+		.transform((value) => value ?? ''),
+	state: z.string().default(UNKNOWN_STATE),
+	// The issue endpoint answers for a pull request as readily as for an issue, and nothing in the
+	// other fields separates them — an open PR reports `state: OPEN`, a merged one `MERGED`. The URL
+	// is what says which it is: `/pull/<n>` against `/issues/<n>` (joshuafolkken/kit#947).
+	url: z.string().default(''),
+	labels: z.array(label_schema).default([]),
+	blockedBy: blocked_by_schema,
+})
+
+type EpicIssue = z.infer<typeof epic_issue_schema>
+
+// A shape surprise reads as an unreadable issue rather than throwing: `gh`'s JSON is somebody else's
+// contract, and these commands are what a run consults before it starts.
+function parse_epic_issue(raw: string | undefined): EpicIssue | undefined {
+	if (raw === undefined) return undefined
+
+	try {
+		return parse_json_object_safe(raw, epic_issue_schema)
+	} catch {
+		return undefined
+	}
+}
+
+// The blockers an issue declares, unwrapped from the connection and carrying the repository each one
+// lives in (joshuafolkken/kit#1126).
+//
+// `fallback_repo` is what an unqualified relation has always meant: the repository the issue itself is
+// read in. REST names the blocker's repository in `repository_url`, and a relation may cross one — so
+// keeping only the number resolved every blocker against the blocked issue's own repository, which
+// named a different issue or none at all.
+//
+// The parameter is narrowed to the one field this reads, so a caller holding a differently-shaped
+// issue — `backlog-pool.ts`'s standalone rows arrive as `OpenIssueData` — resolves through this same
+// function instead of repeating the `repository_url` unwrapping (joshuafolkken/kit#1654).
+function blocker_references_of(
+	issue: Pick<EpicIssue, 'blockedBy'>,
+	fallback_repo = '',
+): Array<IssueReference> {
+	return (issue.blockedBy?.nodes ?? []).map((blocker) =>
+		git_gh_issue_rest.reference_of_blocker(blocker, fallback_repo),
+	)
+}
+
+// The same blockers as bare numbers, for the callers that predate the qualified read: the planner and
+// the bundler. A projection of the read above rather than a second unwrapping of the connection.
+//
+// **The number alone is lossy, and those callers inherit that.** A blocker in another repository
+// collapses to its number here and can then match a local issue that happens to share it —
+// joshuafolkken/kit#1130 carries the case, which is `epic:bundle` reading a false relation and
+// recording one onto the wrong issue. It predates joshuafolkken/kit#1126 rather than being introduced
+// by it, and threading the repository through the bundler is its own change with its own reach.
+function blockers_of(issue: EpicIssue): Array<number> {
+	return blocker_references_of(issue).map((blocker) => blocker.number)
+}
+
+function label_names(issue: EpicIssue): Array<string> {
+	return issue.labels.map((label) => label.name)
+}
+
+// `OPEN` or `CLOSED`, whatever casing the state arrived in.
+//
+// Anything that is not `CLOSED` reads as open, which is right for the auto-close it was written for:
+// a child in any other state still has work left. It is **not** a test for "this issue is open" —
+// `MERGED` maps to `OPEN` here — so a caller that needs that must ask `is_open` instead.
+function normalize_state(state: string): 'OPEN' | 'CLOSED' {
+	return state.toUpperCase() === CLOSED ? CLOSED : 'OPEN'
+}
+
+// Strictly open: exactly `OPEN`, so `MERGED` (a pull request) and the `UNKNOWN` default of a read
+// that came back shaped wrong both answer false rather than passing as an open issue.
+function is_open(state: string): boolean {
+	return state.toUpperCase() === OPEN
+}
+
+// Whether the number answered with a pull request rather than an issue. The issue endpoint
+// (`repos/{owner}/{repo}/issues/{N}`) serves both.
+function is_pull_request(issue: EpicIssue): boolean {
+	return issue.url.includes(PULL_REQUEST_SEGMENT)
+}
+
+// `#123` and `123` are both accepted: the number is copied out of an issue reference as often as it
+// is typed. `owner/repo#123` is refused rather than read as `123`, which would answer about *this*
+// repository's issue of that number — a different issue entirely.
+function parse_epic_number(raw = ''): number | undefined {
+	if (raw.includes('/')) return undefined
+	const parsed = Number(raw.replace('#', ''))
+
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined
+}
+
+// An epic reference: `858`, `#858`, or `owner/repo#858` for an epic in another repository.
+//
+// A cross-repository epic must be qualified. A bare `#858` resolves to *this* repository's issue 858
+// — a different issue entirely — so reading it as the other repository's would silently point at the
+// wrong thing (joshuafolkken/kit#864).
+interface EpicReference {
+	repo?: string
+	number: number
+}
+
+const QUALIFIED_REFERENCE = /^([\w.-]+\/[\w.-]+)#(\d+)$/u
+const QUALIFIED_REPO_GROUP = 1
+const QUALIFIED_NUMBER_GROUP = 2
+
+function to_qualified_reference(match: RegExpExecArray): EpicReference | undefined {
+	const repo = match[QUALIFIED_REPO_GROUP]
+	if (repo === undefined) return undefined
+	const number = Number(match[QUALIFIED_NUMBER_GROUP])
+
+	return Number.isSafeInteger(number) && number > 0 ? { repo, number } : undefined
+}
+
+function parse_epic_reference(raw = ''): EpicReference | undefined {
+	const match = QUALIFIED_REFERENCE.exec(raw.trim())
+	if (match !== null) return to_qualified_reference(match)
+	const number = parse_epic_number(raw)
+
+	return number === undefined ? undefined : { number }
+}
+
+const epic_issue = {
+	CLOSED,
+	blocker_references_of,
+	UNKNOWN_STATE,
+	parse_epic_issue,
+	blockers_of,
+	label_names,
+	normalize_state,
+	is_open,
+	is_pull_request,
+	parse_epic_number,
+	parse_epic_reference,
+}
+
+export type { EpicIssue, EpicReference }
+export { epic_issue }

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

@@ -0,0 +1,207 @@
+import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { epic_busy, type BusyRead } from './epic-busy'
+import {
+	epic_candidate_confirm,
+	type ConfirmContext,
+	type RepoAnswer,
+} from './epic-candidate-confirm'
+import { epic_graph, type EpicChild } from './epic-graph'
+import type { EpicVerdict } from './epic-report'
+
+// Which children a repository has room to start right now (joshuafolkken/kit#1491).
+//
+// Until joshuafolkken/kit#1490 the answer was one or none: the contended resource was one working
+// tree, so a single `in-progress` issue excluded everything else in that repository. A lane is its
+// own checkout, so the question became how many are free — the repository's occupancy counted from
+// GitHub, compared 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. Since joshuafolkken/kit#1493 `epic:next` builds one per
+// named epic and passes them all, which cost the caller change this design predicted and no rewrite
+// of the scheduler: the signatures never learned what an epic is, because once the guarded resource
+// is the lane rather than the repository, which epic a child came from stops mattering. The one
+// thing several sources did add is `dedupe_pools` below — two epics can name the same child, and one
+// child is one lane.
+
+const WAIT_VERDICT: EpicVerdict = 'wait'
+const RUN_VERDICT: EpicVerdict = 'run'
+const NO_LANES = 0
+const ONE_LANE = 1
+
+// One source of candidates, with what confirming them needs. The context carries the graph a
+// candidate is re-classified against, which is per-source by construction — two epics are two pools,
+// each confirmed against its own graph.
+interface RepoPool {
+	candidates: ReadonlyArray<EpicChild>
+	context: ConfirmContext
+}
+
+// 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.
+interface LaneRequest {
+	repo: string
+	limit: number
+	is_all_lanes: boolean
+}
+
+// The answer for one repository: the children to start, the verdict standing in their place when
+// there are none, and the line explaining either. The notice goes to standard error — standard
+// output carries issue numbers or a verdict and nothing else.
+interface LaneOffer {
+	children: ReadonlyArray<EpicChild>
+	verdict: EpicVerdict
+	notice: string
+}
+
+// A read that could not see the whole listing authorizes nothing, whatever its count says. Kept as a
+// kind test rather than folded into the arithmetic: "I saw no holder" and "there are no holders"
+// differ, and only the first one is a reason to wait.
+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 wanted_of(request: LaneRequest, free: number): number {
+	return request.is_all_lanes ? free : Math.min(ONE_LANE, free)
+}
+
+// Said out loud because a run told only "wait" has nothing to go and look at, and because the
+// occupancy is the number a person tunes `JOSH_LANE_LIMIT` against.
+function withheld_message(repo: string): string {
+	return `No runnable child in ${repo}: every candidate was withheld when its blocker relations were confirmed — the reason for each is above.`
+}
+
+function offered_notice(
+	children: ReadonlyArray<EpicChild>,
+	read: BusyRead,
+	request: LaneRequest,
+): string {
+	if (children.length === NO_LANES) return withheld_message(request.repo)
+	if (read.kind !== 'busy') return ''
+
+	return epic_busy.occupancy_message(read.issues, request.repo, request.limit)
+}
+
+// Two pools that both offered nothing can disagree about why, and the answer has to be the one that
+// says what a caller should do. The order is `epic_report.decide_verdict`'s own — waiting before
+// stopping, because a run that stops while something is still resolving on its own gives up on an
+// epic that was going to finish — rather than a second ranking invented here.
+const VERDICT_PRIORITY: ReadonlyArray<EpicVerdict> = [RUN_VERDICT, WAIT_VERDICT, 'stop', 'complete']
+
+function combine_verdicts(left: EpicVerdict, right: EpicVerdict): EpicVerdict {
+	return VERDICT_PRIORITY.indexOf(left) <= VERDICT_PRIORITY.indexOf(right) ? left : right
+}
+
+// Every pool is a source of candidates **for the repository the request names**. The free-lane count
+// was read for that one repository, so spending it on a child that lives somewhere else would
+// allocate a lane nobody counted — the double-allocation joshuafolkken/kit#925 exists to prevent.
+// Dropped rather than offered: a caller with children in two repositories asks twice, once per
+// repository, exactly as `--repo` already makes it.
+function candidates_in(pool: RepoPool, repo: string): RepoPool {
+	return { ...pool, candidates: pool.candidates.filter((child) => child.repo === repo) }
+}
+
+// One pool's candidates, minus every one an earlier pool already carries. `seen` is mutated rather
+// than rebuilt because the earlier pools' claim is what the later one is filtered against.
+function unseen_candidates(pool: RepoPool, seen: Set<string>): RepoPool {
+	const candidates: Array<EpicChild> = []
+
+	for (const child of pool.candidates) {
+		const key = epic_graph.key_of(child)
+
+		if (seen.has(key)) continue
+		seen.add(key)
+		candidates.push(child)
+	}
+
+	return { ...pool, candidates }
+}
+
+// A child two epics both track is still one child, and entering it twice would open two lanes on one
+// issue — two branches, two pull requests, and the second one merging over the first
+// (joshuafolkken/kit#1493). Keyed through `epic_graph.key_of`, the one spelling of an issue's
+// identity in this package: a bare number names a different issue in another repository.
+//
+// **The earlier pool keeps it**, and that is a decision rather than an accident of iteration order.
+// The pool order is the order the epics were named, which is the only ranking a person typed. It
+// also settles what happens when the first pool *withholds* the child: it stays withheld, because a
+// `blocked-by` relation belongs to the issue rather than to the epic that lists it, so offering it
+// from the second pool would start work the first pool's confirmation had just refused.
+function dedupe_pools(pools: ReadonlyArray<RepoPool>): ReadonlyArray<RepoPool> {
+	const seen = new Set<string>()
+
+	return pools.map((pool) => unseen_candidates(pool, seen))
+}
+
+async function ask_pool(pool: RepoPool, wanted: number): Promise<RepoAnswer> {
+	return await epic_candidate_confirm.answer_for_repo(pool.candidates, pool.context, wanted)
+}
+
+// The pools walked in order until the free lanes are spoken for. The confirmation walk itself is
+// per-pool, so a candidate is still re-classified against its own graph; what this adds is that a
+// second pool is asked only for the lanes the first one left — and is not asked at all once there
+// are none, since a walk with no appetite would answer "every candidate was withheld" having
+// examined none of them.
+async function collect(
+	pools: ReadonlyArray<RepoPool>,
+	wanted: number,
+): Promise<{ children: ReadonlyArray<EpicChild>; verdict: EpicVerdict }> {
+	const children: Array<EpicChild> = []
+	let verdict: EpicVerdict = 'complete'
+
+	for (const pool of pools) {
+		if (children.length >= wanted) break
+
+		const answer = await ask_pool(pool, wanted - children.length)
+
+		children.push(...answer.children)
+		verdict = combine_verdicts(verdict, answer.verdict)
+	}
+
+	return { children, verdict: children.length > NO_LANES ? RUN_VERDICT : verdict }
+}
+
+// The repository is asked how full it is **before** any candidate is confirmed, for the reason
+// joshuafolkken/kit#1121 records: a repository with no free lane is handed nothing, so the relations
+// request that would confirm a candidate there buys an answer nobody reads — and a polling `epicrun`
+// would pay it every round.
+async function offer_for_repo(
+	pools: ReadonlyArray<RepoPool>,
+	request: LaneRequest,
+): Promise<LaneOffer> {
+	const read = await epic_busy.read_repository(request.repo)
+	const free = free_lanes(read, request.limit)
+
+	if (free === NO_LANES) {
+		return {
+			children: [],
+			verdict: WAIT_VERDICT,
+			notice: epic_busy.busy_reason(read, request.repo, request.limit),
+		}
+	}
+
+	const for_repo = dedupe_pools(pools.map((pool) => candidates_in(pool, request.repo)))
+	const answer = await collect(for_repo, wanted_of(request, free))
+
+	return { ...answer, notice: offered_notice(answer.children, read, request) }
+}
+
+const epic_lane_offer = {
+	is_held,
+	free_lanes,
+	wanted_of,
+	combine_verdicts,
+	candidates_in,
+	unseen_candidates,
+	dedupe_pools,
+	withheld_message,
+	collect,
+	offer_for_repo,
+}
+
+export type { LaneOffer, LaneRequest, RepoPool }
+export { epic_lane_offer }

package/scripts/epic/epic-nested.ts

@@ -0,0 +1,37 @@
+import { EPIC_LABEL, has_label_name } from '#scripts/git/issue-labels'
+import type { EpicChild } from './epic-graph'
+
+// Whether a task-list row points at another epic (joshuafolkken/kit#1476).
+//
+// An epic's body can hold `- [ ] #<another epic>` — nothing stops it being typed — and until this
+// module nothing read it. `epic-classify.ts` sorted the row like any other child and
+// `from_blockers` minted `runnable` for it, so `epicrun` handed an epic to `fullrun` as an ordinary
+// issue and the run had nothing to implement.
+//
+// Two callers ask the question and they must not answer it differently: the classification, which
+// **withholds** the row, and the audit, which **reports** it. Spelled twice they would drift, and a
+// row the audit called fine would then be one the classification refused, or the reverse.
+
+// **The test is the child's `epic` label, and nothing else.**
+//
+// It is deliberately not any reading of how the row is written. A row naming `owner/repo#N` is a
+// **different** property, and a legitimate one: such a row disables the epic auto-close by design,
+// which is why `CLAUDE.md` requires a cross-repository backlink to be written as prose rather than
+// as a task-list row. Collapsing the two would refuse the very shape that document asks for.
+//
+// The properties are orthogonal, and all four combinations are meant to work: a cross-repository
+// child that is not an epic stays runnable and unreported, and one that is an epic is withheld and
+// reported exactly like a local one.
+//
+// The comparison is case-insensitive because GitHub keeps the casing a label was created with and
+// treats `Epic` and `epic` as one label — a repository that predates these scripts can answer with
+// either spelling, and a row read by eye against the lowercase string is one nothing withholds.
+function is_nested_epic(child: EpicChild): boolean {
+	return has_label_name(child.labels, EPIC_LABEL)
+}
+
+const epic_nested = {
+	is_nested_epic,
+}
+
+export { epic_nested }