@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/epic/epic-graph.ts

@@ -11,13 +11,13 @@ import {
 // `epic:next` has to build this graph anyway to decide what is runnable, so the anomaly checks live
 // here rather than in a separate auditor: a cycle makes every session wait forever, and a body that
 // declares one order while the `blocked-by` relations record another means the implementation would
-// proceed in an order nobody agreed to (joshuafolkken/kit#860).
+// proceed in an order nobody agreed to.
 
 // One child, as the graph sees it. `repo` is the `owner/repo` the child lives in, so a caller can
 // bundle candidates per repository.
 //
-// `blocked_by` carries the native relations **with their repository**, not as bare numbers
-// (joshuafolkken/kit#1126). A relation may cross a repository — REST records and returns one — and a
+// `blocked_by` carries the native relations **with their repository**, not as bare numbers.
+// A relation may cross a repository — REST records and returns one — and a
 // number alone cannot say which repository it names, so a bare read resolved every blocker against
 // the blocked child's own repository. A cross-repository blocker then keyed to an issue that does not
 // exist, `blocker_categories` dropped it, and the child ran as though nothing blocked it. It also
@@ -41,15 +41,15 @@ interface GraphAnomaly {
 	// Set when the reads behind this anomaly failed on the transport, so a caller can ask again
 	// instead of reporting an unusable graph. It travels from the failed request itself rather than
 	// from a probe fired afterwards, which is what let a connection that recovered in a few hundred
-	// milliseconds report the graph as permanently broken (joshuafolkken/kit#1690).
+	// milliseconds report the graph as permanently broken.
 	is_unreachable?: boolean
 }
 
 // An issue's identity across the whole epic. Issue numbers are unique per repository, not globally:
 // an epic tracking both `#7` and `app-kit#7` has two different children, and keying by number alone
-// had them overwrite each other — and had one's blockers resolve against the other
-// (joshuafolkken/kit#864). The audit keys the issues its children *cite* the same way, through this
-// one function rather than a second spelling of it (joshuafolkken/kit#1014).
+// would have them overwrite each other — and one's blockers resolve against the other.
+// The audit keys the issues its children *cite* the same way, through this
+// one function rather than a second spelling of it.
 function reference_key(repo: string, issue_number: number): string {
 	return `${repo}${to_issue_reference(issue_number)}`
 }
@@ -61,13 +61,11 @@ function key_of(reference: IssueReference): string {
 
 // How a reference is written in a message. Bare inside the repository the command runs in — the form
 // every body writes and every existing message used — and `owner/repo#N` outside it, because a bare
-// number resolves against the reader's own repository and names a different issue there
-// (joshuafolkken/kit#864).
+// number resolves against the reader's own repository and names a different issue there.
 //
 // It lives here rather than in the audit, beside the key it is the readable half of: `epic:next`
 // reports the children it could not read too, and a second spelling there would print a bare `#7`
-// for a child in another repository — the very misreading this exists to prevent
-// (joshuafolkken/kit#1016).
+// for a child in another repository — the very misreading this exists to prevent.
 function format_reference(reference: IssueReference, current_repo: string): string {
 	const is_local = reference.repo === '' || reference.repo === current_repo
 
@@ -81,9 +79,9 @@ function format_references(
 	return join_references(references.map((reference) => format_reference(reference, current_repo)))
 }
 
-// A blocker's key, read from the blocker's own repository rather than from the child it blocks
-// (joshuafolkken/kit#1126). The child is no longer part of the answer: taking the repository from it
-// is exactly what sent a cross-repository blocker to this repository's issue of that number.
+// A blocker's key, read from the blocker's own repository rather than from the child it blocks.
+// The child is not part of the answer: taking the repository from it
+// would send a cross-repository blocker to this repository's issue of that number.
 function blocker_key(blocker: IssueReference): string {
 	return key_of(blocker)
 }
@@ -140,7 +138,7 @@ function find_stuck_children(children: ReadonlyArray<EpicChild>): Array<string>
 //
 // Declared links are always written as bare numbers, which name issues in the epic's own repository —
 // so the blocker they name is matched against that repository rather than against any relation that
-// happens to carry the number (joshuafolkken/kit#1126).
+// happens to carry the number.
 function is_link_recorded(
 	link: DependencyLink,
 	children: ReadonlyArray<EpicChild>,
@@ -171,7 +169,7 @@ function missing_relations(
 // The other half: declared links a relation actually backs. It is what a caller about to *drop*
 // relations needs — asking `gh` to remove a link that was never recorded is reported as a failure
 // nobody can act on. Written beside `missing_relations` rather than as a subtraction in each caller,
-// so the two answers cannot come to disagree about what "recorded" means (joshuafolkken/kit#1712).
+// so the two answers cannot come to disagree about what "recorded" means.
 function recorded_relations(
 	links: ReadonlyArray<DependencyLink>,
 	children: ReadonlyArray<EpicChild>,
@@ -182,7 +180,7 @@ function recorded_relations(
 
 // Every relation recorded on one child, as links between children of this epic.
 //
-// Matched by identity rather than by number (joshuafolkken/kit#1126): keyed by number alone, a child
+// Matched by identity rather than by number: keyed by number alone, a child
 // in another repository whose number happened to equal a blocker's was reported as a relation nobody
 // recorded. Only relations inside the declared repository become links, because a declared link is
 // written as a bare number and has no way to name one that crosses a repository.

package/scripts/epic/epic-index.ts

@@ -6,9 +6,9 @@ import { EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 import { z } from 'zod'
 import { epic_parse } from './epic-parse'
 
-// Which epic tracks which issue — the one answer, in one place (joshuafolkken/kit#1633).
+// Which epic tracks which issue — the one answer, in one place.
 //
-// `epic:bundle` has asked it since joshuafolkken/kit#873, to keep an issue an epic already tracks
+// `epic:bundle` asks it to keep an issue an epic already tracks
 // from being recommended a second one. The `auto-ok` pickup needs the same answer for the opposite
 // reason: an issue tracked by an epic that will offer it must run through that epic's order and
 // never be picked up standalone. Two callers, one question, so the read and the index live here
@@ -27,7 +27,7 @@ interface FetchedEpics {
 }
 
 // Which epics track each issue, from the epics' own task lists. **A child can be named by more than
-// one** (joshuafolkken/kit#1694): a task list expresses at most one epic per row, and nothing stops
+// one**: a task list expresses at most one epic per row, and nothing stops
 // two epics writing the same row — `epic_lane_offer.dedupe_pools` has handled exactly that collision
 // on the `epic:next` side since it was written. So the tracking is recorded whole here, and each
 // caller collapses it for its own question rather than losing the other epics at build time.
@@ -104,8 +104,8 @@ function child_epics_of(
 }
 
 // Every epic an `auto-ok` root opts in — the root itself and, transitively, every nested epic reached
-// through its task list and theirs in turn (joshuafolkken/kit#2244). A person puts `auto-ok` on a root
-// to approve everything under it, and the direct-children-only reading (joshuafolkken/kit#1668) stopped
+// through its task list and theirs in turn. A person puts `auto-ok` on a root
+// to approve everything under it, and the direct-children-only reading stopped
 // one level short: a grandchild fell out as "not opted in", though the same reasoning that admits the
 // child admits it. So the root's approval is read down the whole subtree rather than one level of it.
 //
@@ -132,32 +132,30 @@ function reachable_epic_numbers(
 }
 
 // **Which wins when an epic's declared order and a child's own `auto-ok` disagree — the single
-// source** (joshuafolkken/kit#1668, narrowing joshuafolkken/kit#1633).
+// source**.
 //
 // The epic wins wherever the epic is actually going to offer the child, and only there. So the
 // standalone half withholds a tracked child when the epic tracking it carries `auto-ok`: that epic's
 // `blocked-by` graph sequences its children, and offering the child standalone as well would both
 // skip that order and hand the same issue over twice.
 //
-// It withholds nothing when the tracking epic is **not** opted in. joshuafolkken/kit#1633 dropped
-// that child too, on the ground that the standalone path read none of the ordering graph — which has
-// since stopped being true: `auto_ok_cli.is_runnable` refuses a candidate whose `blockedBy` is still
-// open, and `josh epic --ordered` records an epic's declared order as exactly those native
-// relations. So the order survives the standalone route, while the old rule left a person's `auto-ok`
-// on the child silently inert — no path offered it at all, because the epic side never reads an epic
-// that did not opt in.
+// It withholds nothing when the tracking epic is **not** opted in. The standalone route keeps the
+// order: `auto_ok_cli.is_runnable` refuses a candidate whose `blockedBy` is still open, and
+// `josh epic --ordered` records an epic's declared order as exactly those native relations. Withholding
+// that child too would leave a person's `auto-ok` on it silently inert — no path would offer it at
+// all, because the epic side never reads an epic that did not opt in.
 // **It answers with the epic, not merely with membership**, because the withholding and the sentence
 // `backlog:plan` prints about it have to come from one answer. Handing the scope layer the whole
-// index instead let it name an epic that was not withholding anything — the same misreport, moved.
+// index instead would let it name an epic that was not withholding anything.
 //
-// **Any one opted-in epic withholds the child** (joshuafolkken/kit#1694). It reads the whole tracking
+// **Any one opted-in epic withholds the child**. It reads the whole tracking
 // rather than one collapsed winner because the two are not the same answer when two epics name the
 // same child: collapsed, an opted-in epic that merely came earlier in the listing is gone, the child
 // reads as tracked by nobody who would offer it, and the standalone half hands it over while the
 // opted-in epic hands it over too. The epic named as the reason is the first opted-in one in listing
 // order — any of them is withholding it, and picking by position keeps the sentence deterministic.
 //
-// **The opted-in set is the transitive closure, not one level of it** (joshuafolkken/kit#2244). A
+// **The opted-in set is the transitive closure, not one level of it**. A
 // child of a nested epic is withheld from the standalone half exactly when that nested epic is one the
 // backlog is going to offer — which, since the closure reaches it, it now is. Withholding only the
 // direct roots' children here would leave a nested epic's child offered both through the epic and

package/scripts/epic/epic-issue.ts

@@ -1,19 +1,17 @@
 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_safe } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 import type { IssueReference } from './epic-reference'
 
 // The shapes one issue is read as, and the argument every epic command takes.
 //
-// The read goes through `gh api` (REST) since joshuafolkken/kit#1024; `git-gh-issue-rest.ts` maps
-// the response back into the field names `gh issue view --json …` used, so the shapes below are
-// the ones they always were.
+// The read goes through `gh api` (REST); `git-gh-issue-rest.ts` maps the response back into the
+// field names `gh issue view --json …` uses, so the shapes below are those.
 //
 // Single-sourced because three commands read the same JSON and take the same argument. Each had its
 // own copy of the schema, the `blockedBy` unwrapping and the number parser, which is three places to
-// fix the next time `gh` changes shape — and the one place a divergence would not be noticed
-// (joshuafolkken/kit#862).
+// fix the next time `gh` changes shape — and the one place a divergence would not be noticed.
 
 const label_schema = z.object({ name: z.string() })
 
@@ -33,7 +31,7 @@ const epic_issue_schema = z.object({
 	state: z.string().default(UNKNOWN_STATE),
 	// The issue endpoint answers for a pull request as readily as for an issue, and nothing in the
 	// other fields separates them — an open PR reports `state: OPEN`, a merged one `MERGED`. The URL
-	// is what says which it is: `/pull/<n>` against `/issues/<n>` (joshuafolkken/kit#947).
+	// is what says which it is: `/pull/<n>` against `/issues/<n>`.
 	url: z.string().default(''),
 	labels: z.array(label_schema).default([]),
 	blockedBy: blocked_by_schema,
@@ -47,14 +45,14 @@ function parse_epic_issue(raw: string | undefined): EpicIssue | undefined {
 	if (raw === undefined) return undefined
 
 	try {
-		return parse_json_object_safe(raw, epic_issue_schema)
+		return parse_json_object_or_undefined(raw, epic_issue_schema)
 	} catch {
 		return undefined
 	}
 }
 
 // The blockers an issue declares, unwrapped from the connection and carrying the repository each one
-// lives in (joshuafolkken/kit#1126).
+// lives in.
 //
 // `fallback_repo` is what an unqualified relation has always meant: the repository the issue itself is
 // read in. REST names the blocker's repository in `repository_url`, and a relation may cross one — so
@@ -63,7 +61,7 @@ function parse_epic_issue(raw: string | undefined): EpicIssue | undefined {
 //
 // The parameter is narrowed to the one field this reads, so a caller holding a differently-shaped
 // issue — `backlog-pool.ts`'s standalone rows arrive as `OpenIssueData` — resolves through this same
-// function instead of repeating the `repository_url` unwrapping (joshuafolkken/kit#1654).
+// function instead of repeating the `repository_url` unwrapping.
 function blocker_references_of(
 	issue: Pick<EpicIssue, 'blockedBy'>,
 	fallback_repo = '',
@@ -112,7 +110,7 @@ function parse_epic_number(raw = ''): number | undefined {
 //
 // A cross-repository epic must be qualified. A bare `#858` resolves to *this* repository's issue 858
 // — a different issue entirely — so reading it as the other repository's would silently point at the
-// wrong thing (joshuafolkken/kit#864).
+// wrong thing.
 interface EpicReference {
 	repo?: string
 	number: number

package/scripts/epic/epic-label-age.ts

@@ -0,0 +1,74 @@
+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'
+
+// 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
+// `gh api …/timeline` query a parent ran per holder. `epic:next` now prints it beside each holder, so
+// the number the rule is applied against is the one the scheduler already showed.
+//
+// **Read only in `epic:next`'s offer, and only when it names holders.** A timeline read per holder is
+// a request per lane, so the listing polled by `run:progress` / `backlog:next` does not pay it.
+
+// 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`
+
+// The newest time the label was applied. `absent` is a timeline holding no such event — the label is
+// older than what the timeline keeps — and `unread` is a timeline that could not be read at all. Kept
+// apart because only the first is a reason to call the label stale.
+type LabeledAt = { kind: 'at'; at: string } | { kind: 'absent' } | { kind: 'unread' }
+
+async function read_labeled_at(issue: number, repo: string): Promise<LabeledAt> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({
+			path: `${git_gh_api_path.issue_api_path(String(issue), repo)}/timeline?per_page=${String(TIMELINE_PAGE)}`,
+			should_paginate: true,
+			jq_filter: LABELED_FILTER,
+		})
+		const at = raw.split('\n').findLast((line) => line.trim() !== '')
+
+		return at === undefined ? { kind: 'absent' } : { kind: 'at', at }
+	} catch {
+		return { kind: 'unread' }
+	}
+}
+
+function age_text(labeled_at: LabeledAt, now: Date): string {
+	if (labeled_at.kind === 'unread') return 'label age unread'
+	if (labeled_at.kind === 'absent') return `${IN_PROGRESS_LABEL} older than the timeline — stale`
+
+	const minutes = Math.floor((now.getTime() - Date.parse(labeled_at.at)) / MS_PER_MINUTE)
+	const stale = minutes > STALE_MINUTES ? ' — stale' : ''
+
+	return `${IN_PROGRESS_LABEL} for ${String(minutes)} min${stale}`
+}
+
+async function read_ages(
+	issues: ReadonlyArray<number>,
+	repo: string,
+	now: Date,
+): Promise<ReadonlyMap<number, string>> {
+	const ages = await Promise.all(
+		issues.map(async (issue) => {
+			const labeled_at = await read_labeled_at(issue, repo)
+
+			return [issue, age_text(labeled_at, now)] as const
+		}),
+	)
+
+	return new Map(ages)
+}
+
+const epic_label_age = {
+	STALE_MINUTES,
+	read_labeled_at,
+	age_text,
+	read_ages,
+}
+
+export type { LabeledAt }
+export { epic_label_age }

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

@@ -6,26 +6,23 @@ import {
 	type RepoAnswer,
 } from './epic-candidate-confirm'
 import { epic_graph, type EpicChild } from './epic-graph'
+import { epic_label_age } from './epic-label-age'
 import { epic_rank } from './epic-rank'
 import type { EpicVerdict } from './epic-report'
 import { epic_solo } from './epic-solo'
 import { epic_solo_stale } from './epic-solo-stale'
 import { epic_triage, type TriageVerdict } from './epic-triage'
 
-// Which children a repository has room to start right now (joshuafolkken/kit#1491).
+// Which children a repository has room to start right now.
 //
-// Until joshuafolkken/kit#1490 the answer was one or none: the contended resource was one working
-// tree, so a single `in-progress` issue excluded everything else in that repository. A lane is its
-// own checkout, so the question became how many are free — the repository's occupancy counted from
-// GitHub, compared against `lane_capacity`'s limit.
+// A lane is its own checkout, so the question is how many are free — the repository's occupancy
+// counted from GitHub, compared against `lane_capacity`'s limit.
 //
 // **The pool takes several sources, and none of them is an epic.** `RepoPool` is a candidate list
-// with the context needed to confirm it. Since joshuafolkken/kit#1493 `epic:next` builds one per
-// named epic and passes them all, which cost the caller change this design predicted and no rewrite
-// of the scheduler: the signatures never learned what an epic is, because once the guarded resource
-// is the lane rather than the repository, which epic a child came from stops mattering. The one
-// thing several sources did add is `dedupe_pools` below — two epics can name the same child, and one
-// child is one lane.
+// with the context needed to confirm it. `epic:next` builds one per named epic and passes them all;
+// the signatures never learn what an epic is, because once the guarded resource is the lane rather
+// than the repository, which epic a child came from stops mattering. The one thing several sources
+// add is `dedupe_pools` below — two epics can name the same child, and one child is one lane.
 
 const WAIT_VERDICT: EpicVerdict = 'wait'
 const RUN_VERDICT: EpicVerdict = 'run'
@@ -83,11 +80,24 @@ function offered_notice(
 	children: ReadonlyArray<EpicChild>,
 	read: BusyRead,
 	request: LaneRequest,
+	ages: ReadonlyMap<number, string>,
 ): string {
 	if (children.length === NO_LANES) return withheld_message(request.repo)
 	if (read.kind !== 'busy') return ''
 
-	return epic_busy.occupancy_message(read.issues, request.repo, request.limit)
+	return epic_busy.occupancy_message(read.issues, request.repo, request.limit, ages)
+}
+
+// Each holder's label age, read only when there are holders to print — a
+// timeline request per lane is paid for nothing on a read that names no one.
+async function holder_ages(read: BusyRead, repo: string): Promise<ReadonlyMap<number, string>> {
+	if (read.kind !== 'busy') return new Map()
+
+	return await epic_label_age.read_ages(
+		read.issues.map((issue) => issue.number),
+		repo,
+		new Date(),
+	)
 }
 
 // Two pools that both offered nothing can disagree about why, and the answer has to be the one that
@@ -102,7 +112,7 @@ function combine_verdicts(left: EpicVerdict, right: EpicVerdict): EpicVerdict {
 
 // Every pool is a source of candidates **for the repository the request names**. The free-lane count
 // was read for that one repository, so spending it on a child that lives somewhere else would
-// allocate a lane nobody counted — the double-allocation joshuafolkken/kit#925 exists to prevent.
+// allocate a lane nobody counted.
 // Dropped rather than offered: a caller with children in two repositories asks twice, once per
 // repository, exactly as `--repo` already makes it.
 function candidates_in(pool: RepoPool, repo: string): RepoPool {
@@ -110,7 +120,7 @@ function candidates_in(pool: RepoPool, repo: string): RepoPool {
 }
 
 // A pool's candidates for the repository in `epic_rank.rank` order — the ranking `backlog:next` offers
-// in (joshuafolkken/kit#2928), counted against the pool's own graph. **Within a pool, not across
+// in, counted against the pool's own graph. **Within a pool, not across
 // pools**: the pool order is the order a person named the epics in, and that stays the outer key.
 function ranked_in(pool: RepoPool, repo: string): RepoPool {
 	const scoped = candidates_in(pool, repo)
@@ -135,8 +145,8 @@ function unseen_candidates(pool: RepoPool, seen: Set<string>): RepoPool {
 }
 
 // A child two epics both track is still one child, and entering it twice would open two lanes on one
-// issue — two branches, two pull requests, and the second one merging over the first
-// (joshuafolkken/kit#1493). Keyed through `epic_graph.key_of`, the one spelling of an issue's
+// issue — two branches, two pull requests, and the second one merging over the first.
+// Keyed through `epic_graph.key_of`, the one spelling of an issue's
 // identity in this package: a bare number names a different issue in another repository.
 //
 // **The earlier pool keeps it**, and that is a decision rather than an accident of iteration order.
@@ -179,13 +189,14 @@ async function collect(
 	return { children, verdict: children.length > NO_LANES ? RUN_VERDICT : verdict }
 }
 
-// The `run:solo` gate `backlog:next` applies, applied to a named epic's lanes too
-// (joshuafolkken/kit#2776): the confirmed children are cut where `epic_solo.select` says, so a
+// The `run:solo` gate `backlog:next` applies, applied to a named epic's lanes too:
+// the confirmed children are cut where `epic_solo.select` says, so a
 // `run:solo` child never opens a lane beside another one on either path.
 function solo_offer(
 	answer: { children: ReadonlyArray<EpicChild>; verdict: EpicVerdict },
 	read: BusyRead,
 	request: LaneRequest,
+	ages: ReadonlyMap<number, string>,
 ): LaneOffer {
 	const { offered, notice = '' } = epic_solo.select(answer.children, read, request.repo)
 
@@ -193,15 +204,14 @@ function solo_offer(
 		return { children: [], verdict: WAIT_VERDICT, notice }
 	}
 
-	return { ...answer, children: offered, notice: offered_notice(offered, read, request) }
+	return { ...answer, children: offered, notice: offered_notice(offered, read, request, ages) }
 }
 
-// The repository is asked how full it is **before** any candidate is confirmed, for the reason
-// joshuafolkken/kit#1121 records: a repository with no free lane is handed nothing, so the relations
+// The repository is asked how full it is **before** any candidate is confirmed: a repository with no free lane is handed nothing, so the relations
 // request that would confirm a candidate there buys an answer nobody reads — and a polling `epicrun`
 // would pay it every round.
 //
-// **Triage is asked before even that** (joshuafolkken/kit#2779): an untriaged candidate withholds every
+// **Triage is asked before even that**: an untriaged candidate withholds every
 // candidate whatever the occupancy, and it needs only the labels already read. Only a `--lanes` ask
 // is gated — it is the one that opens children beside each other; the single-child form starts one.
 function triage_offer(pools: ReadonlyArray<RepoPool>, request: LaneRequest): LaneOffer | undefined {
@@ -238,18 +248,19 @@ async function offer_for_repo(
 	if (notice !== undefined) console.error(notice)
 
 	const free = free_lanes(read, request.limit)
+	const ages = await holder_ages(read, request.repo)
 
 	if (free === NO_LANES) {
 		return {
 			children: [],
 			verdict: WAIT_VERDICT,
-			notice: epic_busy.busy_reason(read, request.repo, request.limit),
+			notice: epic_busy.busy_reason(read, request.repo, request.limit, ages),
 		}
 	}
 
 	const for_repo = dedupe_pools(pools.map((pool) => ranked_in(pool, request.repo)))
 
-	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request)
+	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request, ages)
 }
 
 const epic_lane_offer = {

package/scripts/epic/epic-nested.ts

@@ -1,7 +1,7 @@
 import { EPIC_LABEL, has_label_name } from '#scripts/issue/issue-labels'
 import type { EpicChild } from './epic-graph'
 
-// Whether a task-list row points at another epic (joshuafolkken/kit#1476).
+// Whether a task-list row points at another epic.
 //
 // An epic's body can hold `- [ ] #<another epic>` — nothing stops it being typed — and until this
 // module nothing read it. `epic-classify.ts` sorted the row like any other child and

package/scripts/epic/epic-next-read.ts

@@ -1,16 +1,17 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_cross_repo } from './epic-cross-repo'
 import { epic_fetch, type EpicSnapshot } from './epic-fetch'
 import { epic_graph } from './epic-graph'
 import type { EpicReference } from './epic-issue'
 
-// Reading the epics `josh epic:next` was given, before anything is classified (joshuafolkken/kit#1493).
+// Reading the epics `josh epic:next` was given, before anything is classified.
 //
 // Split from the command itself because naming several epics turned one read into a walk, and a walk
 // has answers a single read did not: an epic that was skipped, and one that stopped everything.
 
 // A qualified epic is read by naming its repository in the read's REST path, so naming one we do
-// not own would send this command to a third party's tracker — which joshuafolkken/kit#869 forbids
-// for a child and forbids here for the same reason (joshuafolkken/kit#1016).
+// not own would send this command to a third party's tracker — forbidden for a child, and forbidden
+// here for the same reason.
 const FOREIGN_EPIC = 'That epic belongs to another owner; this command only reads our own.'
 const NO_CHILDREN = 0
 
@@ -46,7 +47,7 @@ function epic_repo_of(reference: EpicReference, current_repo: string): string |
 }
 
 function childless(reference: EpicReference): string {
-	return `#${String(reference.number)} tracks no children in a task list.`
+	return `${session_cite.issue(reference.number, undefined, reference.repo)} tracks no children in a task list.`
 }
 
 // The same epic named twice is one epic. Removed here rather than left to
@@ -76,8 +77,7 @@ function unique_references(
 // **An epic whose body could not be read is not a childless epic.** The two are indistinguishable
 // downstream — a body that never arrived parses to zero children exactly as an unpopulated task list
 // does — and skipping it drops the epic from the views with no anomaly anywhere, so the run reports
-// the backlog empty and ends. Kept as a read instead, so `epic:next` sees the failed body and says so
-// (joshuafolkken/kit#1690).
+// the backlog empty and ends. Kept as a read instead, so `epic:next` sees the failed body and says so.
 function is_childless(snapshot: EpicSnapshot): boolean {
 	if (snapshot.body_failure !== undefined) return false
 
@@ -89,7 +89,7 @@ function is_childless(snapshot: EpicSnapshot): boolean {
 // stops the command. An epic that is simply not populated yet is a valid, readable epic of ours — an
 // epic whose task list has not been filled in is the ordinary case — and refusing the
 // whole command for it would stop every *other* named epic's children being offered, on every
-// polling round, until a person noticed (joshuafolkken/kit#1493).
+// polling round, until a person noticed.
 async function read_one(reference: EpicReference, current_repo: string): Promise<ReadOutcome> {
 	const epic_repo = epic_repo_of(reference, current_repo)
 	if (epic_repo === undefined) return { refusal: FOREIGN_EPIC }
@@ -107,7 +107,7 @@ function collect(outcome: ReadOutcome, reads: Array<EpicRead>, notices: Array<st
 
 // **The reads are serial on purpose.** A reference naming another owner has to stop the command
 // before that repository is asked anything, and issuing them together would send every fetch before
-// the first refusal was seen — the read joshuafolkken/kit#1016 exists to prevent. The latency is the
+// the first refusal was seen — the very read the refusal exists to prevent. The latency is the
 // price of that guarantee, and `unique_references` above is what keeps it from being paid twice for
 // one epic.
 async function read_snapshots(

package/scripts/epic/epic-next-views.ts

@@ -1,3 +1,4 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import type { ConfirmContext } from './epic-candidate-confirm'
 import { epic_cross_repo } from './epic-cross-repo'
 import { epic_fetch, type EpicSnapshot } from './epic-fetch'
@@ -6,13 +7,12 @@ import type { EpicReference } from './epic-issue'
 import { epic_lane_offer, type RepoPool } from './epic-lane-offer'
 import { epic_report, type EpicNextResult, type EpicVerdict } from './epic-report'
 
-// Several epics, answered as one (joshuafolkken/kit#1493).
+// Several epics, answered as one.
 //
-// joshuafolkken/kit#1491 built the lane pool epic-agnostic on purpose: `epic-lane-offer.ts` takes an
-// array of `RepoPool`s and nothing below it knows what an epic is. What was still fixed at one was
-// the *caller* — `epic:next` read a single reference and built a single pool — so a repository with
-// six free lanes could only ever fill them from one graph. This module is that caller's other half:
-// one view per named epic, merged into one pool list and one verdict.
+// The lane pool is epic-agnostic on purpose: `epic-lane-offer.ts` takes an array of `RepoPool`s and
+// nothing below it knows what an epic is. A *caller* that read a single reference and built a single
+// pool would still leave a repository with six free lanes filling them from one graph. This module is
+// that caller's other half: one view per named epic, merged into one pool list and one verdict.
 //
 // **The priority order is the order the epics were named**, and it is a decision rather than a
 // fallback. Dependency depth was the alternative and it does not compare across graphs: depth is
@@ -37,20 +37,20 @@ interface EpicView {
 	snapshot: EpicSnapshot
 	result: EpicNextResult
 	// Every issue this invocation may run — the children of all the named epics, plus a backlog's
-	// standalone issues — which a candidate's blockers are re-weighed against at confirmation
-	// (joshuafolkken/kit#1943). Absent, a view confirms against its own epic's children alone.
+	// standalone issues — which a candidate's blockers are re-weighed against at confirmation.
+	// Absent, a view confirms against its own epic's children alone.
 	running?: ReadonlySet<string>
 }
 
 // Written exactly as it was typed. A bare number stays bare, because qualifying it here would name
 // this repository in an answer about an epic the caller referred to without one.
 function format_reference(reference: EpicReference): string {
-	return `${reference.repo ?? ''}#${String(reference.number)}`
+	return issue_cite.plain(reference.number, reference.repo)
 }
 
 // What the candidate confirmation reads with. The blockers come from `epic_fetch`'s own reader, so
 // a candidate is addressed exactly as every other read of a child is — a cross-repository child
-// through its own repository, and a local one bare (joshuafolkken/kit#1012).
+// through its own repository, and a local one bare.
 function confirm_context(snapshot: EpicSnapshot, running?: ReadonlySet<string>): ConfirmContext {
 	return {
 		children: snapshot.children,
@@ -108,8 +108,8 @@ function aggregate_text(views: ReadonlyArray<EpicView>, current_repo: string): s
 	return views.map((view) => format_view(view, is_many, current_repo)).join(BLOCK_SEPARATOR)
 }
 
-// The running set with every issue that waits on a person taken out, and the views built from it
-// (joshuafolkken/kit#1943). A blocker in another named epic only waits when that blocker itself can
+// The running set with every issue that waits on a person taken out, and the views built from it.
+// A blocker in another named epic only waits when that blocker itself can
 // finish: one parked, or one that is itself blocked from outside, holds its dependants for a person
 // exactly as a parked blocker inside one epic does. Each pass removes what the previous one sent to a
 // person, so the set only shrinks, and the walk ends at the first pass that removes nothing.