@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/backlog/backlog-next.ts

@@ -1,8 +1,9 @@
-import { fileURLToPath } from 'node:url'
-import { auto_ok_cli, type OptedInRead, type TrackingRead } from '#scripts/auto-ok/auto-ok-cli'
+import { auto_ok_author } from '#scripts/auto-ok/auto-ok-author'
+import { auto_ok_cli, type OptedInRead } 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'
 import { epic_busy } from '#scripts/epic/epic-busy'
+import type { Classification } from '#scripts/epic/epic-classify'
 import type { EpicChild } from '#scripts/epic/epic-graph'
 import { epic_index } from '#scripts/epic/epic-index'
 import { epic_next } from '#scripts/epic/epic-next'
@@ -13,11 +14,15 @@ 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 { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
-import { backlog_overlap } from './backlog-overlap'
+import { backlog_gate_scope, type OptedIn, type PoolContext } from './backlog-gate-scope'
 import { backlog_pool } from './backlog-pool'
-import { backlog_rank, type GateScope } from './backlog-rank'
+import { backlog_rank } 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 +35,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
 
@@ -81,17 +85,6 @@ const VERDICT_TOKENS: Readonly<Record<BacklogVerdict, string>> = {
 	wait: 'wait',
 }
 
-type OptedIn = Extract<OptedInRead, { kind: 'read' }>
-type Tracking = Extract<TrackingRead, { kind: 'read' }>
-
-// Everything the answer is assembled from, read once and passed down rather than re-fetched.
-interface PoolContext {
-	opted_in: OptedIn
-	tracking: Tracking
-	repo: string
-	exclude: ReadonlyArray<number>
-}
-
 // One token per line on standard output: the runnable issue numbers of **this** repository, in the
 // order they may be started, or the single verdict word when there is nothing to offer here. Every
 // explanation is on standard error, so `answers=$(pnpm josh backlog:next)` captures something a loop
@@ -130,6 +123,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 +157,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)
+
+	const tokens = tokens_of(result, context.repo)
 
-	for (const token of tokens_of(result, context.repo)) console.info(token)
+	if (tokens[0] === VERDICT_TOKENS.wait) warn_wait_causes(result, context)
+	for (const token of tokens) console.info(token)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -161,14 +183,27 @@ function running_of(
 // The two halves as one result. The epic half is already classified by `epic:next`; the standalone
 // half is classified here; the verdict is decided from the merge, so a backlog with a runnable epic
 // child and nothing else says `run` exactly as one with a runnable standalone issue does.
-function combine(views: ReadonlyArray<EpicView>, context: PoolContext): EpicNextResult {
-	const graphs = views.map((view) => view.snapshot.children)
-	const standalone = backlog_pool.standalone_rows(context.opted_in.issues)
-	const from_epics = backlog_pool.drop_excluded(
-		backlog_pool.epic_classification(views),
+// `untrusted` is the epic children an author without write access filed (joshuafolkken/kit#4633).
+function epic_half(
+	views: ReadonlyArray<EpicView>,
+	context: PoolContext,
+	untrusted: ReadonlySet<string>,
+): Classification {
+	return backlog_pool.drop_excluded(
+		backlog_pool.epic_classification(views, untrusted),
 		context.exclude,
 		context.repo,
 	)
+}
+
+function combine(
+	views: ReadonlyArray<EpicView>,
+	context: PoolContext,
+	untrusted: ReadonlySet<string>,
+): EpicNextResult {
+	const graphs = views.map((view) => view.snapshot.children)
+	const standalone = backlog_pool.standalone_rows(context.opted_in.issues)
+	const from_epics = epic_half(views, context, untrusted)
 	const from_standalone = backlog_pool.classify_standalone(standalone, {
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
 		exclude: context.exclude,
@@ -213,10 +248,17 @@ function settled_views(
 //
 // The running set covers the standalone rows as well as every read graph, so an epic child waiting on
 // an opted-in standalone issue waits rather than stops.
-function views_from(reads: ReadonlyArray<EpicRead>, context: PoolContext): ReadonlyArray<EpicView> {
+function views_from(
+	reads: ReadonlyArray<EpicRead>,
+	context: PoolContext,
+	untrusted: ReadonlySet<string>,
+): ReadonlyArray<EpicView> {
 	if (reads.length === 0) return []
 
-	const graphs = reads.map((read) => read.snapshot.children)
+	const graphs = backlog_pool.trusted_graphs(
+		reads.map((read) => read.snapshot.children),
+		untrusted,
+	)
 
 	return settled_views(
 		reads,
@@ -245,11 +287,15 @@ async function resolve(context: PoolContext): Promise<EpicNextResult | undefined
 		return undefined
 	}
 
+	const untrusted = await auto_ok_author.untrusted_child_keys(
+		reads.flatMap((read) => read.snapshot.children),
+		context.repo,
+	)
 	// The defect priority and the ranking keys are applied here rather than when printing, so
 	// `backlog:plan` shows the order the run takes. The
 	// ranking goes last: its sort is stable, so the defect order survives as its final key.
 	const ordered = await backlog_defect_priority.prioritize(
-		combine(views_from(reads, context), context),
+		combine(views_from(reads, context, untrusted), context, untrusted),
 		context.repo,
 	)
 
@@ -286,25 +332,6 @@ function report_retry(context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
-// The rows the offer's cap bounds — the standalone half.
-function standalone_keys(context: PoolContext): ReadonlySet<string> {
-	return backlog_pool.standalone_keys(context.opted_in.issues, {
-		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
-		exclude: context.exclude,
-		repo: context.repo,
-	})
-}
-
-// 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 {
-	return {
-		standalone: standalone_keys(context),
-		declared: backlog_overlap.declared_of(context.opted_in.issues),
-	}
-}
-
 // The `run:solo` gate is applied here rather than in `resolve`, because `backlog:plan` shares
 // `resolve` and a plan made before the run lists everything. The holders are
 // read only on a `run` answer — the one answer the gate can change. The cap follows the gate
@@ -320,7 +347,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 backlog_gate_scope.gate_scope(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
 
@@ -393,6 +420,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 +454,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,
@@ -436,12 +461,9 @@ const backlog_next = {
 	READ_FAILURES,
 	VERDICT_TOKENS,
 	resolve,
-	gate_scope,
 	context_of,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { backlog_next }
-export type { BacklogVerdict, OptedIn, PoolContext }
+export type { BacklogVerdict }

package/scripts/backlog/backlog-occupied.ts

@@ -1,56 +1,69 @@
 import type { LaneInfo } from '#scripts/lane/lane-registry'
-import type { RunEvent } from '#scripts/run/event/run-event-stream'
-import { run_invocation } from '#scripts/run/run-invocation'
-import { backlog_drive_restore } from './backlog-drive-restore'
+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 nobody will come back to holds no place.** A `--only` run works its named list and never
-// touches another lane, so a lane an earlier run left with no child in it would fill the limit for the
-// whole run, and the run's own issues would wait on it for good (joshuafolkken/kit#3967). Under a `--only`
-// run such a lane is not counted; its tree and branch stay, for the next run that names its issue.
+// **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`).
 //
-// **Everything else keeps its place, so the count errs toward fewer free lanes.** A run that drains
-// the pool may offer any open lane's issue again, a lane whose child still works is busy whoever owns
-// it, and with no run there is nobody to judge ownership for. The read stays local — no issue label is
-// read — because the count gates the network read behind it (`backlog-ready.ts`).
-
-interface OccupiedRead {
-	// The live run's invocation, `undefined` when no run is live here.
-	invocation: string | undefined
-	// The live run's own events, for the issues it launched or settled; `undefined` where its scope
-	// could not be told, which leaves every open lane counted.
-	events: ReadonlyArray<RunEvent> | undefined
-	// The issues whose lane has no child working in it; read only for a `--only` run.
-	idle: (lanes: ReadonlyArray<LaneInfo>) => ReadonlyArray<string>
-}
-
-// The issues a `--only` run owns — those it names and those it launched or settled — or `undefined`
-// where there is no such run, or its events could not be scoped to it.
-function owned_issues(read: OccupiedRead): ReadonlySet<string> | undefined {
-	const { invocation, events } = read
-	const is_only = invocation !== undefined && run_invocation.has_only(invocation)
-
-	if (!is_only || events === undefined) return undefined
+// **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 more than one lane past the limit the supervisor waits for a place before it
+// relaunches the child (`run-ship-place.ts`). A named epic's offer discounts the same lanes (`epic-lane-offer.ts`).
 
-	const named = (run_invocation.issue_numbers(invocation) ?? []).map(String)
+// 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
 
-	return new Set([...named, ...backlog_drive_restore.mentioned_issues(events)])
+function is_never_merge_waiting(): boolean {
+	return false
 }
 
-function occupied_lanes(lanes: ReadonlyArray<LaneInfo>, read: OccupiedRead): Array<LaneInfo> {
+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 owned = owned_issues(read)
-
-	if (owned === undefined) return live
+	const idle_issues = new Set(idle(live))
 
-	const idle = new Set(read.idle(live))
+	return live.filter(
+		(lane) =>
+			!idle_issues.has(lane.issue) &&
+			records.get(lane.issue)?.state !== 'paused' &&
+			!is_merge_waiting(lane.issue),
+	)
+}
 
-	return live.filter((lane) => owned.has(lane.issue) || !idle.has(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 }
+const backlog_occupied = { occupied_lanes, unknown_lanes }
 
 export { backlog_occupied }
-export type { OccupiedRead }
+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 }