@joshuafolkken/kit 1.1514.0 → 1.1784.0

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')

package/scripts/backlog/backlog-pool.ts

@@ -7,12 +7,7 @@ import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
 import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
-import {
-	ALREADY_DONE_LABEL,
-	EPIC_LABEL,
-	has_any_label,
-	NEEDS_DECISION_LABEL,
-} from '#scripts/issue/issue-labels'
+import { EPIC_LABEL, has_any_label, PARKED_LABELS } from '#scripts/issue/issue-labels'
 
 // The candidate pool `josh backlog:next` answers from.
 //
@@ -25,11 +20,12 @@ import {
 
 const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
 // The labels that put a withheld row in the "needs a person" bucket rather than the "waiting on
-// time" one. `already-done` belongs with `needs-decision` because no amount of waiting moves it: the
-// work is merged and the close is Tier C, so a person is the only thing that resolves it.
+// time" one are the park labels (`PARKED_LABELS`). `already-done` and `run:stalled` belong with
+// `needs-decision` because no amount of waiting moves them: the work is merged and the close is Tier C,
+// or a mechanical cause has to be fixed, so a person is the only thing that resolves it.
 // Read as `time`, it would be reported as something that resolves itself
-// and nobody would ever be told to close it.
-const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
+// and nobody would ever be told to act on it.
+const DECISION_LABELS: ReadonlySet<string> = PARKED_LABELS
 
 // 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.
@@ -140,6 +136,9 @@ function settle_standalone(
 // `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.
+//
+// The body rides along as an epic child's does, so a declared start time (`issue-not-before.ts`)
+// reaches the classification and the board's waiting row for a standalone row too (#4014).
 function to_child(issue: OpenIssueData, repo: string): EpicChild {
 	return {
 		number: issue.number,
@@ -147,6 +146,7 @@ function to_child(issue: OpenIssueData, repo: string): EpicChild {
 		state: 'OPEN',
 		labels: (issue.labels ?? []).map((label) => label.name),
 		blocked_by: epic_issue.blocker_references_of(issue, repo),
+		body: issue.body,
 	}
 }
 

package/scripts/backlog/backlog-rank.ts

@@ -4,6 +4,7 @@ import { epic_rank } from '#scripts/epic/epic-rank'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
+import type { LaneRecords } from '#scripts/lane/lane-state'
 import { backlog_overlap, type Declared } from './backlog-overlap'
 
 // What the backlog offers, in the order it is decided: rank, then the
@@ -82,15 +83,21 @@ interface OfferInput {
 	// The paths each issue declares; two candidates whose paths overlap are not offered together.
 	// Absent, nothing is separated.
 	declared?: Declared
+	// The issues' lane state records; a clash with a paused holder says so. Absent, none is named.
+	lanes?: LaneRecords
 }
 
 // The overlap separation runs before the cap, for the reason the gate does: the cap only ever
 // removes what would otherwise be offered.
 function select(input: OfferInput): SoloSelection {
 	const ranked = rank(input.candidates, input.pool)
-	const { read, repo } = input
+	const { read, repo, lanes } = input
 	const gated = epic_solo.select(ranked, read, repo)
-	const separated = backlog_overlap.separate(gated, input.declared ?? new Map(), { read, repo })
+	const separated = backlog_overlap.separate(gated, input.declared ?? new Map(), {
+		read,
+		repo,
+		lanes,
+	})
 
 	return cap(separated, input.standalone)
 }
@@ -98,6 +105,7 @@ function select(input: OfferInput): SoloSelection {
 interface GateScope {
 	standalone: ReadonlySet<string>
 	declared: Declared
+	lanes?: LaneRecords
 }
 
 // `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.