@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/epic/epic-bundle.ts

@@ -1,6 +1,7 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { epic_audit_logic, type SignalSection } from './epic-audit'
+import { epic_bundle_recommend } from './epic-bundle-recommend'
 import { epic_graph } from './epic-graph'
 import type { DependencyLink } from './epic-parse'
 import type { IssueReference } from './epic-reference'
@@ -55,6 +56,9 @@ interface BundleDecision {
 	epic?: number
 	// The epics the candidates are spread across, for `ask`.
 	epics: ReadonlyArray<number>
+	// The epic `ask` recommends (`epic-bundle-recommend.ts`). Absent on a cyclic declaration, which
+	// has no innermost epic and stays a person's choice.
+	recommended?: number
 	candidates: ReadonlyArray<number>
 	reason: string
 }
@@ -161,7 +165,7 @@ const NO_SIGNAL_REASON = 'no existing issue shares a reference or a dependency w
 // and an issue tracked by two epics gives the auto-close two task lists to disagree about.
 // The decision already carried the number; only this sentence dropped it.
 function already_tracked_reason(epic: number): string {
-	return `${issue_cite.plain(epic)} already tracks this issue`
+	return `${issue_cite.plain_for('linked', epic)} already tracks this issue`
 }
 
 const SPREAD_REASON =
@@ -173,7 +177,7 @@ function to_numbers(candidates: ReadonlyArray<BacklogIssue>): Array<number> {
 
 function create_decision(subject: BacklogIssue, numbers: ReadonlyArray<number>): BundleDecision {
 	const count = String(numbers.length)
-	const reason = `${issue_cite.plain(subject.number)} and ${count} related issue(s) belong to no epic`
+	const reason = `${issue_cite.plain_for('linked', subject.number)} and ${count} related issue(s) belong to no epic`
 
 	return { action: 'create_epic', epics: [], candidates: numbers, reason }
 }
@@ -241,12 +245,35 @@ function narrow_to_innermost(
 // reported without narrowing above, so a lone survivor of two or more means the graph was acyclic,
 // and there every dropped epic is a transitive parent of the one left.
 function tracks_reason(epic: number, involved: ReadonlyArray<number>): string {
-	const tracks = `${issue_cite.plain(epic)} already tracks a related issue`
+	const tracks = `${issue_cite.plain_for('linked', epic)} already tracks a related issue`
 	if (involved.length === 1) return tracks
 
 	return `${tracks}; the other epics the candidates sit in are its own parents`
 }
 
+// The spread verdict, carrying the epic it recommends unless the epics left sit on a cycle.
+function ask_decision(
+	epics: ReadonlyArray<number>,
+	candidates: ReadonlyArray<BacklogIssue>,
+	parents: ReadonlyMap<number, number>,
+): BundleDecision {
+	const has_cycle = is_cyclic(
+		epics,
+		epics.map((epic) => ancestors_of(epic, parents)),
+	)
+	const recommended = has_cycle
+		? undefined
+		: epic_bundle_recommend.recommend_epic(epics, candidates)
+
+	return {
+		action: 'ask',
+		epics,
+		candidates: to_numbers(candidates),
+		reason: SPREAD_REASON,
+		...(recommended !== undefined && { recommended }),
+	}
+}
+
 // Which of the three the candidates call for, once there is at least one.
 function decide_with_candidates(
 	subject: BacklogIssue,
@@ -256,7 +283,7 @@ function decide_with_candidates(
 	const numbers = to_numbers(candidates)
 	const involved = candidate_epics(candidates)
 	const epics = narrow_to_innermost(involved, parents)
-	if (epics.length > 1) return { action: 'ask', epics, candidates: numbers, reason: SPREAD_REASON }
+	if (epics.length > 1) return ask_decision(epics, candidates, parents)
 	const [epic] = epics
 	if (epic === undefined) return create_decision(subject, numbers)
 

package/scripts/epic/epic-busy.ts

@@ -1,7 +1,8 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import { has_any_label, IN_PROGRESS_LABEL, PARKED_LABELS } from '#scripts/issue/issue-labels'
+import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_run_hold } from '#scripts/issue/issue-run-hold'
 import { session_cite } from '#scripts/issue/session-cite'
 
 // How much of a repository's parallelism is already spoken for — asked of the *repository*, never of
@@ -16,19 +17,17 @@ import { session_cite } from '#scripts/issue/session-cite'
 // with its own branch and its own ports, so the question is not "is anything running" but "how many
 // are running" — and the answer is a count the caller compares against `lane_capacity`'s limit.
 //
-// **The count is read from GitHub, never kept in the session.** Two `epicrun`s counting to six in
+// **The holders are read from GitHub, never kept in the session.** Two `epicrun`s counting to six in
 // their own memory give twelve lanes; the label on an open issue is the one record both of them
 // read. It is an advisory guard rather than a mutex — the label is applied after the read, so two
 // sessions starting in the same instant can still take one seat twice. What it closes is the window
 // that actually occurs: a lane holding the label for minutes.
+// `epic-lane-occupancy.ts` reconciles these holders with the shared local snapshot before selection.
 
 // Wide enough that the cap is never what decides the answer: a repository with a hundred issues
 // carrying `in-progress` at once is already the state this guard exists to report.
 const LISTING_LIMIT = 100
 
-// Read through `has_any_label` rather than compared directly, for the casing reason
-// `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
-//
 // The park labels (`PARKED_LABELS`): `already-done` and `run:stalled` join `needs-decision` here for
 // the same reason they join it in `epic_classify.local_category`: the run that applied one leaves no
 // uncommitted work for the next child to start on top of. That is exactly what separates them from
@@ -160,8 +159,11 @@ function busy_reason(
 // one lane the run would poll instead of continuing. A child stopped by
 // `needs-human-review` is deliberately not parked and goes on holding its lane: its uncommitted work
 // is still sitting in that checkout.
-function is_parked(issue: OpenIssueData): boolean {
-	return has_any_label(issue.labels, PARKED_LABELS)
+//
+// Read through the shared reader (`issue-run-hold.ts`) that `run:add` and the board read too — the
+// listing's label filter only narrows what it is asked of.
+function is_holder(issue: OpenIssueData): boolean {
+	return issue_run_hold.is_held((issue.labels ?? []).map((label) => label.name))
 }
 
 // A listing that arrived, or a gap. The shared reader tells the two gaps apart — output that is not
@@ -184,7 +186,7 @@ function parse_listing(raw: string, is_capped: boolean): BusyRead {
 	const read = read_json_listing(raw, open_issue_schema)
 	if (read.kind !== 'read') return { kind: 'unreadable' }
 
-	const holders = read.rows.filter((row) => !is_parked(row))
+	const holders = read.rows.filter((row) => is_holder(row))
 	if (holders.length > 0) return { kind: 'busy', issues: holders }
 
 	return { kind: is_capped ? 'truncated' : 'idle' }
@@ -210,7 +212,7 @@ const epic_busy = {
 	unreadable_message,
 	truncated_message,
 	busy_reason,
-	is_parked,
+	is_holder,
 	parse_listing,
 	read_repository,
 }

package/scripts/epic/epic-chains.ts

@@ -36,8 +36,12 @@ function render_chains(chains: Chains): Array<string> {
 		.map((chain) => chain.map((number) => to_issue_reference(number)).join(DEPENDENCY_ARROW))
 }
 
+// Each relation once: a fan-out spliced in front of its hub names `#N -> #M` on every line through it,
+// and that is one relation, not one per line.
 function links_of(chains: Chains): Array<DependencyLink> {
-	return chains.flatMap((chain) => chain_links(chain))
+	const links = chains.flatMap((chain) => chain_links(chain))
+
+	return [...new Map(links.map((link) => [format_dependency_link(link), link])).values()]
 }
 
 // The relations to record and the relations to drop, as the difference between two declarations.
@@ -58,8 +62,9 @@ function diff_links(before: Chains, after: Chains): LinkDiff {
 	}
 }
 
-// The indices of the chains naming `target`. More than one is ambiguous rather than wrong: the
-// declaration is readable, but "immediately before #M" does not identify a single place.
+// The indices of the chains naming `target`. More than one can be ambiguous rather than wrong: the
+// declaration is readable, but "immediately before #M" identifies a single place only when every
+// chain gives `#M` the same predecessor (`is_single_place`).
 function chains_containing(chains: Chains, target: number): Array<number> {
 	return chains
 		.map((chain, index) => (chain.includes(target) ? index : -1))
@@ -78,14 +83,6 @@ function find_repeated_reference(chains: Chains): number | undefined {
 	return undefined
 }
 
-function replace_chain(
-	chains: Chains,
-	index: number,
-	updated: ReadonlyArray<number>,
-): Array<Array<number>> {
-	return chains.map((chain, position) => (position === index ? [...updated] : [...chain]))
-}
-
 // The chain a position declares, on its own: `#P -> #N` for `before`, `#N -> #P` for `after`.
 function chain_for(additions: ReadonlyArray<number>, position: InsertPosition): Array<number> {
 	return position.kind === 'before'
@@ -166,6 +163,36 @@ function is_branching_after(
 	return indices.every((index) => has_successor(chains[index] ?? [], position.target))
 }
 
+// `--before <M>` where several chains name `#M`, every one of them with the same predecessor — none, at
+// a fan-out point like `#A -> #B` beside `#A -> #C`. "Immediately before `#M`" is then one place
+// whichever chain a reader picks, so the additions go in front of `#M` on every line. A target the
+// chains reach from different predecessors (after a merge) still has no single place.
+function is_shared_before(
+	chains: Chains,
+	indices: ReadonlyArray<number>,
+	position: InsertPosition,
+): boolean {
+	if (position.kind !== 'before') return false
+
+	const predecessors = indices.map((index) => {
+		const chain = chains[index] ?? []
+
+		return chain[chain.indexOf(position.target) - 1]
+	})
+
+	return predecessors.every((predecessor) => predecessor === predecessors[0])
+}
+
+// Whether a splice at the position lands in one place: one chain names the target, or every chain
+// naming it gives a `before` the same spot.
+function is_single_place(
+	chains: Chains,
+	indices: ReadonlyArray<number>,
+	position: InsertPosition,
+): boolean {
+	return indices.length < AMBIGUOUS_MATCH_COUNT || is_shared_before(chains, indices, position)
+}
+
 function to_ambiguous_position_error(position: InsertPosition): string {
 	return `${to_issue_reference(position.target)} appears in more than one declared chain, so "${position.kind}" does not identify one place; edit the declaration by hand.`
 }
@@ -192,7 +219,7 @@ function find_position_ambiguity(
 ): string | undefined {
 	if (
 		position?.kind !== 'before' ||
-		chains_containing(chains, position.target).length < AMBIGUOUS_MATCH_COUNT
+		is_single_place(chains, chains_containing(chains, position.target), position)
 	) {
 		return undefined
 	}
@@ -200,20 +227,30 @@ function find_position_ambiguity(
 	return to_ambiguous_position_error(position)
 }
 
+function splice_chain(
+	chain: Chain,
+	additions: ReadonlyArray<number>,
+	position: InsertPosition,
+): Array<number> {
+	const at = chain.indexOf(position.target) + (position.kind === 'after' ? 1 : 0)
+
+	return [...chain.slice(0, at), ...additions, ...chain.slice(at)]
+}
+
 // Where a position that is not a branch lands: `--before` always, and `--after` at a chain's tail.
 // Inserting between two references re-points the pair, which is what keeps `--before` from leaving
-// the chain broken.
-function splice_into_chain(
+// the chain broken. Every chain the indices name gets the same splice — more than one only for a
+// shared `--before`.
+function splice_into_chains(
 	chains: Chains,
-	index: number,
+	indices: ReadonlyArray<number>,
 	additions: ReadonlyArray<number>,
 	position: InsertPosition,
 ): InsertOutcome {
-	const chain = chains[index] ?? []
-	const at = chain.indexOf(position.target) + (position.kind === 'after' ? 1 : 0)
-
 	return {
-		chains: replace_chain(chains, index, [...chain.slice(0, at), ...additions, ...chain.slice(at)]),
+		chains: chains.map((chain, index) =>
+			indices.includes(index) ? splice_chain(chain, additions, position) : [...chain],
+		),
 	}
 }
 
@@ -224,16 +261,15 @@ function insert_at_position(
 	tracked: ReadonlyArray<number>,
 ): InsertOutcome {
 	const indices = chains_containing(chains, position.target)
-	const [index] = indices
 
-	if (index === undefined) return insert_outside_chains(chains, additions, position, tracked)
+	if (indices.length === 0) return insert_outside_chains(chains, additions, position, tracked)
 	if (is_branching_after(chains, indices, position)) return add_chain(chains, additions, position)
 
-	if (indices.length >= AMBIGUOUS_MATCH_COUNT) {
+	if (!is_single_place(chains, indices, position)) {
 		return { error: to_ambiguous_position_error(position) }
 	}
 
-	return splice_into_chain(chains, index, additions, position)
+	return splice_into_chains(chains, indices, additions, position)
 }
 
 // No position given: nothing was declared about the additions, so the declaration is copied through

package/scripts/epic/epic-child-source.ts

@@ -0,0 +1,111 @@
+import { author_fields_schema } from '#scripts/git/git-schemas'
+import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+import { z } from 'zod'
+import type { EpicChild } from './epic-graph'
+import { epic_issue } from './epic-issue'
+
+// The children an epic read knows without asking (joshuafolkken/kit#6611): an open row the caller's
+// listing returned in the same scan, and a closed child kept across scans — its state hardly ever
+// changes, yet its issue and blocker reads were paid every scan. A read given no source reads all.
+
+const HOURS_KEPT = 6
+const MS_PER_HOUR = 3_600_000
+// Long against a scan every few minutes, and short enough that a reopened child not in the listing
+// is read as closed for part of a day at most — and none an open sibling waits on, which is read
+// again (`epic-fetch.ts` `recheck_blockers`). One record, for the repository last written; another
+// repository's write replaces it.
+const CLOSED_CACHE: CacheSlot = { prefix: 'josh-epic-closed-', ttl_ms: HOURS_KEPT * MS_PER_HOUR }
+
+const reference_schema = z.object({ repo: z.string(), number: z.number() })
+
+const child_schema = z.object({
+	number: z.number(),
+	repo: z.string(),
+	state: z.enum(['OPEN', 'CLOSED']),
+	labels: z.array(z.string()),
+	blocked_by: z.array(reference_schema),
+	body: z.string().optional(),
+	...author_fields_schema,
+})
+
+// Each child keeps its own read time, so adding another never extends how long it is trusted.
+const entries_schema = z.array(z.object({ read_at: z.number(), child: child_schema }))
+
+type ClosedEntry = z.infer<typeof entries_schema>[number]
+
+// `listed` holds the open rows the caller's listing returned, all in `repo`.
+interface ChildSource {
+	repo: string
+	listed: ReadonlyMap<number, EpicChild>
+}
+
+function fresh_entries(repo: string, now_ms: number): Array<ClosedEntry> {
+	const entries = shared_cache.read(CLOSED_CACHE, repo, entries_schema, now_ms) ?? []
+
+	return entries.filter((entry) => now_ms - entry.read_at < CLOSED_CACHE.ttl_ms)
+}
+
+function cached_closed(repo: string, now_ms: number): Map<number, EpicChild> {
+	return new Map(fresh_entries(repo, now_ms).map((entry) => [entry.child.number, entry.child]))
+}
+
+// The children of `repo` answered without a read. A listed row wins over a cached closed one: the
+// listing is open-only, so a child in it has been reopened since it was cached.
+function known(
+	source: ChildSource | undefined,
+	repo: string,
+	now_ms: number,
+): ReadonlyMap<number, EpicChild> {
+	if (source === undefined) return new Map()
+	const closed = cached_closed(repo, now_ms)
+
+	return source.repo === repo ? new Map([...closed, ...source.listed]) : closed
+}
+
+function is_closed(child: EpicChild): boolean {
+	return child.state === epic_issue.CLOSED
+}
+
+// Adds the closed children just read to the record of `repo`, and drops a cached one that came back
+// open. One already cached is left with its own read time.
+function remember_closed(
+	source: ChildSource | undefined,
+	repo: string,
+	children: ReadonlyArray<EpicChild>,
+	now_ms: number,
+): void {
+	if (source === undefined) return
+	const fresh = fresh_entries(repo, now_ms)
+	const reopened = new Set(
+		children.filter((child) => !is_closed(child)).map((child) => child.number),
+	)
+	const kept = fresh.filter((entry) => !reopened.has(entry.child.number))
+	const cached = new Set(kept.map((entry) => entry.child.number))
+	const added = children.filter((child) => is_closed(child) && !cached.has(child.number))
+
+	if (added.length === 0 && kept.length === fresh.length) return
+	const entries = [...kept, ...added.map((child) => ({ read_at: now_ms, child }))]
+
+	shared_cache.write(CLOSED_CACHE, repo, entries, now_ms)
+}
+
+// The closed children `known` answered that an open sibling still waits on. Reopened, such a child
+// must hold that sibling, so the record is not trusted for it.
+function waited_closed(
+	children: ReadonlyArray<EpicChild>,
+	known_children: ReadonlyMap<number, EpicChild>,
+	repo: string,
+): ReadonlySet<number> {
+	const waited = children
+		.filter((child) => !is_closed(child))
+		.flatMap((child) => child.blocked_by)
+		.filter((blocker) => blocker.repo === repo)
+		.map((blocker) => blocker.number)
+
+	return new Set(waited.filter((number) => known_children.get(number)?.state === epic_issue.CLOSED))
+}
+
+const epic_child_source = { CLOSED_CACHE, known, remember_closed, waited_closed }
+
+export type { ChildSource }
+export { epic_child_source }

package/scripts/epic/epic-cli-untrack.ts

@@ -0,0 +1,38 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { epic_cli_argv } from './epic-cli-argv'
+
+const UNTRACK_FLAG = '--untrack'
+
+interface UntrackArguments {
+	epic_number: number
+	children: ReadonlyArray<number>
+}
+
+function is_untrack(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(UNTRACK_FLAG)
+}
+
+function is_invalid(value: string): boolean {
+	return !issue_number_shape.is_issue_number(value) || !Number.isSafeInteger(Number(value))
+}
+
+function read_subject(raw: ReadonlyArray<string>): UntrackArguments | undefined {
+	if (raw.some((value) => is_invalid(value))) return undefined
+	const [epic_number, ...children] = raw.map(Number)
+
+	if (epic_number === undefined || children.length === 0 || children.includes(epic_number)) {
+		return undefined
+	}
+
+	return { epic_number, children: [...new Set(children)] }
+}
+
+function parse_arguments(argv: ReadonlyArray<string>): UntrackArguments | undefined {
+	const parsed = epic_cli_argv.read_form(argv, { switches: [UNTRACK_FLAG] })
+
+	return parsed === undefined ? undefined : read_subject(parsed.positionals)
+}
+
+const epic_cli_untrack = { is_untrack, parse_arguments }
+
+export { epic_cli_untrack }

package/scripts/epic/epic-cli.ts

@@ -14,6 +14,9 @@ const ORDERED_FLAG = '--ordered'
 const RATIONALE_FLAG = '--rationale-file'
 const ORIGIN_FLAG = '--origin'
 const PROMOTE_FLAG = '--promote'
+// `--promote`'s rename of the promoted issue — the split path's English title, applied in the same call
+// rather than by a separate `gh api` PATCH.
+const TITLE_FLAG = '--title'
 const ADD_FLAG = '--add'
 // `--reconcile <E>`: bring the epic's declaration and its recorded relations back into agreement.
 // It takes no value flags — the epic number is the whole subject.
@@ -30,13 +33,19 @@ const ORDER_AFTER_FLAG = '--order-after'
 // from a file, or from stdin as `-`. The text is a judgement, so the caller writes it; what the command
 // contributes is placing it in the epic's `## Decisions` and on each child.
 const DECISION_FLAG = '--decision-file'
+// The split path's `planning` Telegram — the epic, every child's URL and the run command — sent by the
+// command once the epic exists rather than composed by hand (`epic-notify.ts`).
+const NOTIFY_FLAG = '--notify'
 // Which flags each form knows, and which of them consume the argument after them — per form, for the
 // reason `epic-cli-argv.ts` gives.
 const CREATE_FORM: FormFlags = {
-	switches: [ORDERED_FLAG],
+	switches: [ORDERED_FLAG, NOTIFY_FLAG],
 	value_flags: [RATIONALE_FLAG, ORIGIN_FLAG],
 }
-const PROMOTE_FORM: FormFlags = { ...CREATE_FORM, switches: [PROMOTE_FLAG, ORDERED_FLAG] }
+const PROMOTE_FORM: FormFlags = {
+	switches: [PROMOTE_FLAG, ORDERED_FLAG, NOTIFY_FLAG],
+	value_flags: [RATIONALE_FLAG, ORIGIN_FLAG, TITLE_FLAG],
+}
 const RECONCILE_FORM: FormFlags = { switches: [RECONCILE_FLAG] }
 const CHECK_FORM: FormFlags = { switches: [] }
 const ADD_FORM: FormFlags = {
@@ -51,26 +60,30 @@ interface CreateArguments {
 	title: string
 	children: Array<number>
 	is_ordered: boolean
+	is_notified: boolean
 	rationale_path?: string | undefined
 	origin?: string | undefined
 }
 
-// `--promote <N> <N1> <N2> …`: the issue to promote, then its children. No title — the issue already
-// has one, and the discussion in it is usually the split rationale.
+// `--promote <N> <N1> <N2> …`: the issue to promote, then its children. The title is optional — the
+// issue already has one, and `--title` renames it; the discussion in it is usually the split rationale.
 interface PromoteArguments {
 	epic_number: number
 	children: Array<number>
 	is_ordered: boolean
+	is_notified: boolean
 	rationale_path?: string | undefined
 	origin?: string | undefined
+	title?: string | undefined
 }
 
 // The flags a creation and a promotion share, read the same way for both.
 function read_batch_flags(
 	parsed: EpicArgv,
-): Pick<CreateArguments, 'is_ordered' | 'rationale_path' | 'origin'> {
+): Pick<CreateArguments, 'is_ordered' | 'is_notified' | 'rationale_path' | 'origin'> {
 	return {
 		is_ordered: is_switch_set(parsed, ORDERED_FLAG),
+		is_notified: is_switch_set(parsed, NOTIFY_FLAG),
 		rationale_path: read_flag_value(parsed, RATIONALE_FLAG),
 		origin: read_flag_value(parsed, ORIGIN_FLAG),
 	}
@@ -122,11 +135,15 @@ function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArgume
 
 // The promoted issue and its children. The number after `--promote` is the epic; everything else
 // positional is a child. Refused when the epic would also be listed as its own child, which would
-// have it block itself under `--ordered`.
+// have it block itself under `--ordered`. A blank `--title` is refused rather than dropped: the caller
+// meant to rename the issue.
 function to_promote_arguments(parsed: EpicArgv): PromoteArguments | undefined {
 	const subject = epic_cli_argv.read_epic_children(parsed)
+	const title = read_flag_value(parsed, TITLE_FLAG)?.trim()
+
+	if (subject === undefined || title === '') return undefined
 
-	return subject === undefined ? undefined : { ...subject, ...read_batch_flags(parsed) }
+	return { ...subject, ...read_batch_flags(parsed), title }
 }
 
 function parse_promote_arguments(argv: ReadonlyArray<string>): PromoteArguments | undefined {
@@ -381,6 +398,7 @@ export {
 	AFTER_FLAG,
 	BEFORE_FLAG,
 	DECISION_FLAG,
+	NOTIFY_FLAG,
 	ORDER_AFTER_FLAG,
 	ORDER_BEFORE_FLAG,
 	ORDERED_FLAG,
@@ -390,5 +408,6 @@ export {
 	RECONCILE_FLAG,
 }
 export { REMOVE_FLAG } from './epic-cli-remove'
+export { epic_cli_untrack } from './epic-cli-untrack'
 export type { AddArguments, CreateArguments, CrossRepoAddTarget, PromoteArguments }
 export type { RemoveArguments } from './epic-cli-remove'

package/scripts/epic/epic-close-comment.ts

@@ -43,8 +43,10 @@ const MARKER_CLOSE = ' -->'
 // child issues are closed ()".
 function child_references(epic: EpicChildren): Array<string> {
 	return [
-		...epic.children.map((child) => issue_cite.plain(child)),
-		...epic.external_children.map((child) => issue_cite.plain(child.number, child.repo)),
+		...epic.children.map((child) => issue_cite.plain_for('github', child)),
+		...epic.external_children.map((child) =>
+			issue_cite.plain_for('github', child.number, child.repo),
+		),
 	]
 }
 

package/scripts/epic/epic-close.ts

@@ -1,4 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import {
+	git_gh_issue_batch_read,
+	type BatchReader,
+	type IssueAt,
+} from '#scripts/gh/git-gh-issue-batch-read'
 import {
 	epic_child_schema,
 	epic_issue_schema,
@@ -110,30 +115,39 @@ function to_sibling_state(raw_json: string | undefined): SiblingState {
 
 type ChildRead = 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's state and relations as raw JSON, read by number from the repository `repo` names (this
+// one when absent).
+function state_reader(repo: string | undefined): BatchReader<string | undefined> {
+	return {
+		repo,
+		from_json: (json) => json,
+		read_rest: async (issue_number) =>
+			await git_gh_command.issue_get_state_and_relations(String(issue_number), repo),
+	}
+}
 
-// 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)
-
+function to_child_read(raw: string | undefined): ChildRead {
 	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.
+// reading its state immediately after the merge races with that propagation. The children are read
+// one repository at a time, the batched way (`git-gh-issue-batch-read.ts`).
 async function inspect_children(epic: EpicIssue, merged_number: number): Promise<Array<ChildRead>> {
-	const siblings: Array<ChildReference> = epic.children
+	// A same-repository child carries no `repo`; a cross-repository one names it.
+	const siblings: Array<IssueAt> = epic.children
 		.filter((child) => child !== merged_number)
 		.map((number) => ({ number }))
-
-	return await Promise.all(
-		[...siblings, ...epic.external_children].map(async (child) => await inspect_child(child)),
+	const reads = await git_gh_issue_batch_read.read_across(
+		[...siblings, ...epic.external_children],
+		state_reader,
 	)
+
+	return reads.map((raw) => to_child_read(raw))
 }
 
 // `pnpm josh epic --ordered` and `--add` record the declared chain themselves, through the REST