@joshuafolkken/kit 1.953.0 → 1.972.0

package/scripts/backlog/backlog-arrival.ts

@@ -1,3 +1,4 @@
+import { epic_triage } from '#scripts/epic/epic-triage'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { run_headless } from '#scripts/run/run-headless'
 import { backlog_next } from './backlog-next'
@@ -51,6 +52,10 @@ function answered_issues(result: JoshResult | undefined): ReadonlyArray<string>
 		throw new Error('`backlog:next` did not answer')
 	}
 
+	// `triage` names no number, yet the parent has work — so it is read as one token, which a reading
+	// sees as an arrival (joshuafolkken/kit#2779).
+	if (backlog_stalled.needs_triage(result.out)) return [epic_triage.TRIAGE_VERDICT]
+
 	return backlog_stalled.ready_tokens(result.out)
 }
 
@@ -76,9 +81,14 @@ function arrivals(baseline: ReadonlySet<string>, reading: ReadyReading): Readonl
 
 // The baseline is the whole runnable pool, free lane or not: an issue that was waiting for a lane is not
 // new when one frees, and the child's merge that freed it already wakes the parent.
+//
+// A baseline read during a `triage` answer names none of the issues it withheld, so every one of them
+// would arrive once they were judged — the whole-pool wake. It is read as a baseline that did not answer.
 async function read_baseline(ports: ReadyPorts): Promise<ReadonlySet<string> | undefined> {
 	try {
-		return new Set(await ports.ready_issues())
+		const issues = await ports.ready_issues()
+
+		return issues.includes(epic_triage.TRIAGE_VERDICT) ? undefined : new Set(issues)
 	} catch {
 		return undefined
 	}

package/scripts/backlog/backlog-budget.ts

@@ -47,20 +47,22 @@ const IDLE_POLL_MINUTES = 5
 const RUN_VERDICT = 'run'
 const WATCH_VERDICT = 'watch'
 const STOP_VERDICT = 'stop'
+const TRIAGE_VERDICT = 'triage'
 
 // `run` — start what `backlog:next` offered. `watch` — sleep the polling interval and ask again,
 // except while something of the run's own is in flight, where the wake is the progress watcher's exit
 // and the interval is only a floor (`backlogrun.md` → "The wake exists only while something is in
 // flight").
-// `stop` — report and finish. There is no fourth: an answer the loop cannot act on is a verdict
-// nobody can write a loop against.
-type BudgetVerdict = typeof RUN_VERDICT | typeof WATCH_VERDICT | typeof STOP_VERDICT
+// `stop` — report and finish. `triage` — judge the untriaged issues `backlog:next` named, then ask
+// again (joshuafolkken/kit#2779); it is the parent's to act on, so `backlog:drive` hands it back.
+type BudgetVerdict =
+	typeof RUN_VERDICT | typeof WATCH_VERDICT | typeof STOP_VERDICT | typeof TRIAGE_VERDICT
 
 // What `backlog:next` answered, in the words this decision needs. The mapping is mechanical and is
 // written once, in `backlogrun-steps.md` → "The loop": numbers are `candidates`, `wait` is `blocked` while
 // this run has children in flight and `exhausted` when it does not, `none` is `exhausted`, `stop` is
-// `parked`, and `error` or a failed listing is `unreadable`.
-const ANSWERS = ['blocked', 'candidates', 'exhausted', 'parked', 'unreadable'] as const
+// `parked`, `triage` is `untriaged`, and `error` or a failed listing is `unreadable`.
+const ANSWERS = ['blocked', 'candidates', 'exhausted', 'parked', 'unreadable', 'untriaged'] as const
 
 type BacklogAnswer = (typeof ANSWERS)[number]
 
@@ -102,6 +104,9 @@ const UNREADABLE_REASON =
 const BLOCKED_REASON =
 	'Everything opted in is blocked or already running, so waiting can still change the answer. Poll again at the polling interval.'
 
+const TRIAGE_REASON =
+	'An opted-in candidate carries neither `run:solo` nor `run:lane`, so nothing starts until it is judged. Read each issue named above, record its order and one of the two labels with a comment, then ask again.'
+
 const NO_IDLE_WATCH_REASON =
 	'The backlog is empty and the idle watch was turned off with `--idle 0`, so the run finishes here.'
 
@@ -237,6 +242,18 @@ function is_finish(input: BudgetInput): boolean {
 	return stop_reason(input) === undefined && max_decision(input) === undefined
 }
 
+// The answers whose decision no count changes, once the bounds above have been applied.
+const FIXED_DECISIONS: Readonly<Partial<Record<BacklogAnswer, BudgetDecision>>> = {
+	blocked: { verdict: WATCH_VERDICT, reason: BLOCKED_REASON },
+	untriaged: { verdict: TRIAGE_VERDICT, reason: TRIAGE_REASON },
+}
+
+function answer_decision(input: BudgetInput): BudgetDecision {
+	if (input.answer === 'candidates') return { verdict: RUN_VERDICT, reason: run_reason(input) }
+
+	return FIXED_DECISIONS[input.answer] ?? idle_decision(input)
+}
+
 function decide(input: BudgetInput): BudgetDecision {
 	const reason = stop_reason(input)
 
@@ -245,10 +262,8 @@ function decide(input: BudgetInput): BudgetDecision {
 	const capped = max_decision(input)
 
 	if (capped !== undefined) return capped
-	if (input.answer === 'candidates') return { verdict: RUN_VERDICT, reason: run_reason(input) }
-	if (input.answer === 'blocked') return { verdict: WATCH_VERDICT, reason: BLOCKED_REASON }
 
-	return idle_decision(input)
+	return answer_decision(input)
 }
 
 const backlog_budget = {
@@ -263,6 +278,8 @@ const backlog_budget = {
 	PARKED_REASON,
 	RUN_VERDICT,
 	STOP_VERDICT,
+	TRIAGE_REASON,
+	TRIAGE_VERDICT,
 	UNREADABLE_REASON,
 	WATCH_VERDICT,
 	WHOLE_RUN_BUDGET_HOURS,

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

@@ -3,6 +3,7 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
 import { lane_launch_cli } from '#scripts/lane/lane-launch-cli'
@@ -24,6 +25,7 @@ import { backlog_drive_named_offer } from './backlog-drive-named-offer'
 import { backlog_drive_offer_argv } from './backlog-drive-offer-argv'
 import { backlog_drive_owner } from './backlog-drive-owner'
 import { backlog_drive_restore } from './backlog-drive-restore'
+import { backlog_drive_retrospective } from './backlog-drive-retrospective'
 import { backlog_offer_cli } from './backlog-offer-cli'
 
 // `josh backlog:drive` — the backlogrun parent's loop as one resident wait (joshuafolkken/kit#2499).
@@ -193,7 +195,7 @@ async function read_offer(
 
 	return offer === undefined
 		? undefined
-		: { ...offer, is_retrospective_done: carry.retrospective === true }
+		: { ...offer, is_retrospective_owed: backlog_drive_retrospective.is_owed(carry) }
 }
 
 // A non-zero `run:merge` prints its token first only for a hand-off (`busy`, `stop`, `retry`); any
@@ -357,6 +359,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {
+	// Load `.env` on the real command path only, so `JOSH_RETROSPECTIVE` set there reaches the offer read.
+	hook_decision.load_environment_file()
 	process.exitCode = await run(argv)
 }
 

package/scripts/backlog/backlog-drive-retrospective.ts

@@ -0,0 +1,20 @@
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { find_package_directory } from '#scripts/josh/josh-logic'
+import type { RunCarry } from '#scripts/run/run-carry'
+import { run_retrospective } from '#scripts/run/run-retrospective'
+
+// Whether a drain owes the retrospective, read through the owed rule `run:step` reads, so a drain it
+// owes nothing at keeps the idle watch rather than waking a session with nothing to run
+// (joshuafolkken/kit#2750). The drive is the parent's loop, never a lane child's.
+function is_owed(carry: RunCarry): boolean {
+	const root = find_package_directory(process.cwd())
+
+	return run_retrospective.is_owed({
+		is_retrospective_enabled: run_retrospective.is_enabled(),
+		is_lane_child: false,
+		is_retrospective_done: carry.retrospective === true,
+		is_consumer: doctor_consumer.is_kit_consumer(root),
+	})
+}
+
+export const backlog_drive_retrospective = { is_owed }

package/scripts/backlog/backlog-drive.ts

@@ -45,7 +45,9 @@ interface OfferRead {
 	retries: number
 	answer?: string | undefined
 	reason?: string | undefined
-	is_retrospective_done?: boolean
+	// Whether a drain here owes the retrospective: the opt-in switch is on and it has not run yet. Absent
+	// reads as not owed, so a drain with the switch off keeps the idle watch (joshuafolkken/kit#2750).
+	is_retrospective_owed?: boolean
 	is_finish?: boolean | undefined
 }
 
@@ -106,7 +108,9 @@ function ended(reason: string, state: DriveState, token?: string, issue?: string
 
 function is_drain(read: OfferRead, state: DriveState): boolean {
 	return (
-		read.verdict === WATCH_VERDICT && state.in_flight.length === 0 && !read.is_retrospective_done
+		read.verdict === WATCH_VERDICT &&
+		state.in_flight.length === 0 &&
+		read.is_retrospective_owed === true
 	)
 }
 
@@ -115,7 +119,7 @@ function needs_retrospective(read: OfferRead, state: DriveState): boolean {
 		read.verdict === STOP_VERDICT &&
 		read.answer === 'exhausted' &&
 		state.in_flight.length === 0 &&
-		!read.is_retrospective_done
+		read.is_retrospective_owed === true
 	)
 }
 

package/scripts/backlog/backlog-next.ts

@@ -2,11 +2,15 @@ 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'
+import { epic_busy } from '#scripts/epic/epic-busy'
+import type { EpicChild } from '#scripts/epic/epic-graph'
 import { epic_index } from '#scripts/epic/epic-index'
 import { epic_next } from '#scripts/epic/epic-next'
 import { epic_next_read, type EpicRead } from '#scripts/epic/epic-next-read'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_report, type EpicNextResult, type EpicVerdict } from '#scripts/epic/epic-report'
+import { epic_solo } from '#scripts/epic/epic-solo'
+import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
@@ -61,7 +65,10 @@ const RETRY_MESSAGE =
 // no failure path that could emit it, so widening the shared union would give every consumer of it a
 // member none of them can produce — and `VERDICT_LINES` a line nothing ever prints. The token is a
 // backlog-level answer about the transport, not a reading of one epic's graph.
-type BacklogVerdict = EpicVerdict | 'retry'
+//
+// `triage` is `epic:next`'s word as well as this command's (joshuafolkken/kit#2779), but it is decided
+// after the graph is read rather than from it, so it stays `epic_triage`'s type too.
+type BacklogVerdict = EpicVerdict | 'retry' | TriageVerdict
 
 const VERDICT_TOKENS: Readonly<Record<BacklogVerdict, string>> = {
 	complete: auto_ok_cli.NONE_TOKEN,
@@ -69,6 +76,7 @@ const VERDICT_TOKENS: Readonly<Record<BacklogVerdict, string>> = {
 	retry: 'retry',
 	run: 'run',
 	stop: 'stop',
+	triage: epic_triage.TRIAGE_VERDICT,
 	wait: 'wait',
 }
 
@@ -266,13 +274,47 @@ function report_retry(context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
+// 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 (joshuafolkken/kit#2776). The holders are
+// read only on a `run` answer — the one answer the gate can change.
+async function gate_solo(result: EpicNextResult, repo: string): Promise<EpicNextResult> {
+	if (result.verdict !== 'run') return result
+
+	const gated = epic_solo.gate(result, await epic_busy.read_repository(repo), repo)
+
+	if (gated.notice !== undefined) console.error(gated.notice)
+
+	return gated.result
+}
+
+// An untriaged candidate withholds every candidate (joshuafolkken/kit#2779). Checked before the
+// `run:solo` gate, which cannot be applied to an issue whose label is not recorded yet; the numbers go
+// to standard error, the one token to standard output.
+function report_triage(context: PoolContext, untriaged: ReadonlyArray<EpicChild>): number {
+	warn_epic_gap(context)
+	console.error(epic_triage.message(untriaged, context.repo))
+	console.info(VERDICT_TOKENS.triage)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function untriaged_of(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
+	if (result.verdict !== 'run') return []
+
+	return epic_triage.untriaged(epic_report.candidates_for_repo(result, repo))
+}
+
 async function answer_pool(context: PoolContext): Promise<number> {
 	const result = await resolve(context)
 
 	if (result === undefined) return FAILURE_EXIT_CODE
 	if (is_transport_failure(result)) return report_retry(context)
 
-	return report(result, context)
+	const untriaged = untriaged_of(result, context.repo)
+
+	if (untriaged.length > 0) return report_triage(context, untriaged)
+
+	return report(await gate_solo(result, context.repo), context)
 }
 
 // A backlog nobody has opted into answers `none` before either listing below is asked for.
@@ -362,6 +404,7 @@ const backlog_next = {
 	resolve,
 	is_transport_failure,
 	report_retry,
+	report_triage,
 	context_of,
 	answer_pool,
 	report_none,

package/scripts/backlog/backlog-offer.ts

@@ -40,6 +40,7 @@ const VERDICT_ANSWERS: Readonly<Record<string, BacklogAnswer>> = {
 	[TOKENS.complete]: 'exhausted',
 	[TOKENS.error]: 'unreadable',
 	[TOKENS.stop]: 'parked',
+	[TOKENS.triage]: 'untriaged',
 }
 
 // `wait` is `blocked` while this run has children in flight and `exhausted` when it does not — the

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

@@ -9,8 +9,9 @@ import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 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 } from './backlog-plan'
+import { backlog_plan, type NamedPlan, type PlanContext } from './backlog-plan'
 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).
@@ -36,9 +37,18 @@ 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).
 const ONLY_FLAG = '--only'
+// The flag that renders the run's order wave by wave instead of the pool's sections
+// (joshuafolkken/kit#2778).
+const WAVES_FLAG = '--waves'
 
 const USAGE =
-	'Usage: josh backlog:plan [#<issue-number>...] [--only] [--exclude <issue-number>[,<issue-number>...]]...'
+	'Usage: josh backlog:plan [#<issue-number>...] [--only] [--waves] [--exclude <issue-number>[,<issue-number>...]]...'
+
+// The waves play the opted-in pool forward, and a named prefix runs ahead of it one issue at a time —
+// an epic among them running its children first — so waves drawn from the pool alone would promise an
+// order that invocation does not take.
+const WAVES_WITH_NAMED_MESSAGE =
+	'`--waves` plans the opted-in backlog alone; drop the named issues (and `--only`) to see its waves.'
 
 // The leading `#N` tokens are the named prefix a `backlogrun #N1 #N2 …` runs before the pool. They are
 // read through the invocation grammar so the plan and the run agree on what counts as a named issue.
@@ -56,10 +66,10 @@ function has_only_flag(argv: ReadonlyArray<string>): boolean {
 	return argv.includes(ONLY_FLAG)
 }
 
-// `--only` is stripped before the named block and the options are read, so it is never taken for a
-// positional or an unknown option; whether it was present is carried as a boolean instead.
-function without_only(argv: ReadonlyArray<string>): ReadonlyArray<string> {
-	return argv.filter((token) => token !== ONLY_FLAG)
+// `--only` and `--waves` are stripped before the named block and the options are read, so neither is
+// taken for a positional or an unknown option; whether each was present is carried as a boolean.
+function without_flags(argv: ReadonlyArray<string>): ReadonlyArray<string> {
+	return argv.filter((token) => token !== ONLY_FLAG && token !== WAVES_FLAG)
 }
 
 // The one start-time refusal: `--only` with no named issues has nothing to run. `backlog_named` is the
@@ -103,6 +113,12 @@ interface OpenListing {
 	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(
@@ -138,26 +154,32 @@ async function fetch_open(): Promise<OpenListing | undefined> {
 	return read.kind === 'read' ? { rows: read.rows, is_capped } : undefined
 }
 
-function print_plan(
-	plan: Plan,
-	open_issues: ReadonlyArray<OpenIssueData>,
-	is_capped: boolean,
-	named: NamedPlan,
-): void {
-	const scope = { repo: plan.repo, exclude: plan.exclude, tracked: plan.tracked }
-	const rows = backlog_scope.out_of_scope(open_issues, plan.result, scope)
-	// 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.
-	const context = {
+// 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(open_issues),
-		open_numbers: is_capped ? undefined : backlog_scope.open_numbers_of(open_issues),
+		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)
+
+	if (view.is_waves) {
+		console.info(backlog_waves.format_waves(plan.result, context))
 
-	console.info(backlog_plan.format_plan(plan.result, rows, context, named))
+		return
+	}
+
+	const scope = { repo: plan.repo, exclude: plan.exclude, tracked: plan.tracked }
+	const rows = backlog_scope.out_of_scope(listing.rows, plan.result, scope)
+
+	console.info(backlog_plan.format_plan(plan.result, rows, context, view.named))
 }
 
-async function report(plan: Plan, named: NamedPlan): Promise<number> {
+async function report(plan: Plan, view: PlanView): Promise<number> {
 	const listing = await fetch_open()
 
 	if (listing === undefined) {
@@ -167,12 +189,12 @@ async function report(plan: Plan, named: NamedPlan): Promise<number> {
 	}
 
 	if (listing.is_capped) console.error(OPEN_TRUNCATED_MESSAGE)
-	print_plan(plan, listing.rows, listing.is_capped, named)
+	print_plan(plan, listing, view)
 
 	return SUCCESS_EXIT_CODE
 }
 
-async function run_plan(rest: ReadonlyArray<string>, named: NamedPlan): Promise<number> {
+async function run_plan(rest: ReadonlyArray<string>, view: PlanView): Promise<number> {
 	const options = auto_ok_cli.parse_options(without_named(rest), USAGE)
 
 	if (options.usage !== undefined) {
@@ -191,17 +213,33 @@ async function run_plan(rest: ReadonlyArray<string>, named: NamedPlan): Promise<
 
 	const plan = await classify(opted_in, options.exclude ?? [])
 
-	return plan === undefined ? FAILURE_EXIT_CODE : await report(plan, named)
+	return plan === undefined ? FAILURE_EXIT_CODE : await report(plan, view)
+}
+
+// The start-time refusals, `--only`'s and `--waves`'s, in one place so `run` stays a straight line.
+//
+// The waves refusal reads the named block from the flag-stripped tokens, so `--waves #5` is refused
+// like `#5 --waves` rather than having its `#5` dropped by the option parser.
+function refusal_of(
+	named: ReadonlyArray<number>,
+	rest: ReadonlyArray<string>,
+	is_only: boolean,
+	is_waves: boolean,
+): string | undefined {
+	if (!is_waves) return only_refusal(named, is_only)
+
+	return is_only || named_of(rest).length > 0 ? WAVES_WITH_NAMED_MESSAGE : undefined
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const is_only = has_only_flag(argv)
-	const rest = without_only(argv)
+	const is_waves = argv.includes(WAVES_FLAG)
+	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).
 	const named = named_of(argv)
-	const refusal = only_refusal(named, is_only)
+	const refusal = refusal_of(named, rest, is_only, is_waves)
 
 	if (refusal !== undefined) {
 		console.error(refusal)
@@ -209,7 +247,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await run_plan(rest, { issues: named, only: is_only })
+	return await run_plan(rest, { named: { issues: named, only: is_only }, is_waves })
 }
 
 // `process.exitCode` rather than `process.exit()`, the reason `backlog:next` records: the plan is
@@ -222,6 +260,7 @@ const backlog_plan_cli = {
 	OPEN_TRUNCATED_MESSAGE,
 	OPEN_UNREADABLE_MESSAGE,
 	USAGE,
+	WAVES_WITH_NAMED_MESSAGE,
 	classify,
 	fetch_open,
 	main,

package/scripts/backlog/backlog-plan.ts

@@ -1,7 +1,9 @@
 import type { EpicChild } from '#scripts/epic/epic-graph'
 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 type { IssueReference } from '#scripts/git/git-epic-reference'
-import { has_label_name, IN_PROGRESS_LABEL } from '#scripts/git/issue-labels'
+import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
 // The plan a person reads before a `backlogrun` starts (joshuafolkken/kit#1652).
@@ -74,8 +76,28 @@ function join_row(reference: string, title: string, note: string): string {
 	return `${ROW_INDENT}${parts.join('  ')}`
 }
 
+// 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).
+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.
+const UNTRIAGED_MARK = '[untriaged]'
+
+function mark_of(child: EpicChild): string | undefined {
+	if (epic_solo.is_solo(child)) return SOLO_MARK
+
+	return epic_triage.is_triaged(child) ? undefined : UNTRIAGED_MARK
+}
+
+function marked_reference(child: EpicChild, repo: string): string {
+	const reference = reference_of(child, repo)
+	const mark = mark_of(child)
+
+	return mark === undefined ? reference : `${reference} ${mark}`
+}
+
 function row_of(child: EpicChild, context: PlanContext, note: string): string {
-	return join_row(reference_of(child, context.repo), title_of(child, context), note)
+	return join_row(marked_reference(child, context.repo), title_of(child, context), note)
 }
 
 // Why this one is not offered yet. The blocker numbers are the answer whenever there are any — that
@@ -221,9 +243,15 @@ const backlog_plan = {
 	PAST_OFFER_NOTE,
 	READY_HEADING,
 	SCOPE_HEADING,
+	SOLO_MARK,
+	UNTRIAGED_MARK,
 	UNUSABLE_HEADING,
 	WAITING_HEADING,
 	format_plan,
+	format_unusable,
+	marked_reference,
+	row_of,
+	section,
 	waiting_note,
 }
 

package/scripts/backlog/backlog-stalled.ts

@@ -1,3 +1,4 @@
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
 
 // When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks
@@ -101,6 +102,13 @@ function count_ready_tokens(out: string): number {
 	return ready_tokens(out).length
 }
 
+// Whether `backlog:next` answered `triage` (joshuafolkken/kit#2779): no number is runnable, yet a session
+// has work — judging the untriaged issues — so a reader of the numeric lines alone would take it for an
+// empty pool.
+function needs_triage(out: string): boolean {
+	return out.split('\n').some((token) => token.trim() === epic_triage.TRIAGE_VERDICT)
+}
+
 const backlog_stalled = {
 	STALLED,
 	OK,
@@ -111,6 +119,7 @@ const backlog_stalled = {
 	describe,
 	dispatch_age_ms,
 	is_stalled,
+	needs_triage,
 	ready_tokens,
 }