@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -3,6 +3,8 @@ import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_cite } from '#scripts/issue/issue-cite'
+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'
@@ -19,10 +21,10 @@ 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'
+import { format_dependency_links, 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 (joshuafolkken/kit#873).
+// belongs with something already there.
 //
 // The machine finds the candidates; the decision to bundle is the caller's. This command prints what
 // it found and what it recommends, and writes nothing.
@@ -37,12 +39,12 @@ const USAGE = 'Usage: josh epic:bundle <issue-number>'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the backlog cannot be keyed by repository — check `gh auth status` and that this is a checkout with an `origin` remote.'
 
-// The backlog listing asks for the title too (joshuafolkken/kit#1252). Kept apart from the epic
+// The backlog listing asks for the title too. Kept apart from the epic
 // 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
-// (joshuafolkken/kit#1736). It is **nullish rather than defaulted**, and that is the whole safety of
+// `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
@@ -56,8 +58,7 @@ const backlog_schema = epic_schema.extend({
 
 type BacklogRow = z.infer<typeof backlog_schema>
 
-// The epic index is `epic-index.ts`'s, shared with the `auto-ok` pickup since
-// joshuafolkken/kit#1633: both commands ask which epic tracks an issue, and a second copy of the
+// The epic index is `epic-index.ts`'s, shared with the `auto-ok` pickup: both commands ask which epic tracks an issue, and a second copy of the
 // task-list read would answer differently the first time that shape moved.
 const { build_epic_index } = epic_index
 
@@ -80,21 +81,19 @@ async function epic_issue_relations(
 
 // One read per backlog issue *that has blockers*, a few at a time.
 //
-// Since joshuafolkken/kit#1024 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. That second request was already skipped on a zero; the first one was not, so the
-// command still paid one request for every open issue in the repository — a cost that grows with the
-// backlog and made the command heavier exactly as more issues made it more useful
-// (joshuafolkken/kit#1736). 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.
+// 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.
 //
 // 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 (joshuafolkken/kit#873). The pool itself is `bounded-pool.ts`,
-// shared with the reference reads below it and with the eval suite (joshuafolkken/kit#1144).
+// 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
 
@@ -124,8 +123,8 @@ interface FetchedBacklog {
 	issues: Array<BacklogIssue>
 	unreadable: Array<number>
 	is_readable: boolean
-	// Why the backlog listing stopped short, or that it did not. A `ScanCutoff` rather than a flag
-	// since joshuafolkken/kit#1067: the page ceiling now bounds this listing too, and the two cutoffs
+	// Why the backlog listing stopped short, or that it did not. A `ScanCutoff` rather than a flag:
+	// the page ceiling bounds this listing too, and the two cutoffs
 	// cite different numbers.
 	cutoff?: ScanCutoff
 	has_epic_list?: boolean
@@ -158,7 +157,7 @@ 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 (joshuafolkken/kit#1252). `epic:bundle` leaves it unset and
+// command a run makes before every filing. `epic:bundle` leaves it unset and
 // reads them exactly as before.
 interface BacklogOptions {
 	include_relations?: boolean
@@ -212,7 +211,7 @@ const ACTION_LINES: Readonly<Record<string, string>> = {
 
 // `Nothing to bundle.` is right when nothing was found, and wrong when an epic already tracks the
 // issue — there the answer is actionable: a caller looking for somewhere to put a prerequisite adds
-// it to *that* epic rather than creating a second one (joshuafolkken/kit#943).
+// it to *that* epic rather than creating a second one.
 const ALREADY_TRACKED_LINE = 'Already in an epic — add to that one, do not create a second.'
 
 function headline(decision: BundleDecision): string {
@@ -223,22 +222,21 @@ function headline(decision: BundleDecision): string {
 
 // The epics currently open, at this command's own listing limit. A failed read stays `undefined` and
 // is reported: without the list, an issue an epic already tracks is told to create a second one —
-// confidently, and with exit 0 (joshuafolkken/kit#950).
+// confidently, and with exit 0.
 async function fetch_epics(): Promise<FetchedEpics | undefined> {
 	return await epic_index.fetch_epics(BACKLOG_LIMIT)
 }
 
 function format_numbers(numbers: ReadonlyArray<number>): string {
-	return numbers.map((issue_number) => `#${String(issue_number)}`).join(', ')
+	return numbers.map((issue_number) => issue_cite.plain(issue_number)).join(', ')
 }
 
 // The order to record alongside the bundle. Bundling without it records the batch and loses the
 // reason it is a batch, so the recommendation carries it rather than leaving it to be remembered.
 function format_links(links: ReadonlyArray<{ blocker: number; blocked: number }>): string {
 	if (links.length === 0) return '  Order: none declared — do not invent one'
-	const arrows = links.map((link) => `#${String(link.blocker)} -> #${String(link.blocked)}`)
 
-	return `  Order: ${arrows.join(', ')}`
+	return `  Order: ${format_dependency_links(links)}`
 }
 
 function format_order(
@@ -251,7 +249,7 @@ function format_order(
 	const children = epic_bundle.bundle_children(subject, members)
 
 	// The evidence goes under the order rather than beside the verdict: what it explains is the
-	// order, and a reader checking one reads straight on into the other (joshuafolkken/kit#1737).
+	// order, and a reader checking one reads straight on into the other.
 	return [
 		`  Children: ${format_numbers(children)}`,
 		format_links(epic_bundle.bundle_dependency_links(subject, members)),
@@ -261,7 +259,7 @@ function format_order(
 
 // The verdicts that put the subject into an epic. Each one asserts that no epic already tracks it —
 // `create_epic` asserts as much about the candidates too — and that negative is exactly what a cut
-// epic listing cannot establish (joshuafolkken/kit#1697). `none` is absent on purpose: it either
+// epic listing cannot establish. `none` is absent on purpose: it either
 // names the epic it *found* tracking the subject, which a cut cannot unseat, or reports no candidate
 // at all, which says nothing about epics.
 const PLACING_ACTIONS: ReadonlySet<BundleAction> = new Set<BundleAction>([
@@ -306,7 +304,7 @@ async function read_backlog(repo: string, options?: BacklogOptions): Promise<Fet
 	const epics = build_epic_index(open_epics.epics)
 	// From the epic list itself, not from the index's values: an epic tracking no child yet has no
 	// entry in the index, and would enter the backlog as an ordinary issue that its own children then
-	// propose bundling with (joshuafolkken/kit#873).
+	// propose bundling with.
 	const epic_numbers = new Set(open_epics.epics.map((epic) => epic.number))
 
 	return {
@@ -319,7 +317,7 @@ async function read_backlog(repo: string, options?: BacklogOptions): Promise<Fet
 
 // The backlog the decision is made from: the open listing, plus the referenced issues it could not
 // show. Without the second half the command answers about a window that closes minutes after the
-// follow-up issue is filed (joshuafolkken/kit#947).
+// follow-up issue is filed.
 async function widen_with_referenced(
 	subject: BacklogIssue,
 	backlog: FetchedBacklog,
@@ -360,7 +358,9 @@ function warn_cutoff(message: string | undefined): void {
 // wording of each gap is `epic-bundle-gaps.ts`'s; what stays here is which gaps this command has.
 function warn_about_gaps(backlog: FetchedBacklog): void {
 	if (backlog.unreadable.length > 0) {
-		console.error(`⚠ Could not read ${format_numbers(backlog.unreadable)}.`)
+		const unreadable = backlog.unreadable.map((issue_number) => session_cite.issue(issue_number))
+
+		console.error(`⚠ Could not read ${unreadable.join(', ')}.`)
 	}
 
 	warn_cutoff(epic_bundle_gaps.backlog_gap(backlog.cutoff ?? NO_CUTOFF, BACKLOG_LIMIT))
@@ -373,7 +373,7 @@ function report_decision(subject: BacklogIssue, backlog: FetchedBacklog, repo: s
 	const decision = epic_bundle.decide_bundle(subject, others)
 
 	// The `Related:` / `Children:` listings name issues as `#N`; linkified here so the recommendation a
-	// run copies into its reply carries clickable references rather than bare ones (joshuafolkken/kit#2329).
+	// run copies into its reply carries clickable references rather than bare ones.
 	const report = format_decision(decision, subject, others, is_established)
 
 	console.info(issue_citation.linkify(report, repo))
@@ -417,7 +417,9 @@ async function report_for(
 	const subject = backlog.issues.find((issue) => issue.number === issue_number)
 
 	if (subject === undefined) {
-		console.error(`#${String(issue_number)} is not an open issue in ${repo}.`)
+		console.error(
+			`${session_cite.issue(issue_number, undefined, repo)} is not an open issue in ${repo}.`,
+		)
 
 		return FAILURE_EXIT_CODE
 	}
@@ -436,8 +438,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	const repo = await git_gh_command.repo_get_name_with_owner()
 
-	// A repository that could not be read is refused rather than stood in for. Since
-	// joshuafolkken/kit#1130 the members are keyed by repository and the blockers carry their own, so a
+	// A repository that could not be read is refused rather than stood in for. The members are keyed
+	// by repository and the blockers carry their own, so a
 	// placeholder matches nothing: every recorded dependency would vanish and the command would answer
 	// `Nothing to bundle.` with exit 0 — a confident verdict built on a read that failed, on the
 	// command a run consults before deciding an issue belongs nowhere.
@@ -453,7 +455,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 // `process.exitCode` rather than `process.exit()`: 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 answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
-// is in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first (joshuafolkken/kit#1005).
+// is in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first.
 async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }

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

@@ -1,7 +1,7 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { epic_bundle, type BacklogIssue } from './epic-bundle'
 
-// The facts the bundle decision was already made from, printed beside the order it prints
-// (joshuafolkken/kit#1737).
+// The facts the bundle decision was already made from, printed beside the order it prints.
 //
 // `is_strong_signal` reads exactly two things — whether a body names the other issue's number, and
 // whether a `blocked-by` is already recorded in either direction — and neither ever reached the
@@ -75,7 +75,7 @@ function member_pairs(
 //
 // The repository filter is the one `bundle_dependency_links` applies: a bare number declared in a
 // member elsewhere would be resolved against this repository by the epic body, naming a different
-// issue entirely (joshuafolkken/kit#1130).
+// issue entirely.
 function ordering_evidence(
 	subject: BacklogIssue,
 	candidates: ReadonlyArray<BacklogIssue>,
@@ -118,8 +118,8 @@ const EVIDENCE_INDENT = ' '.repeat(EVIDENCE_INDENT_WIDTH)
 
 function format_one(item: OrderingEvidence): string {
 	const { verb, where, order_prefix, order_suffix } = EVIDENCE_WORDING[item.kind]
-	const first = `#${String(item.first)}`
-	const second = `#${String(item.second)}`
+	const first = issue_cite.plain(item.first)
+	const second = issue_cite.plain(item.second)
 	const order = `${order_prefix}${first}${order_suffix}`
 
 	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${where} — ${order}`

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

@@ -1,8 +1,7 @@
 import { cutoff_cause, type ScanCutoff } from '#scripts/git/listing-cutoff'
 
-// What `epic:bundle` could not see, said in the `⚠ … cap` shape joshuafolkken/kit#1033 settled on
-// for `epic:audit`. Split out of `epic-bundle-cli.ts` because the wording carries more explanation
-// than the command it warns from (joshuafolkken/kit#1067).
+// What `epic:bundle` could not see, said in the `⚠ … cap` shape `epic:audit` uses. Split out of
+// `epic-bundle-cli.ts` because the wording carries more explanation than the command it warns from.
 //
 // **Two listings, and two cuts each.** The listing decides *what* is hidden — a backlog issue, or
 // the epic that tracks one — and the cut decides *which number to cite*, because a reader who wants
@@ -21,7 +20,7 @@ function backlog_gap(cutoff: ScanCutoff, limit: number): string | undefined {
 
 // Named separately from the backlog's. What this one hides is *which epic tracks a candidate*, so
 // `Nothing to bundle.` under it may mean "the epic was past the cut" rather than "no epic tracks
-// it" — and acting on the second reading creates the duplicate epic (joshuafolkken/kit#950).
+// it" — and acting on the second reading creates the duplicate epic.
 function epic_gap(cutoff: ScanCutoff, limit: number): string | undefined {
 	const cause = cutoff_cause(cutoff, `hit its ${String(limit)}-epic cap`)
 	if (cause === undefined) return undefined
@@ -36,8 +35,7 @@ function epic_gap(cutoff: ScanCutoff, limit: number): string | undefined {
 // the assertion is only as good as the epic listing it was read from: an epic past the cut tracks its
 // children invisibly, so each of them reads as tracked by nothing. Acted on as Tier A, that absence
 // puts a **second** epic over an issue one already tracks — the state `fullrun.md` forbids, because
-// the auto-close then has two task lists to disagree about and `epic:next` answers from two graphs
-// (joshuafolkken/kit#943).
+// the auto-close then has two task lists to disagree about and `epic:next` answers from two graphs.
 //
 // A membership that *was* found is untouched, and that is the whole of what survives a cut: `none`
 // reporting `#E already tracks this issue` read the epic it names, and more epics past the cut cannot
@@ -46,12 +44,11 @@ function epic_gap(cutoff: ScanCutoff, limit: number): string | undefined {
 // The cut is the whole condition, and deliberately so. An epic the listing answered without a body
 // would hide its children the same way, but it cannot arrive: the listing mapping coerces a REST
 // `null` body to `''` before this module's caller ever parses one (`git-gh-issue-rest.ts`,
-// `to_gh_field_value`), so a gate arm for it would be code no input can reach
-// (joshuafolkken/kit#1697).
+// `to_gh_field_value`), so a gate arm for it would be code no input can reach.
 //
 // The cutoff is optional because the fetched backlog carries it that way: a listing nothing capped
 // records no cut at all, which is the same answer as `none`. Defaulted here rather than at each call
-// site, so a caller holding the optional field cannot forget the coercion (joshuafolkken/kit#1703).
+// site, so a caller holding the optional field cannot forget the coercion.
 function is_membership_established(cutoff: ScanCutoff = 'none'): boolean {
 	return cutoff === 'none'
 }

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

@@ -1,6 +1,6 @@
 import { poll, type PollOptions } from '#scripts/lib/poll'
 
-// **The open listing trails the create call** (joshuafolkken/kit#3332): `issue:file` asks
+// **The open listing trails the create call**: `issue:file` asks
 // `epic:bundle` about the issue it has just filed, and the list endpoint had not shown it yet on every
 // filing of one run, so the placement was skipped each time. A caller that knows the issue is fresh
 // passes a poll and the listing is read again until it shows the issue. An unreadable listing is

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

@@ -6,22 +6,20 @@ import { epic_issue, type EpicIssue } from './epic-issue'
 
 // Candidates the open backlog cannot show, read from the subject's own prose.
 //
-// `epic:bundle` searched open issues only, which left a window of minutes in which it could answer
-// correctly: a follow-up issue names its parent, and the parent's pull request merges right after —
-// on joshuafolkken/kit#943 the gap between filing and the parent closing was about three minutes.
-// Past it the command reported `Nothing to bundle.` with exit 0, asserting there was no relation
-// rather than that it had not looked (joshuafolkken/kit#947).
+// The open backlog alone cannot answer: a follow-up issue names its parent, and the parent's pull
+// request often merges minutes later. Searching open issues only would then report
+// `Nothing to bundle.` with exit 0, asserting there was no relation rather than that it had not looked.
 //
-// The numbers a body names are information the command already holds; the open listing was never
-// what supplied them. Only the *reading* of those issues needs a request, and this module decides
+// The numbers a body names are information the command already holds; the open listing is not
+// what supplies them. Only the *reading* of those issues needs a request, and this module decides
 // which ones are worth one and which of the answers count.
 
 // One read each, so the count is what bounds the cost. Chosen an order of magnitude above the
-// references a real issue body carries — kit#946's body names five — so the cap is a runaway guard
+// handful of references a real issue body carries, so the cap is a runaway guard
 // rather than something an ordinary issue reaches. A body naming more than this is prose about the
 // backlog, not an issue with twenty prerequisites.
 //
-// Since joshuafolkken/kit#1024 a read is `gh api`, and one reference costs one REST request in the
+// A read is `gh api`, and one reference costs one REST request in the
 // common case. Three cases cost two. The `dependencies/blocked_by` endpoint is asked unless the
 // issue's own dependency summary reports exactly zero blockers, so an issue that declares one pays
 // for it. So does a pull request, which the issue endpoint serves as readily as an issue and which
@@ -88,7 +86,7 @@ function to_backlog_issue(issue: EpicIssue, context: ReferencedContext): Backlog
 function is_usable_candidate(issue: BacklogIssue, read: EpicIssue): boolean {
 	// The issue endpoint answers for a pull request too, and a body citing "the fix landed in #952"
 	// is ordinary prose. Without this, a merged PR reads as an open issue in no epic and the command
-	// proposes creating an epic with a pull request among its children (joshuafolkken/kit#947).
+	// proposes creating an epic with a pull request among its children.
 	if (issue.is_epic === true || epic_issue.is_pull_request(read)) return false
 
 	return epic_issue.is_open(read.state) || issue.epic !== undefined
@@ -96,8 +94,7 @@ function is_usable_candidate(issue: BacklogIssue, read: EpicIssue): boolean {
 
 // How one referenced number came back. `missing` is GitHub resolving it to nothing — a typo, or a
 // number belonging to another repository quoted in prose — which is an answer, not a gap: there is
-// no candidate and nothing was lost. `unreadable` is the gap, and it is the only one reported
-// (joshuafolkken/kit#957).
+// no candidate and nothing was lost. `unreadable` is the gap, and it is the only one reported.
 interface ReferencedRead {
 	number: number
 	result: EpicIssue | 'missing' | 'unreadable'
@@ -113,7 +110,7 @@ interface ReferencedResult {
 	// The ones whose read failed, and the ones the cap never reached. Both are gaps rather than
 	// answers: folded into "no relation found" they become the confident wrong verdict this whole
 	// module exists to remove. A number that resolves to nothing is **not** here — reporting it as a
-	// gap stops an unattended run over a reference that never existed (joshuafolkken/kit#957).
+	// gap stops an unattended run over a reference that never existed.
 	unreadable: Array<number>
 }
 
@@ -156,7 +153,7 @@ async function read_one(number: number): Promise<ReferencedRead> {
 
 // The pool is shared with the eval suite rather than spelled out again here: this was written as
 // waves — slice, `Promise.all`, next slice — which holds every finished read's slot until the whole
-// slice returns (joshuafolkken/kit#1144).
+// slice returns.
 async function fetch_referenced(numbers: ReadonlyArray<number>): Promise<Array<ReferencedRead>> {
 	return await bounded_pool.bounded_map(
 		numbers,

package/scripts/epic/epic-bundle.ts

@@ -1,3 +1,4 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { epic_audit_logic } from './epic-audit'
 import { epic_graph } from './epic-graph'
 import type { DependencyLink } from './epic-parse'
@@ -7,11 +8,10 @@ import type { IssueReference } from './epic-reference'
 //
 // "Two or more always means an epic" already holds when one request is split on the spot. It does
 // not reach the other way in: two issues filed days apart that turn out to be the front and back of
-// one job are executed separately, in whatever order, with the reasoning recorded nowhere
-// (joshuafolkken/kit#873).
+// one job are executed separately, in whatever order, with the reasoning recorded nowhere.
 //
-// The candidate search reads issue references out of prose — the same reading joshuafolkken/kit#870
-// does inside one epic. That analysis is imported rather than written a second time; the only
+// The candidate search reads issue references out of prose — the same reading `epic:audit` does
+// inside one epic. That analysis is imported rather than written a second time; the only
 // difference is what it is pointed at.
 
 // An open issue as the search sees it.
@@ -21,17 +21,17 @@ interface BacklogIssue {
 	body: string
 	// Optional because nothing in this module reads it: the strong signals below are references and
 	// recorded dependencies, and a title resemblance is deliberately not one of them. It rides on the
-	// same listing for `issue:scout`, whose duplicate search is the one thing that does compare titles
-	// (joshuafolkken/kit#1252), and is absent on an issue read one at a time by reference.
+	// same listing for `issue:scout`, whose duplicate search is the one thing that does compare titles,
+	// and is absent on an issue read one at a time by reference.
 	title?: string
 	// The epic tracking it, when one does. An issue belongs to at most one epic, because that is what
 	// a task list can express.
 	epic?: number
 	// Whether this issue *is* an epic. An epic is a container, not a sibling: every child names it as
 	// its parent, so without this every child would find its own epic as a candidate and be told to
-	// bundle with it (joshuafolkken/kit#873, found by running the command on a real backlog).
+	// bundle with it.
 	is_epic?: boolean
-	// Repository-qualified, not bare numbers (joshuafolkken/kit#1130). Issue numbers are unique per
+	// Repository-qualified, not bare numbers. Issue numbers are unique per
 	// repository, so a blocker read as `40` alone matched any candidate numbered 40 — including one in
 	// a different repository entirely. That produced a bundle nobody's data supported, and, through
 	// `bundle_dependency_links`, a `blocked-by` relation recorded onto the wrong issue: a write, not
@@ -55,8 +55,7 @@ interface BundleDecision {
 
 // Whether `from`'s body names `to`. One direction of the citation test, because which direction it
 // was is what `epic-bundle-evidence.ts` reports — and the read is single-sourced here rather than
-// written a second time there, so the candidate search and the evidence beside it cannot drift apart
-// (joshuafolkken/kit#1737).
+// written a second time there, so the candidate search and the evidence beside it cannot drift apart.
 function names_in_body(from: BacklogIssue, to: BacklogIssue): boolean {
 	return epic_audit_logic.parse_references(from.body, from.repo).includes(to.number)
 }
@@ -117,10 +116,10 @@ const NO_SIGNAL_REASON = 'no existing issue shares a reference or a dependency w
 
 // Names the epic, rather than only reporting that one exists. The number is what the caller does
 // something with: the prerequisite procedure inserts into that epic instead of creating a second one,
-// and an issue tracked by two epics gives the auto-close two task lists to disagree about
-// (joshuafolkken/kit#943). The decision already carried the number; only this sentence dropped it.
+// 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 `#${String(epic)} already tracks this issue`
+	return `${issue_cite.plain(epic)} already tracks this issue`
 }
 
 const SPREAD_REASON =
@@ -132,13 +131,13 @@ function to_numbers(candidates: ReadonlyArray<BacklogIssue>): Array<number> {
 
 function create_decision(subject: BacklogIssue, numbers: ReadonlyArray<number>): BundleDecision {
 	const count = String(numbers.length)
-	const reason = `#${String(subject.number)} and ${count} related issue(s) belong to no epic`
+	const reason = `${issue_cite.plain(subject.number)} and ${count} related issue(s) belong to no epic`
 
 	return { action: 'create_epic', epics: [], candidates: numbers, reason }
 }
 
 // Which epic each issue is itself tracked by. An epic is a row of the backlog like any other, so a
-// nested one carries its own parent here and no second read is needed (joshuafolkken/kit#1079).
+// nested one carries its own parent here and no second read is needed.
 // The repository filter is defensive: every caller stamps one repository onto the whole listing
 // today, and the filter is what keeps a bare epic number naming the subject's repository if one ever
 // assembles two.
@@ -181,8 +180,8 @@ function is_cyclic(
 }
 
 // Nested epics are not two peers to choose between: the parent already contains the child, so an
-// issue related to both belongs in the child and no merge is on the table. Asking anyway is the
-// false positive joshuafolkken/kit#1079 recorded three times, one of which stopped a whole batch.
+// issue related to both belongs in the child and no merge is on the table. Asking anyway is a false
+// positive that can stop a whole batch.
 function narrow_to_innermost(
 	epics: ReadonlyArray<number>,
 	parents: ReadonlyMap<number, number>,
@@ -200,7 +199,7 @@ 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 = `#${String(epic)} already tracks a related issue`
+	const tracks = `${issue_cite.plain(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`
@@ -256,7 +255,7 @@ function decide_bundle(
 
 // The dependency links a bundle should record, from what the candidates already declare. Bundling
 // without the order records the batch and loses the reason it is a batch — an issue that must follow
-// another is exactly the case this exists to catch (joshuafolkken/kit#873).
+// another is exactly the case this exists to catch.
 //
 // Only relations already declared are carried over; an order nobody stated is not invented here.
 function bundle_dependency_links(
@@ -269,7 +268,7 @@ function bundle_dependency_links(
 	// rather than from each member: comparing a blocker against its *own* member's repository would
 	// let two members elsewhere emit a link between them, and the epic body would then resolve those
 	// bare numbers against this repository — a different pair of issues. `epic_graph.child_links`
-	// guards the identical case the identical way (joshuafolkken/kit#1130).
+	// guards the identical case the identical way.
 	const declared_repo = subject.repo
 
 	return members

package/scripts/epic/epic-busy.ts

@@ -7,21 +7,19 @@ import {
 	IN_PROGRESS_LABEL,
 	NEEDS_DECISION_LABEL,
 } from '#scripts/issue/issue-labels'
+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
-// the epic (joshuafolkken/kit#925), and counted rather than treated as a yes/no since
-// joshuafolkken/kit#1491.
+// the epic, and counted rather than treated as a yes/no.
 //
 // `epic-classify.ts` sorts only the children the epic tracks, so an `in-progress` issue belonging to
 // a *different* epic is invisible to it: start two `epicrun`s and both answer "nothing of mine is in
 // progress". This read is what closes that gap, and it is deliberately outside the classification —
 // the question is not about the graph.
 //
-// **What an `in-progress` issue holds is one lane, not the repository.** Until joshuafolkken/kit#1490
-// the contended resource really was one working tree, one `main` and one `pnpm-lock.yaml`, so one
-// holder excluded everything. A lane is its own checkout with its own branch and its own ports, so
-// the question stopped being "is anything running" and became "how many are running" — and the
-// answer is a count the caller compares against `lane_capacity`'s limit.
+// **What an `in-progress` issue holds is one lane, not the repository.** A lane is its own checkout
+// 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
 // their own memory give twelve lanes; the label on an open issue is the one record both of them
@@ -37,14 +35,14 @@ const LISTING_LIMIT = 100
 // `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
 //
 // `already-done` joins `needs-decision` here for the same reason it joins it in
-// `epic_classify.local_category` (joshuafolkken/kit#1679): the run that applied it committed
+// `epic_classify.local_category`: the run that applied it committed
 // nothing, so the checkout it ran in is clean and there is no uncommitted work for the next child to
 // start on top of. That is exactly what separates both from `needs-human-review`, which is
 // deliberately not parked because its work is still sitting in the tree.
 const PARKED_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
 
-// What one repository answered. `unreadable` is kept apart from `idle` for the reason
-// joshuafolkken/kit#950 records: reading a failed read as an empty listing is a confident absence
+// What one repository answered. `unreadable` is kept apart from `idle` because reading a failed
+// read as an empty listing is a confident absence
 // built on a response nobody parsed — and here that absence *starts* work, which is the one
 // direction a guard must never fail in.
 //
@@ -55,12 +53,14 @@ const PARKED_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREAD
 // children are read first, and one that could not be read is already an anomaly that exits 1. What
 // is left at this line is transient, and `wait` self-heals where an exit needs a person.
 //
-// **`truncated` is kept apart from `idle` for the same reason, one step further in**
-// (joshuafolkken/kit#1067). Since the page ceiling applies to every listing, a listing can now come
+// **`truncated` is kept apart from `idle` for the same reason, one step further in**.
+// Since the page ceiling applies to every listing, a listing can now come
 // back well-formed, short, and missing the very issue that holds this repository — and "no holder in
 // the rows I was given" is not "no holder". It is grouped with `unreadable` rather than with `idle`
 // because what it authorizes is identical: nothing. It gets its own kind only so the message names
 // the real cause — `unreadable_message` sends a reader to `gh auth status`, which is green here.
+const NO_AGES: ReadonlyMap<number, string> = new Map()
+
 type BusyRead =
 	| { kind: 'idle' }
 	| { kind: 'busy'; issues: ReadonlyArray<OpenIssueData> }
@@ -69,9 +69,25 @@ type BusyRead =
 
 // Named so the reader can go and look at them: the stale-label rule is what keeps an abandoned
 // `in-progress` from holding a repository forever, and it cannot be applied to an issue nobody was
-// told about.
-function format_holders(issues: ReadonlyArray<OpenIssueData>): string {
-	return issues.map((issue) => `#${String(issue.number)} ${issue.title}`).join(', ')
+// told about. Each holder's label age is printed beside it when the caller read one,
+// since the age is what that rule is applied against.
+function format_holder(
+	issue: OpenIssueData,
+	repo: string,
+	ages: ReadonlyMap<number, string>,
+): string {
+	const cite = session_cite.issue(issue.number, issue.title, repo)
+	const age = ages.get(issue.number)
+
+	return age === undefined ? cite : `${cite} (${age})`
+}
+
+function format_holders(
+	issues: ReadonlyArray<OpenIssueData>,
+	repo: string,
+	ages: ReadonlyMap<number, string>,
+): string {
+	return issues.map((issue) => format_holder(issue, repo, ages)).join(', ')
 }
 
 // How many lanes this read shows occupied. Every kind but `busy` is zero, and the two that could not
@@ -87,8 +103,9 @@ function occupancy_message(
 	issues: ReadonlyArray<OpenIssueData>,
 	repo: string,
 	limit: number,
+	ages: ReadonlyMap<number, string> = NO_AGES,
 ): string {
-	return `${String(issues.length)} of ${String(limit)} lanes in use in ${repo}: ${format_holders(issues)}.`
+	return `${String(issues.length)} of ${String(limit)} lanes in use in ${repo}: ${format_holders(issues, repo, ages)}.`
 }
 
 // The occupancy said once, with the consequence appended — rather than a second sentence that
@@ -97,15 +114,16 @@ function lanes_full_message(
 	issues: ReadonlyArray<OpenIssueData>,
 	repo: string,
 	limit: number,
+	ages: ReadonlyMap<number, string> = NO_AGES,
 ): string {
-	return `${occupancy_message(issues, repo, limit)} No lane is free, so nothing is offered here. A lane is released when its child merges or is parked; if a label is stale, remove it and ask again, and \`JOSH_LANE_LIMIT\` is what raises the ceiling.`
+	return `${occupancy_message(issues, repo, limit, ages)} No lane is free, so nothing is offered here. A lane is released when its child merges or is parked; if a label is stale, remove it and ask again, and \`JOSH_LANE_LIMIT\` is what raises the ceiling.`
 }
 
 function unreadable_message(repo: string): string {
 	return `Could not read the \`${IN_PROGRESS_LABEL}\` listing for ${repo}. That is not "nothing is running" — check \`gh auth status\` and ask again.`
 }
 
-// Said in the `⚠ … cap` shape joshuafolkken/kit#1033 settled on, because it is the same kind of
+// Said in the shared `⚠ … cap` shape, because it is the same kind of
 // statement: the read happened and covered less than the whole listing. What it means here is
 // stronger than elsewhere, so the message says the consequence out loud rather than leaving a reader
 // to infer it from a warning marker.
@@ -129,8 +147,13 @@ const BUSY_REASONS: Readonly<
 	truncated: truncated_message,
 }
 
-function busy_reason(read: BusyRead, repo: string, limit: number): string {
-	if (read.kind === 'busy') return lanes_full_message(read.issues, repo, limit)
+function busy_reason(
+	read: BusyRead,
+	repo: string,
+	limit: number,
+	ages: ReadonlyMap<number, string> = NO_AGES,
+): string {
+	if (read.kind === 'busy') return lanes_full_message(read.issues, repo, limit, ages)
 	if (read.kind === 'idle') return ''
 
 	return BUSY_REASONS[read.kind](repo)
@@ -141,7 +164,7 @@ function busy_reason(read: BusyRead, repo: string, limit: number): string {
 // `in-progress` and so calls a parked child `human` rather than `time`. Two readings of one issue
 // have to agree, and without this they do not — nothing removes `in-progress` when a child is
 // parked, so `park and continue` would spend a lane on the very child it just set aside, and with
-// one lane the run would poll instead of continuing (joshuafolkken/kit#925). A child stopped by
+// 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 {