@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/epic/epic-blocked-by.ts

@@ -0,0 +1,198 @@
+import { epic_add } from '#scripts/epic/epic-add'
+import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
+import { epic_index, type FetchedEpics } from '#scripts/epic/epic-index'
+import { epic_reconcile } from '#scripts/epic/epic-reconcile'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { session_cite } from '#scripts/issue/session-cite'
+
+// `#issue` blocked by `#prerequisite`, recorded so the epic tracking `#issue` declares it too — the
+// one write `run:pause` and `backlog:triage --blocked-by` share (joshuafolkken/kit#5647). A direct
+// relation between two children of a declared epic, with no declaration beside it, is the
+// `declaration_mismatch` anomaly that stops every epic's offer (`epic-graph.ts`).
+//
+// **It asks whether the relation is already recorded before it writes**, so a rerun after a later
+// step failed settles the declaration rather than posting the relation twice. Failures throw, the
+// message naming what was or was not recorded.
+
+// `epic:bundle`'s own listing limit, so both commands see the same epics.
+const EPIC_LIMIT = 200
+const SUCCESS_EXIT_CODE = 0
+const ALREADY = 'already'
+const UNSEEN_EPIC = 'the open epics were not read in full, so an epic tracking it may be unseen'
+
+interface BlockedByRequest {
+	issue: string
+	prerequisite: string
+	// Caused-park filings leave placement to epic:bundle's single-epic decision.
+	is_relation_only?: boolean
+}
+
+async function is_blocked(request: BlockedByRequest): Promise<boolean> {
+	const blockers = await git_gh_issue_read.issue_blocked_by_numbers(request.issue)
+
+	return blockers.includes(Number(request.prerequisite))
+}
+
+interface Tracking {
+	epic: number
+	// Whether the same epic already tracks the prerequisite as a row of its own.
+	is_prerequisite_child: boolean
+}
+
+// Every epic listing the child, not the one `build_epic_index` keeps: a child a second epic also
+// lists is still a row of this one.
+function is_listed_by(
+	epics: ReadonlyArray<{ number: number; body: string }>,
+	child: string,
+	epic: number,
+): boolean {
+	return epic_index.build_tracking_index(epics).get(Number(child))?.includes(epic) === true
+}
+
+async function fetch_epics(): Promise<FetchedEpics> {
+	const fetched = await epic_index.fetch_epics(EPIC_LIMIT)
+	if (fetched === undefined) throw new Error('the open epics could not be read')
+
+	return fetched
+}
+
+// A listing cut short is no answer about absence: an epic past the cut tracks `#M` invisibly, and a
+// direct relation written then leaves that epic recording an order its body never declares.
+async function tracked_in(
+	issue: string,
+): Promise<{ epic: number | undefined; fetched: FetchedEpics }> {
+	const fetched = await fetch_epics()
+	const epic = epic_index.build_epic_index(fetched.epics).get(Number(issue))
+
+	if (epic === undefined && !epic_bundle_gaps.is_membership_established(fetched.cutoff)) {
+		throw new Error(UNSEEN_EPIC)
+	}
+
+	return { epic, fetched }
+}
+
+interface ChildrenTracking {
+	epic: number
+	// Whether the same epic already lists every one of the children as a row of its own.
+	lists_children: boolean
+}
+
+// The epic tracking `#issue`, `undefined` for none, or a throw when the listing cannot tell.
+async function tracking_with(
+	issue: string,
+	children: ReadonlyArray<string>,
+): Promise<ChildrenTracking | undefined> {
+	const { epic, fetched } = await tracked_in(issue)
+	if (epic === undefined) return undefined
+
+	return {
+		epic,
+		lists_children: children.every((child) => is_listed_by(fetched.epics, child, epic)),
+	}
+}
+
+async function tracking_epic(request: BlockedByRequest): Promise<Tracking | undefined> {
+	const { epic, fetched } = await tracked_in(request.issue)
+	if (epic === undefined) return undefined
+
+	return { epic, is_prerequisite_child: is_listed_by(fetched.epics, request.prerequisite, epic) }
+}
+
+// Every epic listing `#issue`, not the one `build_epic_index` keeps: removing a relation drops its
+// declaration from each, since any of them may declare it (`backlog:triage --unblock`). A listing cut
+// short refuses even when one epic is seen, for an epic past the cut may declare it too.
+async function listing_epics(issue: string): Promise<ReadonlyArray<number>> {
+	const fetched = await fetch_epics()
+
+	if (!epic_bundle_gaps.is_membership_established(fetched.cutoff)) throw new Error(UNSEEN_EPIC)
+
+	return epic_index.build_tracking_index(fetched.epics).get(Number(issue)) ?? []
+}
+
+async function add_to_epic(epic: number, request: BlockedByRequest): Promise<void> {
+	const code = await epic_add.add_children({
+		epic_number: epic,
+		children: [Number(request.prerequisite)],
+		position: { kind: 'before', target: Number(request.issue) },
+	})
+
+	if (code !== SUCCESS_EXIT_CODE) {
+		throw new Error(`\`epic --add\` into ${session_cite.issue(epic)} failed`)
+	}
+}
+
+async function record_relation(request: BlockedByRequest): Promise<void> {
+	if (await git_gh_issue_write.issue_add_blocked_by(request.issue, request.prerequisite)) return
+
+	throw new Error('the blocked-by relation was not recorded')
+}
+
+async function refuse_unreconcilable(epic: number, request: BlockedByRequest): Promise<void> {
+	const link = { blocker: Number(request.prerequisite), blocked: Number(request.issue) }
+	const refusal = await epic_reconcile.refusal_after(epic, link)
+	if (refusal === undefined) return
+
+	throw new Error(
+		`\`pnpm josh epic --reconcile ${String(epic)}\` would refuse the relation, so none was recorded: ${refusal}`,
+	)
+}
+
+async function reconcile_epic(epic: number): Promise<void> {
+	if ((await epic_reconcile.reconcile_epic(epic)) === SUCCESS_EXIT_CODE) return
+
+	throw new Error(
+		`the relation was recorded, but \`pnpm josh epic --reconcile ${String(epic)}\` failed to declare it`,
+	)
+}
+
+// A prerequisite outside the epic gains its row, declaration and relation from `epic --add --before`.
+// One the epic already tracks does not: `epic --add` reads it as a move and drops every order it
+// already had, where this only adds one — so the relation is recorded directly and
+// `epic --reconcile` copies it into the declaration beside the others, once a dry plan shows the
+// reconcile accepts it: a refusal after the write would leave the relation undeclared. `epic --add`
+// exits 0 on a relation it failed to post, so the relation is read back after the insertion.
+async function record_in_epic(tracking: Tracking, request: BlockedByRequest): Promise<string> {
+	if (tracking.is_prerequisite_child) {
+		await refuse_unreconcilable(tracking.epic, request)
+		await record_relation(request)
+		await reconcile_epic(tracking.epic)
+	} else {
+		await add_to_epic(tracking.epic, request)
+		if (!(await is_blocked(request))) await record_relation(request)
+	}
+
+	return `recorded in epic ${session_cite.issue(tracking.epic)}`
+}
+
+// A relation recorded inside an epic tracking both issues is only done once it is declared, so a
+// rerun past a failed reconcile reconciles again — a no-op on an epic that already declares it.
+async function settle_recorded(request: BlockedByRequest): Promise<string> {
+	const tracking = await tracking_epic(request)
+	if (tracking?.is_prerequisite_child === true) await reconcile_epic(tracking.epic)
+
+	return ALREADY
+}
+
+// What was done — `already`, `recorded` or `recorded in epic #E` — or a throw naming the failure.
+async function record(request: BlockedByRequest): Promise<string> {
+	if (await is_blocked(request)) return await settle_recorded(request)
+
+	const tracking = await tracking_epic(request)
+
+	if (
+		tracking !== undefined &&
+		(request.is_relation_only !== true || tracking.is_prerequisite_child)
+	) {
+		return await record_in_epic(tracking, request)
+	}
+
+	await record_relation(request)
+
+	return 'recorded'
+}
+
+const epic_blocked_by = { record, listing_epics, tracking_with }
+
+export type { BlockedByRequest, ChildrenTracking }
+export { epic_blocked_by }

package/scripts/epic/epic-body.ts

@@ -1,4 +1,3 @@
-import { issue_cite } from '#scripts/issue/issue-cite'
 import { UNORDERED_DEPENDENCIES } from './epic-parse'
 import { DEPENDENCY_ARROW, to_issue_reference } from './epic-reference'
 
@@ -38,10 +37,11 @@ function format_dependencies(children: ReadonlyArray<number>, is_ordered: boolea
 	return children.map((child) => to_issue_reference(child)).join(DEPENDENCY_ARROW)
 }
 
-// The command that runs the batch. `backlogrun #E --only` takes the epic itself rather than a list of
-// children: it re-reads the state from GitHub each
-// round, so an interrupted run resumes without anyone retyping the remaining numbers, and a child that
-// needs a decision is parked rather than ending the run. `--only` runs exactly the epic's children and
+// The command that runs the batch, in the form a terminal runs as typed: a `#` would start a shell
+// comment, and `backlogrun-args.ts` reads a bare number as `#N`. `backlogrun E --only` takes the epic
+// itself rather than a list of children: it re-reads the state from GitHub each round, so an
+// interrupted run resumes without anyone retyping the remaining numbers, and a child that needs a
+// decision is parked rather than ending the run. `--only` runs exactly the epic's children and
 // stops, which is the scope the removed `epicrun #E` keyword had.
 //
 // The epic number is not known while its own body is being built, so the placeholder is filled in by
@@ -53,7 +53,7 @@ const EPIC_PLACEHOLDER = '<this epic>'
 function format_run_command(epic_number: number | undefined): string {
 	const epic = epic_number === undefined ? EPIC_PLACEHOLDER : String(epic_number)
 
-	return `backlogrun ${issue_cite.plain(epic)} --only`
+	return `pnpm josh backlogrun ${epic} --only`
 }
 
 // A backlink to the Issue this split came from, when the split originated in another repository.

package/scripts/epic/epic-bundle-apply.ts

@@ -6,6 +6,7 @@ import {
 	type BundleAction,
 	type BundleDecision,
 } from './epic-bundle'
+import { epic_bundle_recommend } from './epic-bundle-recommend'
 import { epic_reconcile } from './epic-reconcile'
 import { epic_run } from './epic-run'
 
@@ -16,10 +17,12 @@ import { epic_run } from './epic-run'
 // **An order the candidates already record is carried into the epic body** by `epic --reconcile`,
 // which declares exactly the recorded relations — an order nobody recorded is never invented.
 //
-// `ask` stays the caller's: which epic to choose is a judgement, recorded with its reasoning.
+// `ask` is placed in the epic the decision recommends, with the reasoning written through `epic --add`'s
+// decision record on both the epic and the children. A cyclic spread recommends none and writes nothing.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
+const ISO_DATE_LENGTH = 10
 
 interface ApplyInput {
 	decision: BundleDecision
@@ -30,7 +33,7 @@ interface ApplyInput {
 }
 
 const UNAPPLIED_LINES: Readonly<Partial<Record<BundleAction, string>>> = {
-	ask: '↷ `--apply` wrote nothing: the related issues sit in more than one epic. Choose one and place it with `pnpm josh epic --add <E> <N> --decision-file <path>`.',
+	ask: '↷ `--apply` wrote nothing: the related epics declare a cycle, so none is recommended. Choose one and place it with `pnpm josh epic --add <E> <N> --decision-file <path>`.',
 	none: '↷ `--apply` wrote nothing: there is nothing to place.',
 }
 const WITHHELD_LINE =
@@ -73,18 +76,47 @@ function placeable(epic_number: number, input: ApplyInput): ApplyInput {
 	return { ...input, members }
 }
 
-async function add_to_epic(epic_number: number, input: ApplyInput): Promise<number> {
+async function add_to_epic(
+	epic_number: number,
+	input: ApplyInput,
+	decision: string | undefined,
+): Promise<number> {
 	const placed = placeable(epic_number, input)
-	const added = await epic_add.add_children({ epic_number, children: children_of(placed) })
+	const added = await epic_add.add_children({
+		epic_number,
+		children: children_of(placed),
+		...(decision !== undefined && { decision }),
+	})
 	if (added !== SUCCESS_EXIT_CODE) return added
 
 	return await reconcile_order(epic_number, placed)
 }
 
+// The epic a placing answer names: `add_to_epic`'s own, or the one `ask` recommends.
+function target_of(decision: BundleDecision): number | undefined {
+	if (decision.action === 'add_to_epic') return decision.epic
+
+	return decision.action === 'ask' ? decision.recommended : undefined
+}
+
+// `ask`'s placement was a choice between epics, so it carries its record; `add_to_epic`'s was not.
+function record_of(input: ApplyInput, epic_number: number): string | undefined {
+	if (input.decision.action !== 'ask') return undefined
+	const date = new Date().toISOString().slice(0, ISO_DATE_LENGTH)
+	const placement = {
+		subject: input.subject.number,
+		epic: epic_number,
+		epics: input.decision.epics,
+		members: input.members,
+	}
+
+	return epic_bundle_recommend.placement_record(placement, date)
+}
+
 // The title is the subject's, since the subject is what the bundle was asked about; the rationale is
 // the verdict's own reason, which already names the signal that grouped them.
 function title_of(subject: BacklogIssue): string {
-	const title = subject.title ?? `bundle with ${issue_cite.plain(subject.number)}`
+	const title = subject.title ?? `bundle with ${issue_cite.plain_for('github', subject.number)}`
 
 	return `Epic: ${title}`
 }
@@ -116,13 +148,12 @@ async function apply_decision(input: ApplyInput): Promise<number> {
 		return SUCCESS_EXIT_CODE
 	}
 
-	if (decision.action === 'add_to_epic' && decision.epic !== undefined) {
-		return await add_to_epic(decision.epic, input)
-	}
-
 	if (decision.action === 'create_epic') return await create_epic(input)
 
-	return report_unapplied(decision.action)
+	const epic_number = target_of(decision)
+	if (epic_number === undefined) return report_unapplied(decision.action)
+
+	return await add_to_epic(epic_number, input, record_of(input, epic_number))
 }
 
 const epic_bundle_apply = {

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

@@ -1,21 +1,18 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { issue_label_schema } from '#scripts/git/git-schemas'
+import type { IssueListOutcome } from '#scripts/gh/git-gh-issue-list'
+import { blocked_by_schema, issue_label_schema } from '#scripts/git/git-schemas'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
 import { session_cite } from '#scripts/issue/session-cite'
-import { bounded_pool } from '#scripts/lib/bounded-pool'
-import type { PollOptions } from '#scripts/lib/poll'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { z } from 'zod'
 import { epic_bundle, type BacklogIssue, type MembershipContext } from './epic-bundle'
 import { epic_bundle_apply } from './epic-bundle-apply'
 import { epic_bundle_format } from './epic-bundle-format'
 import { epic_bundle_gaps } from './epic-bundle-gaps'
-import { epic_bundle_poll } from './epic-bundle-poll'
 import { epic_bundle_referenced, type ReferencedContext } from './epic-bundle-referenced'
 import { epic_index, epic_schema, type FetchedEpics } from './epic-index'
 import { epic_issue } from './epic-issue'
-import type { IssueReference } from './epic-reference'
 
 // `josh epic:bundle <N>` — after an issue is filed, look at the open backlog and say whether it
 // belongs with something already there.
@@ -38,18 +35,11 @@ const UNKNOWN_REPO_MESSAGE =
 // listing's schema rather than made optional on one: the epic listing does not ask for the field, and
 // a schema that tolerates its absence everywhere would let a missing title pass unnoticed here.
 //
-// `blocked_by_count` is the blocker count GitHub already puts in the listing response.
-// It is **nullish rather than defaulted**, and that is the whole safety of
-// the read below: a row the listing carries no summary for must not be read as a row with no
-// blockers, because that reading is what would silently drop a relation instead of costing a
-// request. Nothing in today's pipeline is expected to arrive without one — the response carries the
-// summary on every issue, and `git-gh-issue-list.ts` filters pull requests, which are what lack it,
-// out client-side — so this tolerates a shape the listing is not supposed to hand over rather than
-// describing one it does.
+// `blockedBy` is absent on the listing that asks for no relations, and reads as none there.
 const backlog_schema = epic_schema.extend({
 	title: z.string().nullable(),
 	labels: z.array(issue_label_schema).default([]),
-	blocked_by_count: z.number().nullish(),
+	blockedBy: blocked_by_schema,
 })
 
 type BacklogRow = z.infer<typeof backlog_schema>
@@ -58,58 +48,21 @@ type BacklogRow = z.infer<typeof backlog_schema>
 // task-list read would answer differently the first time that shape moved.
 const { build_epic_index } = epic_index
 
-// Undefined when the read failed, which the caller reports — as opposed to an issue that genuinely
-// declares no relations, which is an empty array.
-async function epic_issue_relations(
-	issue_number: string,
-	repo: string,
-): Promise<Array<IssueReference> | undefined> {
-	const parsed = epic_issue.parse_epic_issue(
-		await git_gh_command.issue_get_state_and_relations(issue_number),
-	)
-
-	return parsed === undefined ? undefined : epic_issue.blocker_references_of(parsed, repo)
-}
-
-// One read per backlog issue *that has blockers*, a few at a time.
-//
-// A read is `gh api`: one REST request for the issue, and a second to its `dependencies/blocked_by`
-// endpoint unless the issue's own dependency summary reports exactly zero blockers. The listing that
-// produced these rows already carries that same summary, so the zero is known *before* the read
-// rather than inside it, and the read is skipped outright — otherwise the command would pay one
-// request for every open issue in the repository, a cost that grows with the backlog.
+// The listing that carries each row's blocker relations, or the one that carries none.
 //
-// One read would do if `gh` exposed the reverse of `blockedBy`, but it does not (`blocks` is not a
-// JSON field), so a dependency declared on the *other* issue is only visible by asking that issue.
-// Spawning all of them at once is what turns a rate limit into a wrong answer: a refused read becomes
-// an empty relation list, and a bundle that should have been proposed is reported as "no strong
-// signal" instead. Batching bounds the burst; the `unreadable` list below is what keeps a refused
-// read from passing as an answer. The pool itself is `bounded-pool.ts`,
-// shared with the reference reads below it and with the eval suite.
-const RELATION_CONCURRENCY = 8
-const NO_BLOCKERS = 0
-
-// GitHub's own count, not an inference from what was read. Strictly `=== 0`, so a row carrying no
-// summary at all answers `false` and keeps its read: an absent count says nothing about whether the
-// issue has blockers, and treating the two alike is the one way this shortcut could lose a
-// relation. Skipping is cheap and wrong-in-silence; reading is a request and always right.
-function has_no_blockers(row: BacklogRow): boolean {
-	return row.blocked_by_count === NO_BLOCKERS
-}
-
-// Every row still gets an entry, in order, so the index alignment `fetch_backlog` relies on is the
-// same whether a row was read or answered from the listing.
-async function fetch_relations(
-	rows: ReadonlyArray<BacklogRow>,
-	repo: string,
-): Promise<Array<Array<IssueReference> | undefined>> {
-	return await bounded_pool.bounded_map(rows, RELATION_CONCURRENCY, async (row) =>
-		has_no_blockers(row) ? [] : await epic_issue_relations(String(row.number), repo),
-	)
+// The relations ride on the listing (`issue_list_open_relations`), which reads them in one GraphQL
+// query per hundred rows. Read here one issue at a time they cost two requests per open issue
+// declaring a blocker — the bulk of an `issue:file` run's REST calls (joshuafolkken/kit#6796). The
+// listing still skips a row GitHub's own summary reports no blockers on, and a relation it cannot
+// read fails the whole listing, which this command reports, rather than passing as "none".
+async function list_backlog(options: BacklogOptions | undefined): Promise<IssueListOutcome> {
+	return options?.include_relations === false
+		? await git_gh_command.issue_list_open_bodies(BACKLOG_LIMIT)
+		: await git_gh_command.issue_list_open_relations(BACKLOG_LIMIT)
 }
 
 // The open backlog, with each issue's relations and the epic tracking it. `unreadable` names the
-// issues whose relations could not be read, so a "nothing to bundle" verdict is never quietly based
+// referenced issues that could not be read, so a "nothing to bundle" verdict is never quietly based
 // on data that never arrived.
 interface FetchedBacklog {
 	issues: Array<BacklogIssue>
@@ -131,9 +84,8 @@ interface FetchedBacklog {
 // One listing row as the bundler reads it. Split from the fetch so that function stays a list of
 // requests rather than a request list plus a row mapping.
 function to_backlog_issue(
-	row: Pick<BacklogRow, 'number' | 'title' | 'body' | 'labels'>,
+	row: BacklogRow,
 	context: MembershipContext & { repo: string },
-	blocked_by: ReadonlyArray<IssueReference>,
 ): BacklogIssue {
 	const labels = row.labels.map((label) => label.name)
 
@@ -142,7 +94,7 @@ function to_backlog_issue(
 		repo: context.repo,
 		title: row.title ?? '',
 		body: row.body ?? '',
-		blocked_by,
+		blocked_by: epic_issue.blocker_references_of(row, context.repo),
 		...epic_bundle.membership_of(row.number, labels, context),
 	}
 }
@@ -150,48 +102,32 @@ function to_backlog_issue(
 // What a caller does not need read for it. `issue:scout` asks about an issue that does not exist yet:
 // it has no number, so no recorded dependency can name it and it declares none of its own — the
 // relation reads cannot change its answer, and skipping them takes one request per open issue off the
-// command a run makes before every filing. `epic:bundle` leaves it unset and
-// reads them exactly as before.
+// command a run makes before every filing. `epic:bundle` leaves it unset and reads them.
 interface BacklogOptions {
 	include_relations?: boolean
 }
 
-// The relations, or an empty list each when the caller asked for none. Every issue still gets a row,
-// so the index alignment `fetch_backlog` relies on holds either way.
-async function read_relations(
-	rows: ReadonlyArray<BacklogRow>,
-	repo: string,
-	options: BacklogOptions | undefined,
-): Promise<Array<Array<IssueReference> | undefined>> {
-	if (options?.include_relations === false) return rows.map(() => [])
-
-	return await fetch_relations(rows, repo)
-}
-
 async function fetch_backlog(
 	repo: string,
 	epics: Map<number, number>,
 	epic_numbers: ReadonlySet<number> = new Set(epics.values()),
 	options?: BacklogOptions,
 ): Promise<FetchedBacklog> {
-	const { json, is_capped } = await git_gh_command.issue_list_open_bodies(BACKLOG_LIMIT)
+	const { json, is_capped } = await list_backlog(options)
 	// A failed listing is not an empty backlog. Reported rather than degraded into one, which would
 	// have a `gh` failure arrive as "that issue does not exist".
 	if (json === undefined) return { issues: [], unreadable: [], is_readable: false }
 	// Same reason as `fetch_epics`: an unparseable listing is not an empty backlog.
 	const rows = parse_json_array_or_undefined(json, backlog_schema)
 	if (rows === undefined) return { issues: [], unreadable: [], is_readable: false }
-	const relations = await read_relations(rows, repo, options)
 
 	return {
 		is_readable: true,
 		// Either cutoff hides the same thing: a related issue past it, reported as "no existing issue
 		// shares a reference" — an assertion about data that was never loaded.
 		cutoff: cutoff_of(rows.length, BACKLOG_LIMIT, is_capped),
-		issues: rows.map((row, index) =>
-			to_backlog_issue(row, { repo, epics, epic_numbers }, relations[index] ?? []),
-		),
-		unreadable: rows.filter((_, index) => relations[index] === undefined).map((row) => row.number),
+		issues: rows.map((row) => to_backlog_issue(row, { repo, epics, epic_numbers })),
+		unreadable: [],
 	}
 }
 
@@ -318,19 +254,24 @@ async function report_widened(
 	return await report_decision(subject, widened, repo, is_apply)
 }
 
-// The recommendation for one issue, from the open backlog around it. `options` is the poll a caller
-// holding a just-filed issue passes, since the listing trails the create call (`epic-bundle-poll.ts`).
-async function report_for(
+// The subject from the listing, or read on its own when the listing does not show it. A just-filed
+// issue trails the listing for a while; re-reading the whole backlog until it appeared cost every
+// open issue's requests again per attempt (joshuafolkken/kit#6796), where one read answers.
+async function find_subject(
 	issue_number: number,
-	repo: string,
-	options?: PollOptions,
-	is_apply = false,
-): Promise<number> {
-	const backlog = await epic_bundle_poll.read_until_listed(
-		async () => await read_backlog(repo),
-		issue_number,
-		options,
-	)
+	backlog: FetchedBacklog,
+): Promise<BacklogIssue | undefined> {
+	const listed = backlog.issues.find((issue) => issue.number === issue_number)
+	if (listed !== undefined || backlog.context === undefined) return listed
+	const read = await epic_bundle_referenced.read_subject(issue_number, backlog.context)
+	if (read !== undefined) backlog.issues.push(read)
+
+	return read
+}
+
+// The recommendation for one issue, from the open backlog around it.
+async function report_for(issue_number: number, repo: string, is_apply = false): Promise<number> {
+	const backlog = await read_backlog(repo)
 
 	if (!backlog.is_readable) {
 		console.error(unreadable_backlog_message(backlog))
@@ -338,7 +279,7 @@ async function report_for(
 		return FAILURE_EXIT_CODE
 	}
 
-	const subject = backlog.issues.find((issue) => issue.number === issue_number)
+	const subject = await find_subject(issue_number, backlog)
 
 	if (subject === undefined) {
 		console.error(
@@ -374,7 +315,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await report_for(issue_number, repo, undefined, argv.includes(APPLY_FLAG))
+	return await report_for(issue_number, repo, argv.includes(APPLY_FLAG))
 }
 
 const epic_bundle_cli = {

package/scripts/epic/epic-bundle-evidence.ts

@@ -141,8 +141,8 @@ const EVIDENCE_INDENT = ' '.repeat(EVIDENCE_INDENT_WIDTH)
 
 function format_one(item: OrderingEvidence): string {
 	const { verb, order_prefix, order_suffix } = EVIDENCE_WORDING[item.kind]
-	const first = issue_cite.plain(item.first)
-	const second = issue_cite.plain(item.second)
+	const first = issue_cite.plain_for('linked', item.first)
+	const second = issue_cite.plain_for('linked', item.second)
 	const order = `${order_prefix}${first}${order_suffix}`
 
 	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${section_phrase(item)} — ${order}`

package/scripts/epic/epic-bundle-format.ts

@@ -15,7 +15,7 @@ import { format_dependency_links } from './epic-reference'
 const ACTION_LINES: Readonly<Record<string, string>> = {
 	add_to_epic: 'Add it to the epic that already tracks a related issue (Tier A — do it).',
 	create_epic: 'Create an epic for these (Tier A — do it).',
-	ask: 'Related issues sit in more than one epic: choose the one you recommend, add it, and record why (Tier A — do it).',
+	ask: 'Related issues sit in more than one epic: place it in the recommended one and record why — `epic:bundle --apply` does both (Tier A — do it).',
 	none: 'Nothing to bundle.',
 }
 
@@ -31,7 +31,7 @@ function headline(decision: BundleDecision): string {
 }
 
 function format_numbers(numbers: ReadonlyArray<number>): string {
-	return numbers.map((issue_number) => issue_cite.plain(issue_number)).join(', ')
+	return numbers.map((issue_number) => issue_cite.plain_for('linked', issue_number)).join(', ')
 }
 
 // The backlog rows of the verdict's candidates — what the printed order and `--apply` both read.
@@ -79,6 +79,20 @@ const PLACING_ACTIONS: ReadonlySet<BundleAction> = new Set<BundleAction>([
 	'ask',
 ])
 
+// A cycle recommends nothing, so `--apply` places nothing there and the headline's "recommended one"
+// has to be named as absent rather than left for the reader to look for.
+const NO_RECOMMENDATION_LINE =
+	'  Recommended: none — the epics declare a cycle; place it with `pnpm josh epic --add <E> <N> --decision-file <path>`'
+
+// The spread and the epic `ask` recommends — what `--apply` places the issue in.
+function format_epics(decision: BundleDecision): Array<string> {
+	if (decision.epics.length <= 1) return []
+	const involved = `  Epics involved: ${format_numbers(decision.epics)}`
+	if (decision.recommended === undefined) return [involved, NO_RECOMMENDATION_LINE]
+
+	return [involved, `  Recommended: ${issue_cite.plain_for('linked', decision.recommended)}`]
+}
+
 // `is_membership_established` is what separates "no epic tracks these" from "their epics were never
 // read".
 function format_decision(
@@ -97,17 +111,17 @@ function format_decision(
 		lines.push(`  Related: ${format_numbers(decision.candidates)}`)
 	}
 
-	if (decision.epics.length > 1) {
-		lines.push(`  Epics involved: ${format_numbers(decision.epics)}`)
-	}
-
-	return [...lines, ...format_order(decision, subject, backlog)].join('\n')
+	return [...lines, ...format_epics(decision), ...format_order(decision, subject, backlog)].join(
+		'\n',
+	)
 }
 
 const epic_bundle_format = {
 	ACTION_LINES,
 	ALREADY_TRACKED_LINE,
+	NO_RECOMMENDATION_LINE,
 	format_numbers,
+	format_epics,
 	format_order,
 	format_decision,
 	members_of,