@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/backlog/backlog-next-shared.ts

@@ -0,0 +1,73 @@
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { z } from 'zod'
+import { backlog_next } from './backlog-next'
+
+// One `josh backlog:next` answer shared by every reader that asks it within a minute
+// (joshuafolkken/kit#4550).
+//
+// **The drive's assignment and the arrival probe each ask every minute, and since a lane waiting on its
+// merge frees its slot (joshuafolkken/kit#4483) a free slot is the usual state** — so both read the
+// whole pool from GitHub every minute, for the same answer.
+//
+// **The key carries the newest event on the run's stream**, so a launch, a merge or a park — anything
+// that can change what may start — is never answered from before it: the first ask after it reads
+// again. Only an answer that read is kept; a failure or a `retry` is asked again by the next reader.
+
+const SUCCESS_EXIT_CODE = 0
+
+const NEXT_CACHE: CacheSlot = { prefix: 'josh-backlog-next-', ttl_ms: 60_000 }
+
+const result_schema = z.object({
+	code: z.number(),
+	out: z.string(),
+	err: z.string().exactOptional(),
+})
+
+// The key a shared plan read is kept under: what was asked, and the newest event on the run's stream.
+// `run:board`'s plan read keys by it too (joshuafolkken/kit#4558).
+async function stream_key(scope: unknown): Promise<string> {
+	const target = await run_event_stream_emit.stream_target()
+	const last = target === undefined ? undefined : run_event_stream.read_last(target)
+
+	return JSON.stringify({ argv: scope, last })
+}
+
+function is_kept(result: JoshResult): boolean {
+	if (result.code !== SUCCESS_EXIT_CODE) return false
+
+	return !result.out.split('\n').includes(backlog_next.VERDICT_TOKENS.retry)
+}
+
+// A kept answer replays its explanation where the live one would have streamed it.
+function replay(result: JoshResult, should_forward_stderr: boolean): JoshResult {
+	if (should_forward_stderr && result.err !== undefined && result.err !== '') {
+		console.error(result.err)
+	}
+
+	return result
+}
+
+async function read(
+	argv: ReadonlyArray<string>,
+	should_forward_stderr = false,
+	timeout_ms?: number,
+): Promise<JoshResult> {
+	const key = await stream_key(argv)
+	const now_ms = Date.now()
+	const kept = shared_cache.read(NEXT_CACHE, key, result_schema, now_ms)
+
+	if (kept !== undefined) return replay(kept, should_forward_stderr)
+
+	const result = await josh_command.josh_run(argv, should_forward_stderr, timeout_ms)
+
+	if (is_kept(result)) shared_cache.write(NEXT_CACHE, key, result, now_ms)
+
+	return result
+}
+
+const backlog_next_shared = { NEXT_CACHE, read, stream_key }
+
+export { backlog_next_shared }

package/scripts/backlog/backlog-next.ts

@@ -1,4 +1,3 @@
-import { fileURLToPath } from 'node:url'
 import { auto_ok_cli, type OptedInRead, type TrackingRead } from '#scripts/auto-ok/auto-ok-cli'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
@@ -13,11 +12,16 @@ import { epic_solo_stale } from '#scripts/epic/epic-solo-stale'
 import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
+import { issue_not_before_label } from '#scripts/issue/issue-not-before-label'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_state } from '#scripts/lane/lane-state'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
 import { backlog_overlap } from './backlog-overlap'
 import { backlog_pool } from './backlog-pool'
 import { backlog_rank, type GateScope } from './backlog-rank'
+import { backlog_wait_cause } from './backlog-wait-cause'
 
 // `josh backlog:next` — what the whole opted-in backlog may run next.
 //
@@ -30,7 +34,6 @@ import { backlog_rank, type GateScope } from './backlog-rank'
 // `auto-ok:next`'s own listing and runnability rules, and the verdict comes from
 // `epic_report.decide_verdict` so it cannot drift from what `epic:next` means by the same word.
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 
@@ -130,6 +133,31 @@ function warn_gaps(context: PoolContext, has_answer: boolean): void {
 	warn_epic_gap(context)
 }
 
+// Why a row on the time side is not offered yet, when the reason is a declared start time or sample
+// condition — the waits a reader cannot see from the labels or the blockers. A sample condition names
+// its pull request as `#N`, linkified like the explanation.
+function warn_not_before(context: PoolContext): void {
+	for (const issue of context.opted_in.issues) {
+		const reason = issue_not_before.waiting_reason(issue.body)
+
+		if (reason === undefined) continue
+
+		const cited = session_cite.issue(issue.number, undefined, context.repo)
+
+		console.error(`${cited} ${issue_citation.linkify(reason, context.repo)}`)
+	}
+}
+
+// Which waiting issues hold the backlog on a dependency chain or a start condition, read back by
+// `backlog:offer` so a lane held by them is told apart in `lane:stats` (joshuafolkken/kit#4513).
+function warn_wait_causes(result: EpicNextResult, context: PoolContext): void {
+	const causes = backlog_wait_cause.classify(result.waiting, context.repo)
+
+	for (const line of backlog_wait_cause.lines_of(causes)) {
+		console.error(issue_citation.linkify(line, context.repo))
+	}
+}
+
 function report(result: EpicNextResult, context: PoolContext): number {
 	warn_gaps(context, result.verdict === 'run')
 	// The explanation names epics and children as `#N` (`tracked by epic #N`); linkified so the text a
@@ -139,8 +167,12 @@ function report(result: EpicNextResult, context: PoolContext): number {
 	const explanation = epic_report.format_result(result, context.repo)
 
 	console.error(issue_citation.linkify(explanation, context.repo))
+	warn_not_before(context)
 
-	for (const token of tokens_of(result, context.repo)) console.info(token)
+	const tokens = tokens_of(result, context.repo)
+
+	if (tokens[0] === VERDICT_TOKENS.wait) warn_wait_causes(result, context)
+	for (const token of tokens) console.info(token)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -297,11 +329,15 @@ function standalone_keys(context: PoolContext): ReadonlySet<string> {
 
 // The running lanes still carry the pickup label, so the opted-in listing holds their bodies too —
 // which is what lets a candidate be held back from a path a running lane already declares.
-// `backlog:plan --waves` reads the same scope, so its first wave is this offer.
-function gate_scope(context: PoolContext): GateScope {
+// `backlog:plan --waves` reads the same scope, so its first wave is this offer. Their lane state
+// records name a paused holder in the wait it causes (joshuafolkken/kit#4270); they are local files.
+async function gate_scope(context: PoolContext): Promise<GateScope> {
+	const { issues } = context.opted_in
+
 	return {
 		standalone: standalone_keys(context),
-		declared: backlog_overlap.declared_of(context.opted_in.issues),
+		declared: backlog_overlap.declared_of(issues),
+		lanes: await lane_state.read_states(issues.map((issue) => String(issue.number))),
 	}
 }
 
@@ -320,7 +356,7 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 
 	if (notice !== undefined) console.error(notice)
 
-	const gated = backlog_rank.gate(result, read, repo, gate_scope(context))
+	const gated = backlog_rank.gate(result, read, repo, await gate_scope(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
 
@@ -393,6 +429,11 @@ async function context_of(
 }
 
 async function answer(opted_in: OptedIn, exclude: ReadonlyArray<number>): Promise<number> {
+	// The scan has every opted-in body and its labels already, so it keeps `not-before` in line with them
+	// and with every other issue the label is on — before any answer, so a drained backlog or a failed
+	// read still takes a passed label off.
+	await issue_not_before_label.sweep(opted_in.issues)
+
 	if (opted_in.issues.length === 0) return report_none()
 
 	const context = await context_of(opted_in, exclude)
@@ -422,13 +463,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await answer(opted_in, options.exclude ?? [])
 }
 
-// `process.exitCode` rather than `process.exit()`, for the reason `auto-ok:next` records: the whole
-// contract is `answers=$(pnpm josh backlog:next)`, and exiting outright can cut the pipe before it
-// has drained.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const backlog_next = {
 	USAGE,
 	REPO_UNREADABLE_MESSAGE,
@@ -441,7 +475,5 @@ const backlog_next = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { backlog_next }
 export type { BacklogVerdict, OptedIn, PoolContext }

package/scripts/backlog/backlog-occupied.ts

@@ -0,0 +1,69 @@
+import type { LaneInfo } from '#scripts/lane/lane-registry'
+import type { LaneRecords } from '#scripts/lane/lane-state'
+
+// The open lanes that hold a place under the lane limit — the one count `lane:limit`, the drive and
+// `run:board` all subtract from it.
+//
+// **A lane with no child working in it holds no place, whatever it waits on** (joshuafolkken/kit#4107).
+// The limit caps the load on the machine, and a lane whose child is gone puts none on it — parked,
+// blocked by another issue, waiting on a decision, or left by an earlier run (joshuafolkken/kit#3967,
+// #4028). Its tree, branch and port seat stay; when its issue is picked up again the drive seats it
+// ahead of a fresh launch, inside the free lanes (`backlog-drive-seats.ts`).
+//
+// **A paused lane holds no place either** (joshuafolkken/kit#4201): a child `lane:pause` suspended
+// puts no load on the machine until it is resumed. **Paused is the lane state record's answer alone**
+// (joshuafolkken/kit#4270) — the `ps` state is not read — so a lane only `lane:pause` paused is
+// uncounted. Its memory stays held, which the free-memory check reads as measured
+// (`backlog-drive-memory.ts`); `lane:prune` still keeps it, since a child is there (`lane-spent.ts`).
+//
+// **A lane with no record is unknown, and keeps its place**, so the count errs toward fewer free
+// lanes. **Whether a child is there at all is not the record's**:
+// a child that parks or dies writes nothing, so only pgrep's own "no match" (`PROCESS_NONE`,
+// `lane_spent.idle_lanes`) clears a lane, and a probe that did not answer keeps it. A stranded lane has
+// no tree to work in and holds no place either. The reads stay local — no issue label is read —
+// because the count gates the network read behind it (`backlog-ready.ts`).
+//
+// **A lane whose detached ship waits on its merge holds no place either** (joshuafolkken/kit#4466). The
+// child ended at the hand-off, and while `josh followup` runs the supervisor only polls CI, CodeRabbit
+// and the merge, so the slot is free for the next launch while every merge check still runs. The wait is
+// unmarked while the followup stage merges and gates again (`run-ship-sync.ts`); a stop there counts
+// the lane again, and past the limit the supervisor waits for a place before it relaunches the child
+// (`run-ship-return.ts`). A named epic's offer discounts the same lanes (`epic-lane-offer.ts`).
+
+// The issues whose lane has no child working in it (`lane_spent.idle_lanes`).
+type IdleRead = (lanes: ReadonlyArray<LaneInfo>) => ReadonlyArray<string>
+// Whether the lane of an issue has a detached ship waiting on its merge (`lane_handoff.merge_wait_reader`).
+type MergeWaitRead = (issue: string) => boolean
+
+function is_never_merge_waiting(): boolean {
+	return false
+}
+
+function occupied_lanes(
+	lanes: ReadonlyArray<LaneInfo>,
+	idle: IdleRead,
+	records: LaneRecords,
+	is_merge_waiting: MergeWaitRead = is_never_merge_waiting,
+): Array<LaneInfo> {
+	const live = lanes.filter((lane) => !lane.is_stranded)
+	const idle_issues = new Set(idle(live))
+
+	return live.filter(
+		(lane) =>
+			!idle_issues.has(lane.issue) &&
+			records.get(lane.issue)?.state !== 'paused' &&
+			!is_merge_waiting(lane.issue),
+	)
+}
+
+/** The issues of the live lanes in `lanes` that have no state record. */
+function unknown_lanes(lanes: ReadonlyArray<LaneInfo>, records: LaneRecords): Array<string> {
+	return lanes
+		.filter((lane) => !lane.is_stranded && !records.has(lane.issue))
+		.map((lane) => lane.issue)
+}
+
+const backlog_occupied = { occupied_lanes, unknown_lanes }
+
+export { backlog_occupied }
+export type { IdleRead, MergeWaitRead }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { json_value } from '#scripts/lib/json-value'
@@ -7,6 +5,7 @@ import { rule_value_cache } from '#scripts/rules/rule-value-cache'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { z } from 'zod'
+import { backlog_next_shared } from './backlog-next-shared'
 import { backlog_offer, type OfferAnswer } from './backlog-offer'
 
 // `josh backlog:offer` — one composite command for a `backlogrun` loop-head event.
@@ -21,7 +20,6 @@ import { backlog_offer, type OfferAnswer } from './backlog-offer'
 // and in the `--json` object; every explanation `backlog:next` and `backlog:budget` print is streamed
 // straight through to stderr.
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const JSON_KEY = 'offer'
@@ -36,7 +34,6 @@ const EXHAUSTED_ANSWER = 'exhausted'
 const NO_RUNNING = 0
 const DRAIN_TEXT = 'backlog drained'
 const should_forward_stderr = true
-const COUNT_PATTERN = /^\d+$/u
 
 const USAGE =
 	'Usage: josh backlog:offer --started <ISO-8601> [--active <ISO-8601>] [--merged <n>] [--running <n>] [--max <n>] [--idle <minutes>] [--retries <n>] [--exclude <n>[,<n>...]]... [--repo <owner/repo>] [--json]'
@@ -65,18 +62,10 @@ function read_values(argv: ReadonlyArray<string>): ParsedValues | undefined {
 	return cli_flags.values_of(argv, OPTIONS)
 }
 
-function to_count(raw: string | undefined): number | undefined {
-	if (raw === undefined || !COUNT_PATTERN.test(raw)) return undefined
-
-	const parsed = Number(raw)
-
-	return Number.isSafeInteger(parsed) ? parsed : undefined
-}
-
 // A count flag that was given but unreadable makes the invocation unreadable rather than defaulted —
 // the contract `backlog:budget` follows for its own counts.
 function count_of(raw: string | undefined): number | undefined {
-	return raw === undefined ? DEFAULT_COUNT : to_count(raw)
+	return raw === undefined ? DEFAULT_COUNT : cli_flags.to_count(raw)
 }
 
 interface OfferCounts {
@@ -159,6 +148,8 @@ function emit(decision: BudgetRead, offer: OfferAnswer, is_json: boolean): numbe
 			verdict,
 			issues,
 			answer: offer.answer,
+			cause: offer.cause,
+			waiting: offer.waiting,
 			retries: offer.retries,
 			reason,
 			is_finish,
@@ -198,9 +189,9 @@ async function mark_drain(verdict: string, answer: string, running: number): Pro
 }
 
 async function decide(values: ParsedValues, counts: OfferCounts): Promise<number> {
-	const next = await josh_command.josh_run(next_argv(values), should_forward_stderr)
+	const next = await backlog_next_shared.read(next_argv(values), should_forward_stderr)
 	const offer = backlog_offer.answer_of(
-		{ code: next.code, tokens: to_tokens(next.out) },
+		{ code: next.code, tokens: to_tokens(next.out), err: next.err },
 		counts.running,
 		counts.retries,
 	)
@@ -239,10 +230,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await decide(values, counts)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const backlog_offer_cli = {
 	JSON_KEY,
 	budget_argv,
@@ -252,7 +239,5 @@ const backlog_offer_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { backlog_offer_cli }
 export type { ParsedValues }

package/scripts/backlog/backlog-offer-exclude.ts

@@ -0,0 +1,15 @@
+const LIST_SEPARATOR = ','
+
+// **A child in flight is never offered**, nor a settled one `backlog:next` still reads OPEN — merged, or
+// withdrawn from this run (joshuafolkken/kit#4365). The drive builds this list from its state and the
+// stall detector from the event stream (joshuafolkken/kit#4349); both go through here. Kept free of the
+// drive's imports so a reader of the stream does not load it.
+function exclude_of(settled: Iterable<string>, in_flight: Iterable<string>): ReadonlyArray<string> {
+	return [...new Set([...settled, ...in_flight])]
+}
+
+function exclude_argv(exclude: ReadonlyArray<string>): ReadonlyArray<string> {
+	return exclude.length === 0 ? [] : ['--exclude', exclude.join(LIST_SEPARATOR)]
+}
+
+export const backlog_offer_exclude = { exclude_argv, exclude_of }

package/scripts/backlog/backlog-offer-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { backlog_offer_cli } from './backlog-offer-cli'
+
+// The `josh backlog:offer` entry, kept apart from `backlog-offer-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await backlog_offer_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/backlog/backlog-offer.ts

@@ -1,6 +1,8 @@
+import { epic_solo } from '#scripts/epic/epic-solo'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import type { BacklogAnswer } from './backlog-budget'
 import { backlog_next } from './backlog-next'
+import { backlog_wait_cause } from './backlog-wait-cause'
 
 // The mechanical half of `josh backlog:offer`: turn what `backlog:next`
 // answered — its stdout tokens and its exit code — into the one word `backlog:budget` is then asked
@@ -21,10 +23,15 @@ const NO_RETRIES = 0
 
 const TOKENS = backlog_next.VERDICT_TOKENS
 
-// `backlog:next`'s captured result: the exit code, and the trimmed stdout as one token per line.
+const BLOCKED_ANSWER = 'blocked'
+const SOLO_CAUSE = 'solo'
+
+// `backlog:next`'s captured result: the exit code, the trimmed stdout as one token per line, and the
+// stderr its explanations went to.
 interface NextRead {
 	code: number
 	tokens: ReadonlyArray<string>
+	err?: string | undefined
 }
 
 interface OfferAnswer {
@@ -32,6 +39,12 @@ interface OfferAnswer {
 	issues: ReadonlyArray<string>
 	// The consecutive-retry count after this ask — reset to zero by any answer that is not `retry`.
 	retries: number
+	// Why a `wait` answer started nothing, where `backlog:next` said: `solo` for the `run:solo` gate,
+	// so `lane:stats` rows that wait apart from every other one (joshuafolkken/kit#4396); `chain`,
+	// `gate` or `chain+gate` for the waits `backlog-wait-cause.ts` names (joshuafolkken/kit#4513).
+	cause?: string
+	// The issues a `chain` / `gate` cause waited on, recorded with the hold.
+	waiting?: ReadonlyArray<number> | undefined
 }
 
 // The verdict words that map to one answer regardless of context. `wait` and `retry` are the two that
@@ -46,7 +59,7 @@ const VERDICT_ANSWERS: Readonly<Record<string, BacklogAnswer>> = {
 // `wait` is `blocked` while this run has children in flight and `exhausted` when it does not — the
 // mapping `backlog:budget` states, decided from the running count alone.
 function wait_answer(running: number): BacklogAnswer {
-	return running > 0 ? 'blocked' : 'exhausted'
+	return running > 0 ? BLOCKED_ANSWER : 'exhausted'
 }
 
 // An unrecognized token is read as `unreadable` rather than guessed at: an answer the loop cannot
@@ -73,6 +86,24 @@ function is_numbers(tokens: ReadonlyArray<string>): boolean {
 	return tokens.length > 0 && tokens.every((token) => issue_number_shape.is_issue_number(token))
 }
 
+// What `backlog:next`'s stderr says a blocked wait was for: the `run:solo` gate's notice first, then
+// the waiting issues' causes, or nothing when it names neither.
+function blocked_cause(error: string): Pick<OfferAnswer, 'cause' | 'waiting'> {
+	if (epic_solo.is_solo_wait(error)) return { cause: SOLO_CAUSE }
+
+	const causes = backlog_wait_cause.parse(error)
+	const tag = backlog_wait_cause.tag_of(causes)
+
+	return tag === undefined ? {} : { cause: tag, waiting: backlog_wait_cause.numbers_of(causes) }
+}
+
+// A `wait` answer marked with its cause. An `exhausted` wait is marked too: the idle watch it opens
+// holds a free lane as long as a `blocked` one, and a hold with nothing in flight here (a start date,
+// or a blocker another session runs) is still that wait, not an empty backlog.
+function with_cause(offer: OfferAnswer, token: string, error: string): OfferAnswer {
+	return token === TOKENS.wait ? { ...offer, ...blocked_cause(error) } : offer
+}
+
 // **Read the exit code before the tokens.** Exit 1 is "the listing could not be read", which is never
 // an empty backlog — reading it as `none` would report an emptiness that was never seen, so it maps to
 // `unreadable`, and a stray stdout line on that path cannot be mistaken for an issue number.
@@ -85,7 +116,9 @@ function answer_of(read: NextRead, running: number, retries: number): OfferAnswe
 		return { answer: 'candidates', issues: read.tokens, retries: NO_RETRIES }
 	}
 
-	return from_verdict(read.tokens[0] ?? '', running, retries)
+	const token = read.tokens[0] ?? ''
+
+	return with_cause(from_verdict(token, running, retries), token, read.err ?? '')
 }
 
 const backlog_offer = { RETRY_LIMIT, answer_of, verdict_answer, wait_answer }

package/scripts/backlog/backlog-overlap.ts

@@ -2,6 +2,7 @@ import type { BusyRead } from '#scripts/epic/epic-busy'
 import type { EpicChild } from '#scripts/epic/epic-graph'
 import type { SoloSelection } from '#scripts/epic/epic-solo'
 import { session_cite } from '#scripts/issue/session-cite'
+import { lane_state, type LaneRecords } from '#scripts/lane/lane-state'
 
 // Which candidates may not run side by side because their bodies declare overlapping paths.
 // joshuafolkken/kit#3221 held back only a path both bodies named beside a move, split, rename or
@@ -76,6 +77,8 @@ function overlaps(left: string, right: string): boolean {
 interface SeparateContext {
 	read: BusyRead
 	repo: string
+	// The holders' lane state records, so a clash names a paused holder (joshuafolkken/kit#4270).
+	lanes?: LaneRecords | undefined
 }
 
 // The path each of `holders` declares, mapped to the issue that holds it.
@@ -130,15 +133,29 @@ function running_clash(child: EpicChild, declared: Declared, holding: Holding):
 	return clash_of(claims, paths_of(child, declared, holding.repo))
 }
 
-function clash_note(child: EpicChild, clash: Clash): string {
+// Whether `waiting` declares a path `holder` declares — the overlap `separate` withholds it on.
+function holds(declared: Declared, holder: number, waiting: number): boolean {
+	return clash_of(claims_of(declared, [holder]), declared.get(waiting) ?? new Set()) !== undefined
+}
+
+// ` — paused since 01:28 by lane:pause` for a holder whose lane is paused: it holds the path while
+// nothing moves, so the wait lasts until someone resumes it.
+function paused_tail(clash: Clash, lanes: LaneRecords): string {
+	const note = lane_state.paused_note(lanes.get(String(clash.holder)))
+
+	return note === undefined ? '' : ` — ${note}`
+}
+
+function clash_note(child: EpicChild, clash: Clash, lanes: LaneRecords): string {
 	const waiting = session_cite.issue(child.number, undefined, child.repo)
 	const holder = session_cite.issue(clash.holder, undefined, child.repo)
 
-	return `${waiting} waits: its \`${clash.path}\` overlaps \`${clash.claimed}\`, which ${holder} declares.`
+	return `${waiting} waits: its \`${clash.path}\` overlaps \`${clash.claimed}\`, which ${holder} declares${paused_tail(clash, lanes)}.`
 }
 
 interface Walk {
 	claims: Map<string, number>
+	lanes: LaneRecords
 	offered: Array<EpicChild>
 	withheld: Array<EpicChild>
 	notes: Array<string>
@@ -155,7 +172,7 @@ function visit(walk: Walk, child: EpicChild, paths: ReadonlySet<string>): void {
 	}
 
 	walk.withheld.push(child)
-	walk.notes.push(clash_note(child, clash))
+	walk.notes.push(clash_note(child, clash, walk.lanes))
 }
 
 function merged_notice(
@@ -176,6 +193,7 @@ function separate(
 ): SoloSelection {
 	const walk: Walk = {
 		claims: running_claims(declared, context.read),
+		lanes: context.lanes ?? new Map(),
 		offered: [],
 		withheld: [],
 		notes: [],
@@ -189,7 +207,7 @@ function separate(
 	return { offered: walk.offered, withheld, ...(notice !== undefined && { notice }) }
 }
 
-const backlog_overlap = { declared_of, declared_paths, running_clash, separate }
+const backlog_overlap = { declared_of, declared_paths, holds, running_clash, separate }
 
 export { backlog_overlap }
 export type { Clash, Declared }

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

@@ -4,6 +4,7 @@ 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 { issue_sample_gate } from '#scripts/issue/issue-sample-gate'
 import { backlog_next, type OptedIn } from './backlog-next'
 import type { PlanContext } from './backlog-plan'
 import type { GateScope } from './backlog-rank'
@@ -60,7 +61,7 @@ async function classify(
 		repo: context.repo,
 		exclude,
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
-		scope: backlog_next.gate_scope(context),
+		scope: await backlog_next.gate_scope(context),
 	}
 }
 
@@ -74,7 +75,10 @@ async function fetch_open(): Promise<OpenListing | undefined> {
 
 	const read = read_json_listing(json, open_issue_schema)
 
-	return read.kind === 'read' ? { rows: read.rows, is_capped } : undefined
+	if (read.kind !== 'read') return undefined
+	await issue_sample_gate.prime(read.rows.map((row) => row.body))
+
+	return { rows: read.rows, is_capped }
 }
 
 // A cut listing cannot say an issue is closed, only that it was not read — so the blocker filter is

package/scripts/backlog/backlog-plan.ts

@@ -4,7 +4,12 @@ import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo } from '#scripts/epic/epic-solo'
 import { epic_triage } from '#scripts/epic/epic-triage'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import {
+	has_label_name,
+	IN_PROGRESS_LABEL,
+	PARKED_LABELS,
+	RUN_SOLO_LABEL,
+} from '#scripts/issue/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
 // The plan a person reads before a `backlogrun` starts.
@@ -30,8 +35,9 @@ const ONLY_NAMED_HEADING =
 const READY_HEADING =
 	'Ready now — each takes a free lane in its repository, so these may run in parallel:'
 const WAITING_HEADING = 'Waiting — each names what it is waiting on:'
-const HUMAN_HEADING =
-	'Waiting on a person (`needs-decision`) — resolve these before the run starts:'
+// Every park label (`PARKED_LABELS`) puts a child here, so the heading names none and each row names
+// its own: a `run:stalled` row read as `needs-decision` sends a person to decide a mechanical failure.
+const HUMAN_HEADING = 'Waiting on a person — resolve these before the run starts:'
 const SCOPE_HEADING = 'Out of scope — open, but the backlog will not run these:'
 // `epic_report`'s own words for the same condition, so the plan and the run name it identically.
 const UNUSABLE_HEADING = 'The dependency graph is unusable, so there is no plan:'
@@ -150,6 +156,14 @@ function child_lines(
 	return children.map((child) => row_of(child, context, note(child)))
 }
 
+// The park labels a child carries, so its row says what the person is asked for.
+function park_note(child: EpicChild): string {
+	return [...PARKED_LABELS]
+		.filter((label) => has_label_name(child.labels, label))
+		.map((label) => `\`${label}\``)
+		.join(', ')
+}
+
 // A section whose rows say nothing beyond naming the issue: being under the heading is the whole
 // statement.
 function no_note(): string {
@@ -239,7 +253,7 @@ function format_plan(
 		'',
 		section(WAITING_HEADING, waiting_lines(result.waiting, context)),
 		'',
-		section(HUMAN_HEADING, child_lines(result.blocked_on_people, context, no_note)),
+		section(HUMAN_HEADING, child_lines(result.blocked_on_people, context, park_note)),
 		'',
 		section(SCOPE_HEADING, scope_lines(out_of_scope, context.repo)),
 	].join('\n')