@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/backlog/backlog-plan-cli.ts

@@ -1,21 +1,15 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
-import { epic_index } from '#scripts/epic/epic-index'
-import type { EpicNextResult } from '#scripts/epic/epic-report'
-import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
-import { read_json_listing } from '#scripts/git/parse-json-array'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_named } from './backlog-named'
-import { backlog_next, type OptedIn } from './backlog-next'
-import { backlog_plan, type NamedPlan, type PlanContext } from './backlog-plan'
-import type { GateScope } from './backlog-rank'
+import { backlog_next } from './backlog-next'
+import { backlog_plan, type NamedPlan } from './backlog-plan'
+import { backlog_plan_read, type OpenListing, type Plan } from './backlog-plan-read'
 import { backlog_scope } from './backlog-scope'
 import { backlog_waves } from './backlog-waves'
 
-// `josh backlog:plan` — the whole backlog as a plan a person reads before a run starts
-// (joshuafolkken/kit#1652).
+// `josh backlog:plan` — the whole backlog as a plan a person reads before a run starts.
 //
 // `backlog:next` already answers what may start, and a `backlogrun` acted on that answer one ask at a
 // time, so nothing ever showed the shape of the run: the order, which issue waits on which, what is
@@ -33,13 +27,12 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 
 // The keyword `run_invocation` parses a named-issue prefix behind, reused rather than parsing `#N`
-// again here so the `0` / leading-zero / safe-integer rules stay single-sourced (joshuafolkken/kit#1984).
+// again here so the `0` / leading-zero / safe-integer rules stay single-sourced.
 const NAMED_COMMAND = 'backlogrun'
 // The flag that runs the named list and stops, mirrored here so the plan the person reads before the
-// run shows the same scope the run will take (joshuafolkken/kit#1984).
+// run shows the same scope the run will take.
 const ONLY_FLAG = '--only'
-// The flag that renders the run's order wave by wave instead of the pool's sections
-// (joshuafolkken/kit#2778).
+// The flag that renders the run's order wave by wave instead of the pool's sections.
 const WAVES_FLAG = '--waves'
 
 const USAGE =
@@ -76,7 +69,7 @@ function without_flags(argv: ReadonlyArray<string>): ReadonlyArray<string> {
 // The one start-time refusal: `--only` with no named issues has nothing to run. `backlog_named` is the
 // single source of that decision, so the plan and the run refuse it alike. The refusal turns only on
 // whether anything was named, so the items are built with `is_epic: false` — which item is an epic is
-// decided by the run at dispatch time, not here (joshuafolkken/kit#1985).
+// decided by the run at dispatch time, not here.
 function only_refusal(named: ReadonlyArray<number>, is_only: boolean): string | undefined {
 	const items = named.map((issue) => ({ issue, is_epic: false }))
 	const startup = backlog_named.startup(items, is_only)
@@ -84,9 +77,8 @@ function only_refusal(named: ReadonlyArray<number>, is_only: boolean): string |
 	return startup.kind === 'refused' ? startup.reason : undefined
 }
 
-// A failed open listing is not "nothing is out of scope". Reported rather than rendered around, for
-// the reason joshuafolkken/kit#950 records: a confident absence built on a read that failed is worse
-// than no answer.
+// A failed open listing is not "nothing is out of scope". Reported rather than rendered around,
+// because a confident absence built on a read that failed is worse than no answer.
 const OPEN_UNREADABLE_MESSAGE =
 	"Could not read this repository's open issues, so the out-of-scope half of the plan cannot be told from an empty one. Check `gh auth status` and ask again."
 
@@ -95,82 +87,14 @@ const OPEN_UNREADABLE_MESSAGE =
 // every other one. Reported as a gap, the way `backlog:next` reports its own truncated listings.
 const OPEN_TRUNCATED_MESSAGE = `⚠ The open-issue listing stopped at ${String(auto_ok_cli.LISTING_LIMIT)} rows, so the out-of-scope section is partial, some titles are missing, and a blocker that has since closed can still be named. The plan below is incomplete.`
 
-interface Plan {
-	result: EpicNextResult
-	repo: string
-	exclude: ReadonlyArray<number>
-	// Which **opted-in** epic is withholding which issue, narrowed by the same function the pool
-	// decided membership with (joshuafolkken/kit#1668). Without it the scope layer had no branch for
-	// "an epic is offering this one instead", so every opted-in row it could not place was reported as
-	// past the listing cap. Carrying the *whole* index here instead would move that misreport rather
-	// than remove it: the sentence would name an epic that is withholding nothing.
-	tracked: ReadonlyMap<number, number>
-	// The rows the offer's cap bounds and the paths each issue restructures, so `--waves` cuts each
-	// wave where `backlog:next` does (joshuafolkken/kit#2928, joshuafolkken/kit#3221).
-	scope: GateScope
-}
-
-// The listing plus whether it was cut. Carried together because the rows alone cannot say whether
-// what is missing from them is absent or merely past the cap.
-interface OpenListing {
-	rows: ReadonlyArray<OpenIssueData>
-	is_capped: boolean
-}
-
 // Which rendering was asked for: the named prefix the sections lead with, or the waves.
 interface PlanView {
 	named: NamedPlan
 	is_waves: boolean
 }
 
-// The same reads and the same classification `backlog:next` makes, through the same two functions.
-// `undefined` is a failure it has already reported.
-async function classify(
-	opted_in: OptedIn,
-	exclude: ReadonlyArray<number>,
-): Promise<Plan | undefined> {
-	const context = await backlog_next.context_of(opted_in, exclude)
-
-	if (context === undefined) return undefined
-
-	const result = await backlog_next.resolve(context)
-
-	if (result === undefined) return undefined
-
-	return {
-		result,
-		repo: context.repo,
-		exclude,
-		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
-		scope: backlog_next.gate_scope(context),
-	}
-}
-
-// Every open issue, read once. It carries both halves the plan needs and the pool does not hold: the
-// titles, and the set the out-of-scope rows are subtracted from. One read serves both, so the plan
-// costs exactly one `gh` call more than the answer it is rendering.
-async function fetch_open(): Promise<OpenListing | undefined> {
-	const { json, is_capped } = await git_gh_command.issue_list_recent(auto_ok_cli.LISTING_LIMIT)
-
-	if (json === undefined) return undefined
-
-	const read = read_json_listing(json, open_issue_schema)
-
-	return read.kind === 'read' ? { rows: read.rows, is_capped } : undefined
-}
-
-// A cut listing cannot say an issue is closed, only that it was not read — so the blocker filter is
-// switched off rather than fed a set that would silently report standing blockers as gone.
-function context_of(plan: Plan, listing: OpenListing): PlanContext {
-	return {
-		repo: plan.repo,
-		titles: backlog_scope.titles_of(listing.rows),
-		open_numbers: listing.is_capped ? undefined : backlog_scope.open_numbers_of(listing.rows),
-	}
-}
-
 function print_plan(plan: Plan, listing: OpenListing, view: PlanView): void {
-	const context = context_of(plan, listing)
+	const context = backlog_plan_read.context_of(plan, listing)
 
 	if (view.is_waves) {
 		console.info(backlog_waves.format_waves(plan.result, context, plan.scope))
@@ -185,7 +109,7 @@ function print_plan(plan: Plan, listing: OpenListing, view: PlanView): void {
 }
 
 async function report(plan: Plan, view: PlanView): Promise<number> {
-	const listing = await fetch_open()
+	const listing = await backlog_plan_read.fetch_open()
 
 	if (listing === undefined) {
 		console.error(OPEN_UNREADABLE_MESSAGE)
@@ -216,7 +140,7 @@ async function run_plan(rest: ReadonlyArray<string>, view: PlanView): Promise<nu
 		return FAILURE_EXIT_CODE
 	}
 
-	const plan = await classify(opted_in, options.exclude ?? [])
+	const plan = await backlog_plan_read.classify(opted_in, options.exclude ?? [])
 
 	return plan === undefined ? FAILURE_EXIT_CODE : await report(plan, view)
 }
@@ -242,7 +166,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const rest = without_flags(argv)
 	// Read the named block from the *original* argv, so `--only` placed before the `#N` block breaks the
 	// leading block exactly as the run grammar does — the plan then refuses an ordering the run refuses,
-	// rather than promising a scope the resumed invocation would stop on (joshuafolkken/kit#1984).
+	// rather than promising a scope the resumed invocation would stop on.
 	const named = named_of(argv)
 	const refusal = refusal_of(named, rest, is_only, is_waves)
 

package/scripts/backlog/backlog-plan-read.ts

@@ -0,0 +1,111 @@
+import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
+import { epic_index } from '#scripts/epic/epic-index'
+import type { EpicNextResult } from '#scripts/epic/epic-report'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { backlog_next, type OptedIn } from './backlog-next'
+import type { PlanContext } from './backlog-plan'
+import type { GateScope } from './backlog-rank'
+import { backlog_scope } from './backlog-scope'
+
+// The reads a backlog plan is drawn from — `backlog:plan`'s and `run:board`'s.
+// Moved out of `backlog-plan-cli.ts` so the board places each issue through the very classification the
+// plan prints, rather than a second copy of it that could promise a different order.
+
+interface Plan {
+	result: EpicNextResult
+	repo: string
+	exclude: ReadonlyArray<number>
+	// Which **opted-in** epic is withholding which issue, narrowed by the same function the pool
+	// decided membership with. Without it the scope layer had no branch for
+	// "an epic is offering this one instead", so every opted-in row it could not place was reported as
+	// past the listing cap. Carrying the *whole* index here instead would move that misreport rather
+	// than remove it: the sentence would name an epic that is withholding nothing.
+	tracked: ReadonlyMap<number, number>
+	// The rows the offer's cap bounds and the paths each issue declares, so `--waves` cuts each
+	// wave where `backlog:next` does.
+	scope: GateScope
+}
+
+// The listing plus whether it was cut. Carried together because the rows alone cannot say whether
+// what is missing from them is absent or merely past the cap.
+interface OpenListing {
+	rows: ReadonlyArray<OpenIssueData>
+	is_capped: boolean
+}
+
+// A plan with the open listing it is rendered against.
+interface PlanRead {
+	plan: Plan
+	listing: OpenListing
+}
+
+// The same reads and the same classification `backlog:next` makes, through the same two functions.
+// `undefined` is a failure it has already reported.
+async function classify(
+	opted_in: OptedIn,
+	exclude: ReadonlyArray<number>,
+): Promise<Plan | undefined> {
+	const context = await backlog_next.context_of(opted_in, exclude)
+
+	if (context === undefined) return undefined
+
+	const result = await backlog_next.resolve(context)
+
+	if (result === undefined) return undefined
+
+	return {
+		result,
+		repo: context.repo,
+		exclude,
+		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
+		scope: backlog_next.gate_scope(context),
+	}
+}
+
+// Every open issue, read once. It carries both halves the plan needs and the pool does not hold: the
+// titles, and the set the out-of-scope rows are subtracted from. One read serves both, so the plan
+// costs exactly one `gh` call more than the answer it is rendering.
+async function fetch_open(): Promise<OpenListing | undefined> {
+	const { json, is_capped } = await git_gh_command.issue_list_recent(auto_ok_cli.LISTING_LIMIT)
+
+	if (json === undefined) return undefined
+
+	const read = read_json_listing(json, open_issue_schema)
+
+	return read.kind === 'read' ? { rows: read.rows, is_capped } : undefined
+}
+
+// A cut listing cannot say an issue is closed, only that it was not read — so the blocker filter is
+// switched off rather than fed a set that would silently report standing blockers as gone.
+function context_of(plan: Plan, listing: OpenListing): PlanContext {
+	return {
+		repo: plan.repo,
+		titles: backlog_scope.titles_of(listing.rows),
+		open_numbers: listing.is_capped ? undefined : backlog_scope.open_numbers_of(listing.rows),
+	}
+}
+
+// The whole read, end to end, for a caller that only needs to know whether it succeeded — `run:board`
+// keeps its previous plan on `undefined` rather than drawing an empty one.
+async function with_listing(plan: Plan | undefined): Promise<PlanRead | undefined> {
+	if (plan === undefined) return undefined
+
+	const listing = await fetch_open()
+
+	return listing === undefined ? undefined : { plan, listing }
+}
+
+async function read_plan(exclude: ReadonlyArray<number> = []): Promise<PlanRead | undefined> {
+	const opted_in = await auto_ok_cli.fetch_opted_in()
+
+	if (opted_in.kind !== 'read') return undefined
+
+	return await with_listing(await classify(opted_in, exclude))
+}
+
+const backlog_plan_read = { classify, context_of, fetch_open, read_plan }
+
+export { backlog_plan_read }
+export type { OpenListing, Plan, PlanRead }

package/scripts/backlog/backlog-plan.ts

@@ -7,7 +7,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
-// The plan a person reads before a `backlogrun` starts (joshuafolkken/kit#1652).
+// The plan a person reads before a `backlogrun` starts.
 //
 // `backlog:next` answers the **next** question — which numbers may start now — and its report is
 // shaped for the loop that consumes it. This renders the **whole** picture from the same classified
@@ -20,11 +20,11 @@ const ROW_INDENT_WIDTH = 4
 const ROW_INDENT = ' '.repeat(ROW_INDENT_WIDTH)
 const NOTHING = `${ROW_INDENT}(none)`
 
-// The named-issue prefix of a `backlogrun #N1 #N2 …` (joshuafolkken/kit#1984): these run one at a
+// The named-issue prefix of a `backlogrun #N1 #N2 …`: these run one at a
 // time, in the order they were typed, before anything in the pool below is picked up.
 const NAMED_HEADING = 'Named issues — run in order first, one at a time, then the backlog:'
-// `--only` runs the named list and stops, so its heading says the pool is not drained
-// (joshuafolkken/kit#1984). The plan then shows the named section alone.
+// `--only` runs the named list and stops, so its heading says the pool is not drained.
+// The plan then shows the named section alone.
 const ONLY_NAMED_HEADING =
 	'Named issues — run in order, one at a time, then stop (`--only`; the opted-in backlog is not run):'
 const READY_HEADING =
@@ -57,16 +57,16 @@ interface PlanContext {
 }
 
 // A child elsewhere is qualified, because a bare number would name *this* repository's issue of that
-// number — a different issue (joshuafolkken/kit#1016). Takes the reference rather than the child, so
-// a `blocked_by` edge is named by the same rule the child itself is. This repository's issue is cited
-// (joshuafolkken/kit#3099): the plan is copied into a report verbatim, so the line it prints is the
+// number — a different issue. Takes the reference rather than the child, so
+// a `blocked_by` edge is named by the same rule the child itself is. This repository's issue is cited:
+// the plan is copied into a report verbatim, so the line it prints is the
 // citation the report carries.
 function cite_of(reference: IssueReference, repo: string, title: string | undefined): string {
 	const number = String(reference.number)
 
 	return reference.repo === repo
 		? issue_cite.reference(repo, number, title)
-		: `${reference.repo}#${number}`
+		: issue_cite.plain(number, reference.repo)
 }
 
 function reference_of(reference: IssueReference, repo: string): string {
@@ -84,10 +84,10 @@ function join_row(reference: string, note: string): string {
 }
 
 // A `run:solo` child is marked beside its number, so a person reading the plan sees which issues
-// `backlog:next` will start alone before the run starts (joshuafolkken/kit#2776).
+// `backlog:next` will start alone before the run starts.
 const SOLO_MARK = `[${RUN_SOLO_LABEL}]`
 // A child with neither `run:solo` nor `run:lane` is one `backlog:next` withholds everything for until
-// it is judged (joshuafolkken/kit#2779), so the plan says which ones before the run asks.
+// it is judged, so the plan says which ones before the run asks.
 const UNTRIAGED_MARK = '[untriaged]'
 
 function mark_of(child: EpicChild): string | undefined {
@@ -260,6 +260,7 @@ const backlog_plan = {
 	WAITING_HEADING,
 	format_plan,
 	format_unusable,
+	is_standing,
 	marked_reference,
 	row_of,
 	section,

package/scripts/backlog/backlog-pool.ts

@@ -14,7 +14,7 @@ import {
 	NEEDS_DECISION_LABEL,
 } from '#scripts/issue/issue-labels'
 
-// The candidate pool `josh backlog:next` answers from (joshuafolkken/kit#1630).
+// The candidate pool `josh backlog:next` answers from.
 //
 // Two sources feed one pool: the opted-in issues no epic tracks, and the children of the epics whose
 // **root** carries `auto-ok`. Splitting them apart lives here so the command itself stays a list of
@@ -26,8 +26,8 @@ import {
 const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
 // The labels that put a withheld row in the "needs a person" bucket rather than the "waiting on
 // time" one. `already-done` belongs with `needs-decision` because no amount of waiting moves it: the
-// work is merged and the close is Tier C, so a person is the only thing that resolves it
-// (joshuafolkken/kit#1679). Read as `time`, it would be reported as something that resolves itself
+// work is merged and the close is Tier C, so a person is the only thing that resolves it.
+// Read as `time`, it would be reported as something that resolves itself
 // and nobody would ever be told to close it.
 const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
 
@@ -35,7 +35,7 @@ const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALRE
 // instead, the ones the caller has named as done, and the repository the rows belong to.
 //
 // `tracked` is the narrowed set `epic_index.withheld_children` builds, not every child an epic
-// tracks (joshuafolkken/kit#1668) — the narrowing itself is defined there, once, for this half and
+// tracks — the narrowing itself is defined there, once, for this half and
 // `auto-ok:next` alike.
 // Child number to every open epic whose task list names it — `epic_index.build_tracking_index`.
 type TrackingIndex = ReadonlyMap<number, ReadonlyArray<number>>
@@ -47,7 +47,7 @@ interface StandaloneContext {
 	tracked: ReadonlyMap<number, number>
 	exclude: ReadonlyArray<number>
 	repo: string
-	// Every issue this backlog may run (joshuafolkken/kit#1943). A row whose open blocker is outside it
+	// Every issue this backlog may run. A row whose open blocker is outside it
 	// waits on a person rather than on time, exactly as an epic child's does.
 	running: ReadonlySet<string>
 }
@@ -77,7 +77,7 @@ function epic_keys_of(tracking: TrackingIndex, repo: string): ReadonlySet<string
 	return new Set([...tracking.values()].flat().map((number) => epic_graph.key_of({ repo, number })))
 }
 
-// The set with every epic that tracks a member added, nested epics included (joshuafolkken/kit#3289).
+// The set with every epic that tracks a member added, nested epics included.
 // An epic is a container rather than work, so it is never run itself — but it closes once its children
 // do, so a row blocked by it waits on time exactly when one of those children is in this run.
 function with_tracking_epics(
@@ -136,8 +136,8 @@ function settle_standalone(
 // classification covers all of them and the verdict is decided once rather than per source.
 //
 // `repo` stamps the row itself, never its blockers: issue numbers are unique per repository, so a
-// blocker read bare resolves against the *reading* repository and names a different issue there
-// (joshuafolkken/kit#1654). `epic_issue.blocker_references_of` is the epic side's own resolution —
+// blocker read bare resolves against the *reading* repository and names a different issue there.
+// `epic_issue.blocker_references_of` is the epic side's own resolution —
 // `repository_url` when the node names one, this repository only as the fallback an unqualified
 // relation has always meant — and it is reused rather than repeated.
 function to_child(issue: OpenIssueData, repo: string): EpicChild {
@@ -155,7 +155,7 @@ function to_children(issues: ReadonlyArray<OpenIssueData>, repo: string): Array<
 }
 
 // The epics whose `auto-ok` stands for their children — the opted-in roots and, transitively, every
-// nested epic reached through their task lists (joshuafolkken/kit#2244, extending joshuafolkken/kit#1668).
+// nested epic reached through their task lists.
 //
 // The roots come out of the opted-in listing itself: an epic that carries `auto-ok` is a row in that
 // listing which also carries `epic`, so no second listing reads an epic's labels. From each root the
@@ -177,8 +177,7 @@ function standalone_rows(issues: ReadonlyArray<OpenIssueData>): ReadonlyArray<Op
 }
 
 // A row an **opted-in** epic tracks belongs to that epic's order and never to the standalone half —
-// the rule joshuafolkken/kit#1633 established, narrowed by joshuafolkken/kit#1668 to the epics that
-// are actually going to offer their children and applied here for the same reason. Which rows those
+// limited to the epics that are actually going to offer their children. Which rows those
 // are is `epic_index.withheld_children`'s answer, not a second test made here. A row the caller
 // excluded is out of the pool entirely rather than merely unoffered: it has just merged.
 function is_considered(issue: OpenIssueData, context: ConsideredContext): boolean {
@@ -193,7 +192,7 @@ function is_considered(issue: OpenIssueData, context: ConsideredContext): boolea
 // and everything else — a standing blocker, a run already in progress — resolves on its own and is
 // waiting on time.
 //
-// **The display's cap is not applied here** (joshuafolkken/kit#2928). Cut at this point, a sixth
+// **The display's cap is not applied here**. Cut at this point, a sixth
 // runnable `run:solo` issue never reached the gate that holds back what is ranked below it, so the
 // cap is applied after that gate instead (`backlog-rank.ts`). A row past it is still reported as
 // waiting and offered by a later ask, so the backlog drains without it ever being lost.
@@ -221,8 +220,8 @@ function classify_standalone(
 	}
 }
 
-// Every issue the backlog may run: each opted-in epic's children and the standalone rows
-// (joshuafolkken/kit#1943). A child is opted in through its epic's `auto-ok` even where it carries none
+// Every issue the backlog may run: each opted-in epic's children and the standalone rows.
+// A child is opted in through its epic's `auto-ok` even where it carries none
 // of its own, which is why the set is built from the graphs that were read rather than from labels. A
 // standalone row a person has to resolve is left out, so a row waiting on it waits for that person too;
 // an epic child in the same state is taken out by `epic_next_views.settle_views`. An open epic with a

package/scripts/backlog/backlog-rank.ts

@@ -4,18 +4,18 @@ import { epic_rank } from '#scripts/epic/epic-rank'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
-import { backlog_restructure, type Declared } from './backlog-restructure'
+import { backlog_overlap, type Declared } from './backlog-overlap'
 
-// What the backlog offers, in the order it is decided (joshuafolkken/kit#2928): rank, then the
+// What the backlog offers, in the order it is decided: rank, then the
 // `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
 // plan's first wave is what the run starts into an idle repository rather than an order the run never
 // takes.
 //
-// **The cap comes last.** It used to be applied while the standalone half was classified, before the
-// gate, so a `run:solo` issue ranked sixth or lower was cut before the gate could see it — and the
-// issues below it were offered past it. Cut after the gate, the cap only ever removes what the gate
-// would have offered, so it cannot hide a waiting `run:solo` issue from it. It still bounds only the
-// standalone rows, as it always has; an epic's children were never capped.
+// **The cap comes last.** Applied while the standalone half is classified, before the gate, it would
+// cut a `run:solo` issue ranked sixth or lower before the gate could see it — and offer the issues
+// below it past it. Cut after the gate, the cap only ever removes what the gate would have offered,
+// so it cannot hide a waiting `run:solo` issue from it. It bounds only the standalone rows; an epic's
+// children are never capped.
 
 // Every child the classification placed, in the order it placed them: the ranked candidates first,
 // then the waiting ones, then the ones waiting on a person.
@@ -79,18 +79,18 @@ interface OfferInput {
 	repo: string
 	// The keys of the standalone rows — the ones the cap bounds.
 	standalone: ReadonlySet<string>
-	// The paths each issue restructures; two candidates claiming one are not offered together
-	// (joshuafolkken/kit#3221). Absent, nothing is separated.
+	// The paths each issue declares; two candidates whose paths overlap are not offered together.
+	// Absent, nothing is separated.
 	declared?: Declared
 }
 
-// The restructure separation runs before the cap, for the reason the gate does: the cap only ever
+// The overlap separation runs before the cap, for the reason the gate does: the cap only ever
 // removes what would otherwise be offered.
 function select(input: OfferInput): SoloSelection {
 	const ranked = rank(input.candidates, input.pool)
 	const { read, repo } = input
 	const gated = epic_solo.select(ranked, read, repo)
-	const separated = backlog_restructure.separate(gated, input.declared ?? new Map(), { read, repo })
+	const separated = backlog_overlap.separate(gated, input.declared ?? new Map(), { read, repo })
 
 	return cap(separated, input.standalone)
 }

package/scripts/backlog/backlog-ready.ts

@@ -23,11 +23,15 @@ interface ReadyPorts {
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
-async function free_under(limit: number): Promise<number> {
+// The lanes in use: the open worktrees an interruption has not stranded. `josh lane:limit` prints it.
+async function live_lane_count(): Promise<number> {
 	const lanes = await lane_registry.list_lanes()
-	const live = lanes.filter((lane) => !lane.is_stranded).length
 
-	return lane_capacity.free_lanes(limit, live)
+	return lanes.filter((lane) => !lane.is_stranded).length
+}
+
+async function free_under(limit: number): Promise<number> {
+	return lane_capacity.free_lanes(limit, await live_lane_count())
 }
 
 // Free lanes right now: the limit less the live lanes. An unreadable limit reads as no free lane — the
@@ -40,25 +44,25 @@ async function free_under(limit: number): Promise<number> {
 // (`backlog:next`) is gated behind a free lane, so a network read here would defeat that design. The
 // two can diverge, but only toward over-counting live lanes → fewer free lanes, the safe direction.
 async function free_lane_count(): Promise<number> {
-	const limit = lane_capacity.lane_limit()
+	const limit = await lane_capacity.lane_limit()
 
 	if (limit.kind !== 'limit') return NO_FREE
 
 	return await free_under(limit.limit)
 }
 
-// **The drive's count throws on an unreadable limit** (joshuafolkken/kit#3027). The drive launches no
+// **The drive's count throws on an unreadable limit**. The drive launches no
 // more than this count, so the safe-direction zero above would leave it launching nothing and reporting
 // nothing for good; a bad setting is the hard error `lane_capacity` says it is, ending the drive loudly.
 async function drive_free_lane_count(): Promise<number> {
-	const limit = lane_capacity.lane_limit()
+	const limit = await lane_capacity.lane_limit()
 
 	if (limit.kind !== 'limit') throw new Error(limit.problem)
 
 	return await free_under(limit.limit)
 }
 
-// **A `--only` run has no pool to drain** (joshuafolkken/kit#2472). `backlog:next` lists the opted-in
+// **A `--only` run has no pool to drain**. `backlog:next` lists the opted-in
 // pool, and a `--only` run's work is its named list — issues and epics that run in order through their
 // own step, never through the pick-up ask — so a ready pool issue is neither a stall nor an ask it owes.
 // Without a `--only` record the pool is the run's, whole.
@@ -67,7 +71,7 @@ function drains_pool(carry: RunCarry | undefined): boolean {
 }
 
 // The `backlog:next` read, or `undefined` for a `--only` run, which answers none before paying for the
-// network read. A bounded read (joshuafolkken/kit#2503) keeps stderr piped: the arrival probe reads once
+// network read. A bounded read keeps stderr piped: the arrival probe reads once
 // a minute, and a forwarded refusal would fill the watcher's output.
 async function read_backlog_next(timeout_ms?: number): Promise<JoshResult | undefined> {
 	if (!drains_pool(await run_headless.current_carry())) return undefined
@@ -95,7 +99,7 @@ async function read_ready(ports: ReadyPorts = DEFAULT_PORTS): Promise<ReadyReadi
 }
 
 // `undefined` unless there is both runnable work and a lane for it — the only state worth a line. Each
-// issue is a number-link against `slug` (joshuafolkken/kit#3099): the parent copies this line into its
+// issue is a number-link against `slug`: the parent copies this line into its
 // report, so a bare `#N` here is the citation the Stop guard sends back.
 function ready_line(reading: ReadyReading, slug: string | undefined): string | undefined {
 	if (reading.issues.length === NONE || reading.free_lanes <= NO_FREE) return undefined
@@ -141,7 +145,7 @@ async function print_ready_line(
 
 // The line `epic --add` prints once a child entered an epic while a `backlogrun` parent drives this
 // checkout: a filing made mid-run joins the pool the moment it is placed, so the parent asks now rather
-// than on the next wake (joshuafolkken/kit#2452). The recommendation commands (`issue:scout`,
+// than on the next wake. The recommendation commands (`issue:scout`,
 // `epic:bundle`) carry none — before the insertion the child is in no pool the ask could find.
 const OFFER_HINT =
 	'↻ backlogrun parent: a child just entered an epic — run `pnpm josh backlog:offer` next, so a ' +
@@ -163,6 +167,7 @@ const backlog_ready = {
 	read_backlog_next,
 	print_offer_hint,
 	free_lane_count,
+	live_lane_count,
 	drive_free_lane_count,
 	drains_pool,
 	print_ready_line,

package/scripts/backlog/backlog-scope.ts

@@ -1,29 +1,28 @@
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
 
-// Which open issues the backlog will not run, and why (joshuafolkken/kit#1652).
+// Which open issues the backlog will not run, and why.
 //
 // **The set is a subtraction, never a second membership rule.** Everything open that the pool did not
 // classify is out of scope, so this cannot drift from what `backlog:next` offers the way a
 // re-implemented "is it opted in" test would. What is decided per row is only the sentence saying
 // why, and each of those is read off a label rather than judged.
 //
-// It exists because the exclusion used to be silent: an issue without `auto-ok`, or a child of an
-// epic whose root lacks it, never enters the pool at all, so a person watching a `backlogrun` could
-// not tell "not opted in" from "the backlog has not reached it yet".
+// It exists because an issue without `auto-ok` never enters the pool at all, so without this a person
+// watching a `backlogrun` could not tell "not opted in" from "the backlog has not reached it yet".
 //
-// A child of an epic whose root lacks `auto-ok` is no longer one of those — since
-// joshuafolkken/kit#1668 its own label carries it into the standalone half, so it is offered rather
-// than explained. What is still explained here is the child of an epic that **is** opted in and that
-// the epic did not place, and telling that apart from a row past the listing cap is the whole of
-// `opted_in_reason` below.
+// A child of an epic whose root lacks `auto-ok` is not one of those — its own label carries it into
+// the standalone half, so it is offered rather than explained. What is explained here is the child of
+// an epic that **is** opted in and that the epic did not place, and telling that apart from a row past
+// the listing cap is the whole of `opted_in_reason` below.
 
 const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
 const AUTO_OK_LABELS: ReadonlySet<string> = new Set([AUTO_OK_LABEL])
 
 const NO_OPT_IN_REASON = 'not opted in — no `auto-ok` label'
-// Since joshuafolkken/kit#1668 this no longer speaks for the children: an epic that did not opt in
+// This does not speak for the children: an epic that did not opt in
 // offers none of them, but each child carrying `auto-ok` of its own is offered by the standalone
 // half. Saying "its children are not offered" here would contradict the plan's own ready section.
 const EPIC_NOT_OPTED_IN_REASON =
@@ -31,13 +30,13 @@ const EPIC_NOT_OPTED_IN_REASON =
 const EPIC_ROOT_REASON = 'epic root — a container, so its children are planned instead of it'
 const OPTED_IN_UNPLACED_REASON = 'opted in, but past the listing cap this ask could read'
 
-// The cap is what the row above says, and it used to be said of every opted-in row the plan could
-// not place — including the ones the cap had nothing to do with (joshuafolkken/kit#1668). An issue an
+// The cap is what the row above says, and it is not said of every opted-in row the plan could not
+// place — only of the ones the cap has to do with. An issue an
 // opted-in epic tracks is offered through that epic and not standalone, so when the epic did not
 // place it either, the epic is the fact worth naming and the cap is a misreport a reader acts on:
 // "past the cap" reads as "the next ask will offer it", and the next ask never does.
 function epic_tracked_reason(epic: number): string {
-	return `tracked by epic #${String(epic)}, which offers it instead of the standalone half`
+	return `tracked by epic ${session_cite.issue(epic)}, which offers it instead of the standalone half`
 }
 
 // `--exclude` drops an issue from every bucket, so an excluded one lands here. Named for what it is,
@@ -55,8 +54,8 @@ interface ScopeContext {
 	repo: string
 	exclude: ReadonlyArray<number>
 	// Which **opted-in** epic is withholding which issue — `epic_index.withheld_children`'s own answer,
-	// the one the pool decided membership from, so the sentence and the decision cannot disagree
-	// (joshuafolkken/kit#1668). A row in here is one an epic is genuinely offering instead.
+	// the one the pool decided membership from, so the sentence and the decision cannot disagree.
+	// A row in here is one an epic is genuinely offering instead.
 	tracked: ReadonlyMap<number, number>
 }