@joshuafolkken/kit 1.1471.0 → 1.1784.0

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 }

package/scripts/epic/epic-outside-blocker.ts

@@ -24,6 +24,10 @@ type DependencyVerdict = 'resolved' | 'time' | 'human' | 'inherit'
 // a closed blocker is a finished one.
 type ResolveDependency = (blocker: EpicChild, blocked: EpicChild) => DependencyVerdict
 
+// A notice's mark on `run:board`: ❗ rather than ⚠, a text symbol drawn two columns wide over the
+// blank after it.
+const NOTICE_ICON = '❗'
+
 type OutsideCategory = 'time' | 'human'
 
 // A line to announce once per invocation, keyed so the classifier's de-duplication can drop repeats.
@@ -62,7 +66,7 @@ function unread_answer(child: EpicChild, reference: IssueReference): OutsideAnsw
 		category: 'time',
 		notice: {
 			key: `unread:${epic_graph.key_of(child)}:${blocker}`,
-			message: `⚠ ${name_of(child)} is blocked by ${blocker}, whose state could not be read — it waits rather than runs`,
+			message: `${NOTICE_ICON} ${name_of(child)} is blocked by ${blocker}, whose state could not be read — it waits rather than runs`,
 		},
 	}
 }
@@ -80,7 +84,7 @@ function open_answer(
 		category: 'human',
 		notice: {
 			key: `outside:${epic_graph.key_of(child)}:${blocker}`,
-			message: `⚠ ${name_of(child)} waits on ${blocker}, which this run will not finish — withheld for a person`,
+			message: `${NOTICE_ICON} ${name_of(child)} waits on ${blocker}, which this run will not finish — withheld for a person`,
 		},
 	}
 }

package/scripts/epic/epic-parse.ts

@@ -16,7 +16,10 @@ const TASK_LIST_LINE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'u')
 // `owner/repo#101` on its own. The row patterns below are built from this source, so what counts as
 // a cross-repository reference has one definition — a second copy would let a form the task list
 // accepts be refused where a person types it, or the reverse.
-const EXTERNAL_REFERENCE_SOURCE = String.raw`([\w.-]+)\/([\w.-]+)#(\d+)`
+// A segment starts with a word character, so `.`, `..` and a leading `-` never become an owner or a
+// repository — `../..#1` would otherwise be read as one and walk the API path out of `repos/`.
+const REPOSITORY_SEGMENT_SOURCE = String.raw`\w[\w.-]*`
+const EXTERNAL_REFERENCE_SOURCE = String.raw`(${REPOSITORY_SEGMENT_SOURCE})\/(${REPOSITORY_SEGMENT_SOURCE})#(\d+)`
 const EXTERNAL_REFERENCE_PATTERN = new RegExp(`^${EXTERNAL_REFERENCE_SOURCE}$`, 'u')
 const TASK_LIST_ROW_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+`
 const EXTERNAL_TASK_LIST_PATTERN = new RegExp(
@@ -29,8 +32,10 @@ const EXTERNAL_SHORTHAND_PATTERN = new RegExp(
 	'gmu',
 )
 // `- [ ] https://github.com/owner/repo/issues/101`
-const EXTERNAL_URL_PATTERN =
-	/^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)\b/gmu
+const EXTERNAL_URL_PATTERN = new RegExp(
+	String.raw`${TASK_LIST_ROW_SOURCE}https?:\/\/github\.com\/(${REPOSITORY_SEGMENT_SOURCE})\/(${REPOSITORY_SEGMENT_SOURCE})\/issues\/(\d+)\b`,
+	'gmu',
+)
 
 // Fenced blocks are stripped before matching. An epic body may quote the body template itself, and
 // its sample rows (`- [ ] #101 <title>`) are illustrations, not tracked children — counting them
@@ -345,4 +350,5 @@ export {
 	is_state_closed,
 	UNORDERED_DEPENDENCIES,
 	DECLARED_CHAIN_LINE,
+	REPOSITORY_SEGMENT_SOURCE,
 }

package/scripts/epic/epic-read.ts

@@ -67,6 +67,7 @@ async function read_epic(epic_number: number): Promise<EpicReading | { error: st
 }
 
 const epic_read = {
+	read_subject,
 	read_epic,
 }
 

package/scripts/epic/epic-reconcile.ts

@@ -235,11 +235,50 @@ async function reconcile_epic(epic_number: number): Promise<number> {
 	return await apply_plan(epic_number, plan)
 }
 
+function with_recorded(
+	recorded: ReadonlyArray<EpicChild>,
+	link: DependencyLink,
+	repo: string,
+): Array<EpicChild> {
+	return recorded.map((child) =>
+		child.number === link.blocked && child.repo === repo
+			? { ...child, blocked_by: [...child.blocked_by, to_blocker(link, repo)] }
+			: child,
+	)
+}
+
+// The plan the epic would reconcile to once `link` is recorded, so a caller about to record it can
+// refuse first — a relation recorded and then refused leaves an order the declaration never carries.
+function build_plan_after(input: ReconcilePlanInput, link: DependencyLink): ReconcilePlan {
+	return build_reconcile_plan({
+		...input,
+		recorded: with_recorded(input.recorded, link, input.repo),
+	})
+}
+
+// Why reconciling after recording `link` would refuse, read before anything is written. An epic that
+// cannot be read throws: a failed read is no answer about whether the reconcile would refuse.
+async function refusal_after(
+	epic_number: number,
+	link: DependencyLink,
+): Promise<string | undefined> {
+	const epic = await epic_read.read_epic(epic_number)
+	if ('error' in epic) throw new Error(epic.error)
+
+	const input = { body: epic.subject.body, recorded: epic.recorded, repo: epic.repo }
+	const plan = build_plan_after(input, link)
+	if (plan.kind === 'cycle') return plan.message
+
+	return plan.kind === 'error' ? plan.error : undefined
+}
+
 const epic_reconcile = {
 	NOTHING_TO_RECONCILE,
 	RECONCILED,
+	build_plan_after,
 	build_reconcile_plan,
 	reconcile_epic,
+	refusal_after,
 }
 
 export { epic_reconcile }

package/scripts/epic/epic-run.ts

@@ -84,7 +84,9 @@ async function fill_run_command(
 	}
 }
 
-async function create_epic(input: CreateEpicInput): Promise<number> {
+// The created epic's number, or `undefined` when its URL could not be read — for a caller that writes
+// to the epic next (`epic:bundle --apply` reconciling a recorded order).
+async function create_epic_number(input: CreateEpicInput): Promise<number | undefined> {
 	await git_gh_command.label_ensure({
 		name: EPIC_LABEL,
 		color: EPIC_LABEL_COLOR,
@@ -110,6 +112,12 @@ async function create_epic(input: CreateEpicInput): Promise<number> {
 	await fill_run_command(epic_number, input)
 	console.info(`▶ Run the children with: ${epic_body.format_run_command(epic_number)}`)
 
+	return epic_number
+}
+
+async function create_epic(input: CreateEpicInput): Promise<number> {
+	await create_epic_number(input)
+
 	return SUCCESS_EXIT_CODE
 }
 
@@ -215,6 +223,7 @@ async function check_epic(epic_number: number): Promise<number> {
 
 const epic_run = {
 	create_epic,
+	create_epic_number,
 	promote_epic,
 	check_epic,
 }

package/scripts/epic/epic-solo.ts

@@ -1,5 +1,5 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_busy, type BusyRead } from './epic-busy'
 import type { EpicChild } from './epic-graph'
@@ -28,8 +28,6 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // them goes first is the ranking's question — `issue-rank.ts` puts a verification-path defect at the head — so an idle
 // repository takes the candidates in rank order like any other.
 
-const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
-
 // Which of the ordered candidates may start, which are held back, and why when a reason is worth
 // saying. `offered` keeps the candidates' own order.
 interface SoloSelection {
@@ -38,35 +36,65 @@ interface SoloSelection {
 	notice?: string
 }
 
+interface SoloQueue {
+	solo: EpicChild
+	index: number
+	behind: ReadonlyArray<EpicChild>
+}
+
 interface SoloGate {
 	result: EpicNextResult
 	notice?: string
 }
 
-function is_solo(child: EpicChild): boolean {
+// An issue as its number and its label names — a candidate, or a running issue `run:board` reads.
+type Labelled = Pick<EpicChild, 'number' | 'labels'>
+
+function is_solo(child: Labelled): boolean {
 	return has_label_name(child.labels, RUN_SOLO_LABEL)
 }
 
+// The running `run:solo` issue that lets nothing new start, if any — the one reading `select` and
+// `run:board`'s 🔒 rows share (joshuafolkken/kit#4391).
+function holder_of(running: ReadonlyArray<Labelled>): number | undefined {
+	return running.find((issue) => is_solo(issue))?.number
+}
+
 function solo_holder(read: BusyRead): number | undefined {
 	if (read.kind !== 'busy') return undefined
+	const running = read.issues.map((issue) => ({
+		number: issue.number,
+		labels: (issue.labels ?? []).map((label) => label.name),
+	}))
 
-	return read.issues.find((issue) => has_any_label(issue.labels, SOLO_LABELS))?.number
+	return holder_of(running)
 }
 
+// The words each of the gate's wait notices carries, so `backlog:offer` tells a `run:solo` wait from any
+// other `wait` off the notice `backlog:next` printed (joshuafolkken/kit#4396). Each names its verb:
+// `epic_solo_stale`'s release notice also opens "carries `run:solo` and", and is no wait.
+const HELD_MARK = `carries \`${RUN_SOLO_LABEL}\` and is running in`
+const WAITING_MARK = `carries \`${RUN_SOLO_LABEL}\` and waits for`
+
 function held_message(holder: number, repo: string): string {
 	return issue_citation.linkify(
-		`${issue_cite.plain(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
+		`${issue_cite.plain(holder)} ${HELD_MARK} ${repo}; nothing else starts until it merges or is parked.`,
 		repo,
 	)
 }
 
 function waiting_message(solo: number, repo: string): string {
 	return issue_citation.linkify(
-		`${issue_cite.plain(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
+		`${issue_cite.plain(solo)} ${WAITING_MARK} ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
 		repo,
 	)
 }
 
+// Whether `text` — what an offer printed on stderr — says the `run:solo` gate held the candidates.
+function is_solo_wait(text: string): boolean {
+	return text.includes(HELD_MARK) || text.includes(WAITING_MARK)
+}
+
 function first_of(children: ReadonlyArray<EpicChild>, keep: number): SoloSelection {
 	return { offered: children.slice(0, keep), withheld: children.slice(keep) }
 }
@@ -75,6 +103,15 @@ function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelect
 	return { offered: [], withheld: [...children], notice }
 }
 
+// The first `run:solo` candidate, where it sits, and the candidates ranked behind it, which nothing
+// offers past it. `run:board` draws the same reading on its queued rows (joshuafolkken/kit#4294).
+function queue_of(children: ReadonlyArray<EpicChild>): SoloQueue | undefined {
+	const index = children.findIndex((child) => is_solo(child))
+	const solo = children[index]
+
+	return solo === undefined ? undefined : { solo, index, behind: children.slice(index + 1) }
+}
+
 // Where the first `run:solo` candidate sits decides what starts: everything when there is none, the
 // candidates ahead of it when it is not first, and it alone once it heads an idle repository's ranking.
 function select_candidates(
@@ -82,14 +119,13 @@ function select_candidates(
 	read: BusyRead,
 	repo: string,
 ): SoloSelection {
-	const index = children.findIndex((child) => is_solo(child))
-	const solo = children[index]
+	const queue = queue_of(children)
 
-	if (solo === undefined) return first_of(children, children.length)
-	if (index > 0) return first_of(children, index)
+	if (queue === undefined) return first_of(children, children.length)
+	if (queue.index > 0) return first_of(children, queue.index)
 	if (read.kind === 'idle') return first_of(children, 1)
 
-	return none_of(children, waiting_message(solo.number, repo))
+	return none_of(children, waiting_message(queue.solo.number, repo))
 }
 
 // An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
@@ -143,7 +179,7 @@ function gate(
 		: { result: gated, notice: selection.notice }
 }
 
-const epic_solo = { gate, is_solo, select }
+const epic_solo = { gate, holder_of, is_solo, is_solo_wait, queue_of, select }
 
-export type { SoloGate, SoloSelection, SoloSelector }
+export type { Labelled, SoloGate, SoloQueue, SoloSelection, SoloSelector }
 export { epic_solo }

package/scripts/epic/epic.ts

@@ -8,11 +8,13 @@
  *        tsx scripts/epic/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
  *                                                      [--decision-file <path|->]
  *        tsx scripts/epic/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
+ *        tsx scripts/epic/epic.ts --decide <E> <N1> <N2> ... --decision-file <path|->
  */
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_add, type AddChildrenInput } from './epic-add'
 import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'
+import { epic_decide } from './epic-decide'
 import { epic_reconcile } from './epic-reconcile'
 import { epic_remove } from './epic-remove'
 import { epic_run } from './epic-run'
@@ -26,6 +28,7 @@ const USAGE = [
 	'       josh epic --add <E> <N1> <N2> ... [--order-before <M> | --order-after <M>] [--decision-file <path|->]',
 	'       josh epic --remove <E> <M> <N> ... [--decision-file <path|->]',
 	'       josh epic --reconcile <E>',
+	'       josh epic --decide <E> <N1> <N2> ... --decision-file <path|->',
 ].join('\n')
 const FAILURE_EXIT_CODE = 1
 
@@ -134,6 +137,26 @@ async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 	})
 }
 
+// A decision about children the epic already tracks — the half `--add --decision-file` cannot write,
+// since an insertion with nothing to add is refused.
+async function run_decision(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_decide_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(
+			`✖ An epic number, at least one child issue number, and exactly one readable \`--decision-file\` path (\`-\` reads stdin) are required.\n${USAGE}`,
+		)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await epic_decide.decide({
+		epic_number: parsed.epic_number,
+		children: parsed.children,
+		decision: epic_cli.read_decision(parsed.decision_path) ?? '',
+	})
+}
+
 // Reconcile an epic's declaration with its recorded relations. No decision file and no children: the
 // repair reads what the epic already records rather than being told an order.
 async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number> {
@@ -166,15 +189,26 @@ async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
 	})
 }
 
-// `--add` is checked before `--promote`: both name an existing issue first, and only the flag
-// distinguishes "insert into this epic" from "turn this issue into one".
+type EpicForm = readonly [
+	(argv: ReadonlyArray<string>) => boolean,
+	(argv: ReadonlyArray<string>) => Promise<number>,
+]
+
+// Checked in this order. `--add` comes before `--promote`: both name an existing issue first, and only
+// the flag distinguishes "insert into this epic" from "turn this issue into one".
+const FLAGGED_FORMS: ReadonlyArray<EpicForm> = [
+	[epic_cli.is_reconciliation, run_reconciliation],
+	[epic_cli.is_removal, run_removal],
+	[epic_cli.is_decision_entry, run_decision],
+	[epic_cli.is_addition, run_addition],
+	[epic_cli.is_promotion, run_promotion],
+]
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	if (epic_cli.is_reconciliation(argv)) return await run_reconciliation(argv)
-	if (epic_cli.is_removal(argv)) return await run_removal(argv)
-	if (epic_cli.is_addition(argv)) return await run_addition(argv)
-	if (epic_cli.is_promotion(argv)) return await run_promotion(argv)
+	const form = FLAGGED_FORMS.find(([is_form]) => is_form(argv))
+	const run_form = form === undefined ? run_creation : form[1]
 
-	return await run_creation(argv)
+	return await run_form(argv)
 }
 
 async function main(): Promise<void> {

package/scripts/exports/unused-members-cli.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { project_checks } from '#scripts/gate/project-checks'
 import { NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
-import type { NamespaceMember } from './namespace-members'
+import type { NamespaceMember } from '#tools/exports/namespace-members'
 
 const CHECK = 'exports'
 const FAIL_EXIT_CODE = 1
@@ -39,7 +39,7 @@ async function run_unused_members(root: string): Promise<number> {
 	// Loaded only past the skip: the scanner pulls in `typescript`, an optional peer a basic-profile
 	// consumer may not have, and this check runs in every consumer's gate. For the same reason the
 	// scanner is left out of the published package (`package.json` `files`); only this entry ships.
-	const { unused_members } = await import('./unused-members')
+	const { unused_members } = await import('#tools/exports/unused-members')
 	const members = unused_members.find_unused_members(root)
 	const output = report(root, members)
 

package/scripts/followup/followup-checks-event.ts

@@ -35,16 +35,21 @@ function coderabbit_state_of(check: RollupCheck | undefined): CodeRabbitState {
 	return is_coderabbit_rate_limited(check) ? 'rate-limited' : 'done'
 }
 
+// CodeRabbit's state on one poll — the reading `run:board` draws and `followup` times
+// (`followup-coderabbit-wait.ts`).
+function coderabbit_of(snapshot: PrStateSnapshot): CodeRabbitState {
+	return coderabbit_state_of(snapshot.rollup.find((check) => is_coderabbit_check(check.name)))
+}
+
 function summary_of(snapshot: PrStateSnapshot, pr: number): PrChecks {
 	const ci = snapshot.rollup.filter((check) => !is_coderabbit_check(check.name))
-	const coderabbit = snapshot.rollup.find((check) => is_coderabbit_check(check.name))
 
 	return {
 		pr,
 		pass: count_of(ci, CHECK_STATUS_PASS),
 		pending: count_of(ci, CHECK_STATUS_PENDING),
 		fail: count_of(ci, CHECK_STATUS_FAIL),
-		coderabbit: coderabbit_state_of(coderabbit),
+		coderabbit: coderabbit_of(snapshot),
 	}
 }
 
@@ -77,6 +82,6 @@ function observer_of(issue: string | undefined, pr_url: string | undefined): Sna
 	}
 }
 
-const followup_checks_event = { observer_of, summary_of }
+const followup_checks_event = { coderabbit_of, observer_of, summary_of }
 
 export { followup_checks_event }