@joshuafolkken/kit 1.872.0

package/scripts/backlog/backlog-pool.ts

@@ -0,0 +1,322 @@
+import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
+import type { Classification } from '#scripts/epic/epic-classify'
+import { epic_graph, type EpicChild, type GraphAnomaly } from '#scripts/epic/epic-graph'
+import { epic_index } from '#scripts/epic/epic-index'
+import { epic_issue } from '#scripts/epic/epic-issue'
+import type { EpicView } from '#scripts/epic/epic-next-views'
+import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
+import { git_next_issues } from '#scripts/git/git-next-issues'
+import {
+	ALREADY_DONE_LABEL,
+	EPIC_LABEL,
+	has_any_label,
+	NEEDS_DECISION_LABEL,
+} from '#scripts/git/issue-labels'
+import type { OpenIssueData } from '#scripts/git/schemas'
+
+// The candidate pool `josh backlog:next` answers from (joshuafolkken/kit#1630).
+//
+// 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
+// steps, and so the two halves arrive as the one shape the verdict is decided from —
+// `epic-classify.ts`'s `Classification`, which `epic-report.ts` then turns into the answer. Nothing
+// here re-implements the dependency graph or the wave: the epic half arrives already classified by
+// `epic:next`'s own pipeline, and this module only merges it with the standalone half.
+
+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
+// and nobody would ever be told to close it.
+const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
+
+// What decides whether a standalone row is offered: the children an opted-in epic is going to offer
+// 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
+// `auto-ok:next` alike.
+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
+	// waits on a person rather than on time, exactly as an epic child's does.
+	running: ReadonlySet<string>
+}
+
+function is_epic_row(issue: OpenIssueData): boolean {
+	return has_any_label(issue.labels, EPIC_LABELS)
+}
+
+// Whether a row is waiting on an open issue this backlog will never run. Only a blocker whose state
+// was read counts: one with no state stays `time`, the fail-safe `auto_ok_cli.is_runnable` already
+// applies to it.
+function waits_outside(issue: OpenIssueData, running: ReadonlySet<string>, repo: string): boolean {
+	return epic_issue
+		.blocker_references_of(issue, repo)
+		.some((blocker) => blocker.state === 'OPEN' && !running.has(epic_graph.blocker_key(blocker)))
+}
+
+function needs_person(issue: OpenIssueData, context: StandaloneContext): boolean {
+	return (
+		has_any_label(issue.labels, DECISION_LABELS) ||
+		waits_outside(issue, context.running, context.repo)
+	)
+}
+
+// The running set with every standalone row a person has to resolve taken out, repeated until a pass
+// removes nothing — a row waiting on such a row waits on that person too, however long the chain.
+function settle_standalone(
+	running: ReadonlySet<string>,
+	issues: ReadonlyArray<OpenIssueData>,
+	repo: string,
+): ReadonlySet<string> {
+	const settled = new Set(running)
+
+	// An epic row is never in the set, so deleting its key changes nothing and it needs no filter.
+	for (const issue of issues) {
+		const is_stuck =
+			has_any_label(issue.labels, DECISION_LABELS) || waits_outside(issue, running, repo)
+
+		if (is_stuck) settled.delete(epic_graph.key_of({ repo, number: issue.number }))
+	}
+
+	return settled.size === running.size ? running : settle_standalone(settled, issues, repo)
+}
+
+// An opted-in row as the graph's node type. Both halves of the pool are then the same shape, so one
+// 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 —
+// `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 {
+	return {
+		number: issue.number,
+		repo,
+		state: 'OPEN',
+		labels: (issue.labels ?? []).map((label) => label.name),
+		blocked_by: epic_issue.blocker_references_of(issue, repo),
+	}
+}
+
+function to_children(issues: ReadonlyArray<OpenIssueData>, repo: string): Array<EpicChild> {
+	return issues.map((issue) => to_child(issue, repo))
+}
+
+// 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).
+//
+// 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
+// closure follows the tracking index down into a nested epic and its own nested epics, so a person's
+// one label on the root approves the whole subtree — exactly as typing `epicrun #<E>` approves every
+// merge inside `#<E>`, however deep.
+function opted_in_epics(
+	issues: ReadonlyArray<OpenIssueData>,
+	tracking: ReadonlyMap<number, ReadonlyArray<number>>,
+): ReadonlyArray<number> {
+	return [...epic_index.reachable_epic_numbers(tracking, issues)]
+}
+
+// The rows that stand for themselves. An epic root is a container rather than work, so it is never a
+// standalone candidate however it is labelled — `prioritize` drops it again below, and this keeps it
+// out of the count as well.
+function standalone_rows(issues: ReadonlyArray<OpenIssueData>): ReadonlyArray<OpenIssueData> {
+	return issues.filter((issue) => !is_epic_row(issue))
+}
+
+// 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
+// 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: StandaloneContext): boolean {
+	return !context.tracked.has(issue.number) && !context.exclude.includes(issue.number)
+}
+
+// The standalone half, in the buckets the verdict is read from.
+//
+// The order is `git_next_issues.prioritize`'s and not a second one — the same ranking the
+// `🗒 Next issues` display and `auto-ok:next` already answer with, cap included, so the three cannot
+// disagree about what comes next. Anything it withholds is still open work: `needs-decision` is
+// waiting on a person, and everything else — a standing blocker, a run already in progress, a row
+// past the cap — resolves on its own and is waiting on time. **The cap is one of those**: a sixth
+// runnable standalone issue is reported as waiting rather than offered, and the next ask offers it
+// once one of the five above it merges, so the backlog drains without it ever being lost. That is
+// the cost of having one ranking rather than two, and `docs/josh-commands.md` states it.
+function classify_standalone(
+	issues: ReadonlyArray<OpenIssueData>,
+	context: StandaloneContext,
+): Classification {
+	const considered = issues.filter((issue) => is_considered(issue, context))
+	const runnable = git_next_issues.prioritize(
+		considered.filter((issue) => auto_ok_cli.is_runnable(issue, context.tracked, context.exclude)),
+	)
+	const offered = new Set(runnable.map((issue) => issue.number))
+	const withheld = considered.filter((issue) => !offered.has(issue.number))
+
+	return {
+		runnable: to_children(runnable, context.repo),
+		time: to_children(
+			withheld.filter((issue) => !needs_person(issue, context)),
+			context.repo,
+		),
+		human: to_children(
+			withheld.filter((issue) => needs_person(issue, context)),
+			context.repo,
+		),
+	}
+}
+
+// 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
+// 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`.
+function running_set(
+	graphs: ReadonlyArray<ReadonlyArray<EpicChild>>,
+	issues: ReadonlyArray<OpenIssueData>,
+	repo: string,
+): ReadonlySet<string> {
+	const running = epic_outside_blocker.running_keys([
+		...graphs.flat(),
+		...to_children(standalone_rows(issues), repo),
+	])
+
+	return settle_standalone(running, issues, repo)
+}
+
+// A cycle no single epic can see, because its links cross from one graph into another. Each epic's own
+// cycle is already that epic's anomaly, and a loop among standalone rows alone has always left them
+// waiting without stopping the backlog, so what is reported here is only what crossing a graph adds.
+function cross_epic_cycles(
+	graphs: ReadonlyArray<ReadonlyArray<EpicChild>>,
+	standalone: ReadonlyArray<EpicChild>,
+): Array<GraphAnomaly> {
+	const within = new Set(
+		[...graphs, standalone].flatMap((children) => epic_graph.find_stuck_children(children)),
+	)
+	// The loops already known are left out before the walk rather than filtered from its answer, so what
+	// only sits downstream of one peels away instead of being named as a loop of its own.
+	const union = [...epic_graph.index_children([...graphs.flat(), ...standalone]).values()]
+	const stuck = epic_graph.find_stuck_children(
+		union.filter((child) => !within.has(epic_graph.key_of(child))),
+	)
+
+	if (stuck.length === 0) return []
+
+	return [
+		{
+			kind: 'cycle',
+			message: `Dependency cycle across the backlog: ${stuck.join(', ')} can never start until a person breaks it`,
+		},
+	]
+}
+
+// Two epics can list the same child. `epic:next` answers about one epic at a time and never sees it;
+// here the child would reach standard output twice, and a loop starting one run per line would start
+// it twice. Keyed by repository and number, because two repositories legitimately have an issue of
+// the same number.
+function unique_children(children: ReadonlyArray<EpicChild>): Array<EpicChild> {
+	const seen = new Set<string>()
+	const unique: Array<EpicChild> = []
+
+	for (const child of children) {
+		if (seen.has(epic_graph.key_of(child))) continue
+		seen.add(epic_graph.key_of(child))
+		unique.push(child)
+	}
+
+	return unique
+}
+
+function without(children: ReadonlyArray<EpicChild>, taken: ReadonlySet<string>): Array<EpicChild> {
+	return children.filter((child) => !taken.has(epic_graph.key_of(child)))
+}
+
+function keys_of(children: ReadonlyArray<EpicChild>): Set<string> {
+	return new Set(children.map((child) => epic_graph.key_of(child)))
+}
+
+// The epic half, already classified. `epic:next` decided each of these — the `blocked-by` graph, the
+// wave, the anomalies — so this only flattens the per-repository bundles back into one list, in the
+// order the epics' own task lists gave them.
+//
+// **Withholding wins across the buckets, not only within one.** Two epics can classify the same child
+// differently — one tracks the blocker and calls it `time`, the other does not track it and calls it
+// `runnable` — and a child offered on standard output while standard error lists it as waiting is
+// work a loop would start against a dependency that is still standing. So `human` is settled first,
+// `time` next, and `runnable` keeps only what neither claimed.
+function epic_classification(views: ReadonlyArray<EpicView>): Classification {
+	const human = unique_children(views.flatMap((view) => view.result.blocked_on_people))
+	const time = without(
+		unique_children(views.flatMap((view) => view.result.waiting)),
+		keys_of(human),
+	)
+	const offered = views.flatMap((view) =>
+		view.result.candidates.flatMap((bundle) => bundle.children),
+	)
+
+	return {
+		runnable: without(unique_children(offered), keys_of([...human, ...time])),
+		time,
+		human,
+	}
+}
+
+// `--exclude` takes bare numbers, and a bare number names an issue of the repository the command is
+// running in. A child elsewhere with the same number is a different issue, so the comparison carries
+// the repository rather than the number alone.
+function is_kept(child: EpicChild, exclude: ReadonlyArray<number>, repo: string): boolean {
+	return child.repo !== repo || !exclude.includes(child.number)
+}
+
+// A child that merged moments ago still reads as open until GitHub applies `closes #N`, so an
+// exclusion drops it from every bucket rather than only from the offer: left in `time`, it would
+// answer `wait` for a backlog with nothing left to wait for.
+function drop_excluded(
+	classification: Classification,
+	exclude: ReadonlyArray<number>,
+	repo: string,
+): Classification {
+	return {
+		runnable: classification.runnable.filter((child) => is_kept(child, exclude, repo)),
+		time: classification.time.filter((child) => is_kept(child, exclude, repo)),
+		human: classification.human.filter((child) => is_kept(child, exclude, repo)),
+	}
+}
+
+// The epic half first, then the standalone half. An epic's children are work somebody has already
+// planned and ordered, so finishing what is in flight comes before starting something new.
+function merge_classifications(left: Classification, right: Classification): Classification {
+	return {
+		runnable: [...left.runnable, ...right.runnable],
+		time: [...left.time, ...right.time],
+		human: [...left.human, ...right.human],
+	}
+}
+
+const backlog_pool = {
+	classify_standalone,
+	cross_epic_cycles,
+	running_set,
+	settle_standalone,
+	drop_excluded,
+	epic_classification,
+	is_epic_row,
+	keys_of,
+	merge_classifications,
+	opted_in_epics,
+	standalone_rows,
+	to_child,
+	to_children,
+	unique_children,
+}
+
+export { backlog_pool }
+export type { StandaloneContext }

package/scripts/backlog/backlog-ready.ts

@@ -0,0 +1,146 @@
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import type { RunCarry } from '#scripts/run/run-carry'
+import { run_headless } from '#scripts/run/run-headless'
+import { run_invocation } from '#scripts/run/run-invocation'
+import { backlog_stalled } from './backlog-stalled'
+
+// The ready line reports runnable work to the driving backlogrun parent on a watcher wake.
+
+const NO_FREE = 0
+const NONE = 0
+
+interface ReadyReading {
+	issues: ReadonlyArray<string>
+	free_lanes: number
+}
+
+interface ReadyPorts {
+	free_lane_count: () => Promise<number>
+	ready_issues: () => Promise<ReadonlyArray<string>>
+}
+
+// Free lanes right now: the limit less the live lanes. An unreadable limit reads as no free lane — the
+// safe direction, since both the stall and the ready line need a free lane and reporting one that is
+// not there is the false positive neither may raise.
+//
+// **Occupancy is the local worktree count, not the dispatch budget's busy read.** `epic-lane-offer`
+// measures occupancy with `epic_busy.occupied_lanes`, a network read of in-progress issue labels; this
+// counts live worktrees instead, deliberately — it runs on the cheap-first path where the costly read
+// (`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()
+
+	if (limit.kind !== 'limit') return NO_FREE
+
+	const lanes = await lane_registry.list_lanes()
+	const live = lanes.filter((lane) => !lane.is_stranded).length
+
+	return lane_capacity.free_lanes(limit.limit, live)
+}
+
+// **A `--only` run has no pool to drain** (joshuafolkken/kit#2472). `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.
+function drains_pool(carry: RunCarry | undefined): boolean {
+	return carry === undefined || !run_invocation.has_only(carry.invocation)
+}
+
+// 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
+// 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
+
+	return await josh_command.josh_run(['backlog:next'], timeout_ms === undefined, timeout_ms)
+}
+
+// The runnable issues for this checkout, read the way a loop reads them: `backlog:next`'s numeric lines.
+async function ready_issues(): Promise<ReadonlyArray<string>> {
+	const result = await read_backlog_next()
+
+	return result === undefined ? [] : backlog_stalled.ready_tokens(result.out)
+}
+
+const DEFAULT_PORTS: ReadyPorts = { free_lane_count, ready_issues }
+
+// Cheap first: a full pool answers without the network read, since ready work with nowhere to go is not
+// a pick-up.
+async function read_ready(ports: ReadyPorts = DEFAULT_PORTS): Promise<ReadyReading> {
+	const free_lanes = await ports.free_lane_count()
+
+	if (free_lanes <= NO_FREE) return { issues: [], free_lanes }
+
+	return { issues: await ports.ready_issues(), free_lanes }
+}
+
+// `undefined` unless there is both runnable work and a lane for it — the only state worth a line.
+function ready_line(reading: ReadyReading): string | undefined {
+	if (reading.issues.length === NONE || reading.free_lanes <= NO_FREE) return undefined
+
+	const issues = reading.issues.map((issue) => `#${issue}`).join(' ')
+
+	return `ready ${issues} · free lanes ${String(reading.free_lanes)}`
+}
+
+// The watcher's line on exit, for the driving parent alone — a `fullrun` watcher has no pool to pick
+// from. Best-effort: a reading that fails prints nothing rather than failing the watcher whose exit is
+// the wake.
+async function parent_ready_line(
+	ports: ReadyPorts,
+	is_parent: () => Promise<boolean>,
+): Promise<string | undefined> {
+	if (!(await is_parent())) return undefined
+
+	return ready_line(await read_ready(ports))
+}
+
+async function print_ready_line(
+	ports: ReadyPorts = DEFAULT_PORTS,
+	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+): Promise<void> {
+	try {
+		const line = await parent_ready_line(ports, is_parent)
+
+		if (line !== undefined) console.info(line)
+	} catch {
+		// A pick-up line is a hint; the wake it rides must still be delivered.
+	}
+}
+
+// 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`,
+// `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 ' +
+	'runnable filing is dispatched now rather than on the next wake.'
+
+async function print_offer_hint(
+	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+): Promise<void> {
+	try {
+		if (await is_parent()) console.info(OFFER_HINT)
+	} catch {
+		// A hint that cannot read the carry record says nothing; the insertion itself has landed.
+	}
+}
+
+const backlog_ready = {
+	DEFAULT_PORTS,
+	OFFER_HINT,
+	read_backlog_next,
+	print_offer_hint,
+	free_lane_count,
+	drains_pool,
+	print_ready_line,
+	read_ready,
+	ready_issues,
+	ready_line,
+}
+
+export { backlog_ready }
+export type { ReadyPorts, ReadyReading }

package/scripts/backlog/backlog-scope.ts

@@ -0,0 +1,144 @@
+import type { EpicNextResult } from '#scripts/epic/epic-report'
+import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
+import type { OpenIssueData } from '#scripts/git/schemas'
+
+// Which open issues the backlog will not run, and why (joshuafolkken/kit#1652).
+//
+// **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".
+//
+// 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.
+
+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
+// 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 =
+	'epic root without `auto-ok` — it offers no children, and only a child carrying `auto-ok` itself is offered'
+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
+// 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`
+}
+
+// `--exclude` drops an issue from every bucket, so an excluded one lands here. Named for what it is,
+// because the label-derived reasons would otherwise report a cap that had nothing to do with it.
+const EXCLUDED_REASON = 'excluded from this ask — it merged moments ago'
+
+interface OutOfScopeRow {
+	number: number
+	title: string
+	reason: string
+}
+
+// What the subtraction is made against: this repository, and the numbers the caller excluded.
+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.
+	tracked: ReadonlyMap<number, number>
+}
+
+// A child elsewhere is excluded by repository rather than by number: two repositories legitimately
+// have an issue of the same number, and the open listing this is subtracted from is this one's.
+function planned_numbers(result: EpicNextResult, repo: string): ReadonlySet<number> {
+	const children = [
+		...result.candidates.flatMap((bundle) => bundle.children),
+		...result.waiting,
+		...result.blocked_on_people,
+	]
+
+	return new Set(children.filter((child) => child.repo === repo).map((child) => child.number))
+}
+
+// An epic root carrying `auto-ok` is not an omission — it is a container whose children are planned
+// individually, which is the distinction a person reading "why is this not running" most needs.
+function opted_in_reason(issue: OpenIssueData, tracked: ReadonlyMap<number, number>): string {
+	const epic = tracked.get(issue.number)
+
+	return epic === undefined ? OPTED_IN_UNPLACED_REASON : epic_tracked_reason(epic)
+}
+
+function label_reason(issue: OpenIssueData, tracked: ReadonlyMap<number, number>): string {
+	const is_opted_in = has_any_label(issue.labels, AUTO_OK_LABELS)
+
+	if (has_any_label(issue.labels, EPIC_LABELS)) {
+		return is_opted_in ? EPIC_ROOT_REASON : EPIC_NOT_OPTED_IN_REASON
+	}
+
+	return is_opted_in ? opted_in_reason(issue, tracked) : NO_OPT_IN_REASON
+}
+
+// The exclusion is checked before the labels, because it is why the issue is here at all: an
+// excluded row still carries whatever labels it had, and reading those would name a cause that had
+// nothing to do with its absence from the plan.
+function reason_for(issue: OpenIssueData, scope: ScopeContext): string {
+	return scope.exclude.includes(issue.number) ? EXCLUDED_REASON : label_reason(issue, scope.tracked)
+}
+
+function out_of_scope(
+	open_issues: ReadonlyArray<OpenIssueData>,
+	result: EpicNextResult,
+	scope: ScopeContext,
+): ReadonlyArray<OutOfScopeRow> {
+	const planned = planned_numbers(result, scope.repo)
+
+	return open_issues
+		.filter((issue) => !planned.has(issue.number))
+		.map((issue) => ({
+			number: issue.number,
+			title: issue.title,
+			reason: reason_for(issue, scope),
+		}))
+}
+
+// The pool carries issue numbers and labels but no titles, and a plan of bare numbers is not a plan a
+// person can read. The one open listing the subtraction already needs is where they come from, so no
+// second read is made for them.
+function titles_of(open_issues: ReadonlyArray<OpenIssueData>): ReadonlyMap<number, string> {
+	return new Map(open_issues.map((issue) => [issue.number, issue.title]))
+}
+
+// The numbers still open in this repository, which is how a waiting row tells a standing blocker from
+// one that has since closed. Same listing, so it costs nothing beyond the map above.
+function open_numbers_of(open_issues: ReadonlyArray<OpenIssueData>): ReadonlySet<number> {
+	return new Set(open_issues.map((issue) => issue.number))
+}
+
+const backlog_scope = {
+	epic_tracked_reason,
+	EPIC_NOT_OPTED_IN_REASON,
+	EPIC_ROOT_REASON,
+	EXCLUDED_REASON,
+	NO_OPT_IN_REASON,
+	OPTED_IN_UNPLACED_REASON,
+	open_numbers_of,
+	out_of_scope,
+	planned_numbers,
+	reason_for,
+	titles_of,
+}
+
+export { backlog_scope }
+export type { OutOfScopeRow, ScopeContext }

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { backlog_stalled } from './backlog-stalled'
+import { backlog_stalled_detect } from './backlog-stalled-detect'
+
+// `josh backlog:stalled` — read the three conditions once and print the verdict
+// (joshuafolkken/kit#2359). This is the manual and testable face of the detector `stop-guard.ts` runs
+// on every stop; both call the one `detect_and_report`, so the command and the hook can never drift.
+//
+// **It reports, it never stops.** The exit code is always success — a stall is a state to surface, not
+// an error to fail on — so a caller (a person, a test, a wired hook) reads the verdict off stdout and is
+// never halted by it. An unreadable record prints `unreadable` for the same reason: the run carries on.
+
+const SUCCESS_EXIT_CODE = 0
+
+async function main(): Promise<void> {
+	try {
+		console.info(await backlog_stalled_detect.detect_and_report())
+	} catch {
+		console.info(backlog_stalled.UNREADABLE)
+	}
+
+	process.exitCode = SUCCESS_EXIT_CODE
+}
+
+const backlog_stalled_cli = { main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { backlog_stalled_cli }