@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/auto-ok/auto-ok-cli.ts

@@ -3,19 +3,19 @@ import { fileURLToPath } from 'node:url'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
 import { epic_index, type FetchedEpics } from '#scripts/epic/epic-index'
 import { epic_issue } from '#scripts/epic/epic-issue'
-import { git_gh_command } from '#scripts/git/git-gh-command'
-import { SUMMARY_FIELDS } from '#scripts/git/git-gh-issue'
-import { git_next_issues } from '#scripts/git/git-next-issues'
-import { AUTO_OK_LABEL } from '#scripts/git/issue-labels'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { SUMMARY_FIELDS } from '#scripts/gh/git-gh-issue'
 import { cutoff_cause, cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { read_json_listing } from '#scripts/git/parse-json-array'
 import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
+import { git_next_issues } from '#scripts/issue/git-next-issues'
+import { AUTO_OK_LABEL } from '#scripts/issue/issue-labels'
 
 // `josh auto-ok:next` — which issue outside the epic an unattended run picks up next
 // (joshuafolkken/kit#906).
 //
 // A command rather than a documented `gh` invocation, for the reason the label constant exists: the
-// name `auto-ok` is single-sourced in `scripts/git/issue-labels.ts`, and a procedure that told an
+// name `auto-ok` is single-sourced in `scripts/issue/issue-labels.ts`, and a procedure that told an
 // agent to type `gh issue list --label auto-ok` would put a second copy of it in prose, where
 // nothing checks it. The contract is `epic:next`'s: one token on standard output, every explanation
 // on standard error, so `answer=$(pnpm josh auto-ok:next)` reads it.
@@ -48,7 +48,7 @@ const LISTING_LIMIT = 200
 // CLI's version cannot be what changed the row shape — the same misdirection the message below
 // already refuses to repeat for the blocker relations, left standing one constant above it.
 const UNREADABLE_MESSAGE = `Could not read the \`${AUTO_OK_LABEL}\` listing. That is not "nothing is opted in" — check \`gh auth status\` and ask again.`
-const UNEXPECTED_SHAPE_MESSAGE = `Read the \`${AUTO_OK_LABEL}\` listing but could not parse it. That is not "nothing is opted in" — the rows came back in a shape this command does not recognize, so check the fields it asks for and the REST field mapping in \`scripts/git/git-gh-issue-rest.ts\` rather than your authentication.`
+const UNEXPECTED_SHAPE_MESSAGE = `Read the \`${AUTO_OK_LABEL}\` listing but could not parse it. That is not "nothing is opted in" — the rows came back in a shape this command does not recognize, so check the fields it asks for and the REST field mapping in \`scripts/gh/git-gh-issue-rest.ts\` rather than your authentication.`
 // The blocker relations failing takes the whole listing with them, and `issue_list` swallows
 // the error — so the read looks exactly like an access failure and sends the reader to
 // `gh auth status`, which is green. That is the misdirection joshuafolkken/kit#996 added the message
@@ -491,23 +491,13 @@ const auto_ok_cli = {
 	TRUNCATED_WITHOUT_ANSWER,
 	NONE_OPTED_IN_MESSAGE,
 	truncated_cause,
-	parse_issue_number,
-	parse_exclude,
-	parse_pair,
 	parse_options,
 	fetch_opted_in,
-	parse_listing,
-	is_page_complete,
-	is_closed,
-	is_unblocked,
 	fetch_tracking,
 	is_runnable,
 	pick_next,
 	truncation_note,
-	none_reason,
-	report,
 	run,
-	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/backlog/backlog-arrival.ts

@@ -18,10 +18,11 @@ import { backlog_stalled } from './backlog-stalled'
 //
 // **"New" is measured against the watcher's own start**, so one issue wakes the parent once: the next
 // `--wait` the parent starts takes the pool as it stands then — the woken issue included, dispatched or
-// not — as its baseline. A reading that fails is not an arrival; the probe says nothing and the
-// interval still wakes the parent. A baseline that cannot be read leaves that one wait inert rather than
-// reading it as empty — an empty one would wake the parent for the whole pool — and the next `--wait`
-// reads it again.
+// not — as its baseline. A reading that fails is not an arrival; the probe says nothing and reads again
+// a minute later. A baseline that cannot be read is never read as empty — an empty one would wake the
+// parent for the whole pool — but it is not given up on either: the scheduled report no longer ends the
+// wait (joshuafolkken/kit#3102), so an inert probe would leave the parent without a wake until `--hours`. The
+// probe reads the baseline again each minute until one answers.
 //
 // **Every read is bounded.** The probe is awaited inside the watcher's tick loop, so a `gh` call that
 // hangs would otherwise freeze the loop — its `--hours` bound, its liveness ping and the exit that is
@@ -116,19 +117,40 @@ async function never_arrives(): Promise<boolean> {
 
 const INERT: ArrivalProbe = { has_arrived: never_arrives }
 
-// Only the next-probe instant changes between probes, and it is set before the read is awaited.
+// A probe spent on the baseline reports no arrival, whether or not the baseline answered.
+async function retry_baseline(
+	answered: Array<ReadonlySet<string>>,
+	ports: ReadyPorts,
+): Promise<boolean> {
+	const late = await read_baseline(ports)
+
+	if (late !== undefined) answered.push(late)
+
+	return false
+}
+
+// The next-probe instant is set before any read is awaited. A baseline that did not answer is read again
+// at the next probe instead of the reading, and the first one that answers is the baseline from then on
+// — never an arrival itself, since it is the pool as it stands.
 function probe_of(
-	baseline: ReadonlySet<string>,
+	initial: ReadonlySet<string> | undefined,
 	first_ms: number,
 	ports: ReadyPorts,
 ): ArrivalProbe {
 	let next_ms = first_ms
+	// At most one entry, held in a list so the baseline that answers after an await is added rather than
+	// reassigned over the value read before it.
+	const answered: Array<ReadonlySet<string>> = initial === undefined ? [] : [initial]
 
 	async function has_arrived(now_ms: number): Promise<boolean> {
 		if (now_ms < next_ms) return false
 
 		next_ms = now_ms + PROBE_INTERVAL_MS
 
+		const [baseline] = answered
+
+		if (baseline === undefined) return await retry_baseline(answered, ports)
+
 		const reading = await read_reading(ports)
 
 		return reading !== undefined && arrivals(baseline, reading).length > NONE
@@ -146,12 +168,10 @@ async function start(
 ): Promise<ArrivalProbe> {
 	if (!(await is_parent_safely(is_parent))) return INERT
 
-	const baseline = await read_baseline(ports)
-
-	return baseline === undefined ? INERT : probe_of(baseline, now_ms + PROBE_INTERVAL_MS, ports)
+	return probe_of(await read_baseline(ports), now_ms + PROBE_INTERVAL_MS, ports)
 }
 
-const backlog_arrival = { INERT, PROBE_INTERVAL_MS, answered_issues, arrivals, start }
+const backlog_arrival = { PROBE_INTERVAL_MS, answered_issues, arrivals, start }
 
 export type { ArrivalProbe }
 export { backlog_arrival }

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

@@ -32,11 +32,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean>>
 // A misspelled flag is refused rather than defaulted, the contract `path_decision.has_unknown_flag`
 // states for the path-decided commands: an invocation nobody can read is never answered.
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-function text_of(value: string | boolean | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 // `find` rather than a cast: an unrecognized word has to be refused, and a type assertion would
@@ -79,15 +75,15 @@ type Counts = Record<(typeof COUNT_NAMES)[number], number | undefined>
 
 function counts_of(values: ParsedValues): Counts {
 	return {
-		idle: to_count(text_of(values.idle)),
-		max: to_count(text_of(values.max)),
-		merged: to_count(text_of(values.merged)),
-		running: to_count(text_of(values.running)),
+		idle: to_count(cli_flags.string_of(values.idle)),
+		max: to_count(cli_flags.string_of(values.max)),
+		merged: to_count(cli_flags.string_of(values.merged)),
+		running: to_count(cli_flags.string_of(values.running)),
 	}
 }
 
 function are_counts_readable(values: ParsedValues, counts: Counts): boolean {
-	return COUNT_NAMES.every((name) => is_readable(text_of(values[name]), counts[name]))
+	return COUNT_NAMES.every((name) => is_readable(cli_flags.string_of(values[name]), counts[name]))
 }
 
 // **`--idle 0` is how the watch is turned off, and omitting the flag takes the default**
@@ -116,14 +112,17 @@ function to_idle_ms(idle_minutes: number | undefined): number | undefined {
 // lands on the very first ask, before the run has started anything, and the fix is one flag the loop
 // already holds: it always knows when it last had work.
 function is_watch_readable(values: ParsedValues): boolean {
-	if (to_idle_ms(to_count(text_of(values.idle))) === undefined) return true
+	if (to_idle_ms(to_count(cli_flags.string_of(values.idle))) === undefined) return true
 
-	return text_of(values.active) !== undefined
+	return cli_flags.string_of(values.active) !== undefined
 }
 
 function are_values_readable(values: ParsedValues): boolean {
 	return (
-		is_readable(text_of(values.active), to_time_ms(text_of(values.active))) &&
+		is_readable(
+			cli_flags.string_of(values.active),
+			to_time_ms(cli_flags.string_of(values.active)),
+		) &&
 		is_watch_readable(values) &&
 		are_counts_readable(values, counts_of(values))
 	)
@@ -138,7 +137,7 @@ function input_of(values: ParsedValues, base: InputBase): BudgetInput {
 
 	return {
 		...base,
-		active_at_ms: to_time_ms(text_of(values.active)) ?? base.started_at_ms,
+		active_at_ms: to_time_ms(cli_flags.string_of(values.active)) ?? base.started_at_ms,
 		merged: counts.merged ?? 0,
 		running: counts.running ?? 0,
 		max_issues: counts.max,
@@ -147,11 +146,11 @@ function input_of(values: ParsedValues, base: InputBase): BudgetInput {
 }
 
 function build_input(values: ParsedValues, now_ms: number): BudgetInput | undefined {
-	const answer = to_answer(text_of(values.answer))
+	const answer = to_answer(cli_flags.string_of(values.answer))
 
 	if (answer === undefined) return undefined
 
-	const started_at_ms = to_time_ms(text_of(values.started))
+	const started_at_ms = to_time_ms(cli_flags.string_of(values.started))
 
 	if (started_at_ms === undefined) return undefined
 	if (!are_values_readable(values)) return undefined

package/scripts/backlog/backlog-budget.ts

@@ -268,7 +268,6 @@ function decide(input: BudgetInput): BudgetDecision {
 
 const backlog_budget = {
 	ANSWERS,
-	ANSWER_STOP_REASONS,
 	BLOCKED_REASON,
 	DEFAULT_IDLE_MINUTES,
 	DEFAULT_IDLE_MS,
@@ -283,7 +282,6 @@ const backlog_budget = {
 	UNREADABLE_REASON,
 	WATCH_VERDICT,
 	WHOLE_RUN_BUDGET_HOURS,
-	WHOLE_RUN_BUDGET_MINUTES,
 	WHOLE_RUN_BUDGET_MS,
 	WHOLE_RUN_REASON,
 	decide,

package/scripts/backlog/backlog-defect-priority.ts

@@ -1,6 +1,6 @@
 import type { EpicChild } from '#scripts/epic/epic-graph'
 import type { EpicNextResult, RepoCandidates } from '#scripts/epic/epic-report'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { defect_rate, type DefectRate, type IssueKind } from '#scripts/issue/defect-rate'
 import { defect_rate_cli } from '#scripts/issue/defect-rate-cli'
 
@@ -72,6 +72,6 @@ async function prioritize(
 	return await reorder(result, repo)
 }
 
-const backlog_defect_priority = { UNMEASURED_MESSAGE, KIND_RANK, prioritize }
+const backlog_defect_priority = { UNMEASURED_MESSAGE, prioritize }
 
 export { backlog_defect_priority }

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

@@ -5,13 +5,13 @@ import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-thresho
 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'
+import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
 import { lane_registry } from '#scripts/lane/lane-registry'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 import { run_carry, type RunCarry } from '#scripts/run/run-carry'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
-import { run_merge_cli } from '#scripts/run/run-merge-cli'
+import { run_merge_cli, type MergeResult } from '#scripts/run/run-merge-cli'
 import { z } from 'zod'
 import {
 	backlog_drive,
@@ -28,6 +28,7 @@ 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'
+import { backlog_ready } from './backlog-ready'
 
 // `josh backlog:drive` — the backlogrun parent's loop as one resident wait (joshuafolkken/kit#2499).
 // The parent issues it once, in the background, and is woken only when it exits — with a token the model
@@ -217,7 +218,7 @@ function merge_token(out: string, code: number): string {
 
 // The child's transcript, where its lane recorded one, so `run:merge` can tell an API outage from a
 // failure exactly as it does for the parent that passes `--output` by hand.
-async function merge(issue: string, owner: string): Promise<string> {
+async function merge(issue: string, owner: string): Promise<MergeResult> {
 	await backlog_drive_owner.assert_current(owner)
 	const lane = await lane_registry.find_open_lane(issue)
 	const result = await run_merge_cli.merge_child({
@@ -231,13 +232,15 @@ async function merge(issue: string, owner: string): Promise<string> {
 
 	await backlog_drive_named.mark_done(issue, result, owner)
 
-	return result.token
+	return result
 }
 
-async function launch(issue: string, owner: string): Promise<boolean> {
+async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
 	await backlog_drive_owner.assert_current(owner)
 
-	return (await lane_launch_cli.launch_lane({ issue, stash: undefined })) !== undefined
+	const outcome = await lane_launch_cli.launch_lane({ issue, stash: undefined })
+
+	return outcome.kind
 }
 
 // `lane:await`'s re-confirmed check, one state per child. A child already gone when the loop starts —
@@ -304,6 +307,7 @@ function ports_of(
 		merge: async (issue) => await merge(issue, context.owner),
 		offer: async (state) => await read_offer(state, context),
 		launch: async (issue) => await launch(issue, context.owner),
+		free_lanes: backlog_ready.drive_free_lane_count,
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
 			await sleep(milliseconds)
@@ -375,14 +379,12 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const backlog_drive_cli = {
-	USAGE,
 	end_line,
 	finish: backlog_drive_finish.finish,
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse,
 	resume_line,
-	run,
 	to_offer,
 }
 

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -1,6 +1,8 @@
-import { EPIC_LABEL, has_label_name } from '#scripts/git/issue-labels'
+import { EPIC_LABEL, has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import type { IssueState } from '#scripts/issue/issue-state'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import type { RunCarry } from '#scripts/run/run-carry'
+import type { MergeResult } from '#scripts/run/run-merge-cli'
 import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_named } from './backlog-drive-named'
@@ -44,6 +46,15 @@ function budget_offer(
 	}
 }
 
+// The outcome a named issue has already reached without this run dispatching it: closed is merged, and
+// a `needs-decision` park waits on a person, so re-dispatching it only repeats the stop it parked on
+// (joshuafolkken/kit#2965). Either is booked done rather than offered.
+function settled_outcome(state: IssueState): MergeResult['outcome'] | undefined {
+	if (state.state.toUpperCase() === 'CLOSED') return 'merged'
+
+	return has_label_name(state.labels, NEEDS_DECISION_LABEL) ? 'parked' : undefined
+}
+
 async function classify(issue: string, named: OfferRead, owner: string): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
@@ -51,8 +62,10 @@ async function classify(issue: string, named: OfferRead, owner: string): Promise
 		return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
 	}
 
-	if (result.state.state.toUpperCase() === 'CLOSED') {
-		await backlog_drive_named.mark_done(issue, { outcome: 'merged', code: 0, token: 'none' }, owner)
+	const outcome = settled_outcome(result.state)
+
+	if (outcome !== undefined) {
+		await backlog_drive_named.mark_done(issue, { outcome, code: 0, token: 'none' }, owner)
 
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}

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

@@ -1,4 +1,4 @@
-import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { run_carry, type RunCarry } from '#scripts/run/run-carry'
 import type { RunEvent } from '#scripts/run/run-event-stream'
@@ -94,6 +94,7 @@ async function reconcile(
 	for (const issue of completed) {
 		const outcome = parked.has(issue) ? 'parked' : 'merged'
 
+		// eslint-disable-next-line no-await-in-loop -- each mark rewrites the same carry file
 		await mark_done(String(issue), { outcome, code: 0, token: 'none' }, owner)
 	}
 }

package/scripts/backlog/backlog-drive.ts

@@ -16,6 +16,9 @@
 // **Everything it touches is a port**, the pattern `run-wake-loop.ts` set, so the sequencing is pinned
 // without a process, a network or a clock.
 
+import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import type { MergeResult } from '#scripts/run/run-merge-cli'
+
 const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
 // The `run:merge` tokens that end the loop at once: a hand-off, a person's stop, the environment down,
@@ -32,6 +35,7 @@ const IMMEDIATE_TOKENS: ReadonlySet<string> = new Set([
 // and the children still in flight are collected before the loop ends (joshuafolkken/kit#2881).
 const HANDOFF_TOKENS: ReadonlySet<string> = new Set([...IMMEDIATE_TOKENS, STOP_VERDICT])
 const RESUMED_TOKEN = 'resumed'
+const MERGED_OUTCOME = 'merged'
 const WATCH_VERDICT = 'watch'
 // The verdicts the loop acts on without the parent. Any other is handed back as it was printed.
 const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
@@ -41,6 +45,9 @@ const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
 	'wait',
 ])
 const NO_RETRIES = 0
+const NO_FREE_LANES = 0
+const LAUNCHED = 'launched'
+const UNOPENED = 'unopened'
 
 interface OfferRead {
 	verdict: string
@@ -57,7 +64,9 @@ interface OfferRead {
 interface DriveState {
 	// The children this run has in flight — seeded from the open lanes, so a restarted loop resumes them.
 	in_flight: Array<string>
-	// Every child collected, fed back to `backlog:offer` because GitHub closes a merged issue late.
+	// Every child merged, fed back to `backlog:offer` because GitHub closes a merged issue late. A parked
+	// child is left out: its labels classify it, so one a person released is offered again
+	// (joshuafolkken/kit#3041).
 	exclude: Array<string>
 	// When the run last did something, handed to `backlog:budget` as `--active`.
 	active: string
@@ -80,14 +89,20 @@ interface DriveEnd {
 	is_finish?: boolean | undefined
 }
 
+type Collected = Pick<MergeResult, 'token' | 'outcome'>
+
 interface DrivePorts {
 	// Whether a child's process has confirmed-ended — `lane:await`'s re-confirmed check in production.
 	is_finished: (issue: string) => boolean
-	// `run:merge <N>`'s first stdout token.
-	merge: (issue: string) => Promise<string>
+	// `run:merge <N>`'s first stdout token and the outcome it handled the child as.
+	merge: (issue: string) => Promise<Collected>
 	// `backlog:offer`'s answer for the state, or `undefined` when it exited non-zero.
 	offer: (state: DriveState) => Promise<OfferRead | undefined>
-	launch: (issue: string) => Promise<boolean>
+	// Where `lane:launch`'s chain ended — `launched`, `unopened` (no lane taken) or `failed` (one taken).
+	launch: (issue: string) => Promise<LaunchOutcome['kind']>
+	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
+	// open lanes.
+	free_lanes: () => Promise<number>
 	now: () => Date
 }
 
@@ -150,29 +165,40 @@ function merge_stopped(issue: string, state: DriveState): DriveState {
 	}
 }
 
-// The child collected and excluded, and — unless its cut was resumed in place — out of flight.
+// Only a merged child is excluded: `backlog:next` may still read it OPEN. Any other is classified by
+// its labels, so excluding it would hide a child a person released for the rest of the process.
+function excluded(issue: string, outcome: Collected['outcome'], state: DriveState): Array<string> {
+	if (outcome !== MERGED_OUTCOME || state.exclude.includes(issue)) return state.exclude
+
+	return [...state.exclude, issue]
+}
+
+// The child collected, and — unless its cut was resumed in place — out of flight.
 function collected_state(
 	issue: string,
-	token: string,
+	collected: Collected,
 	state: DriveState,
 	active: string,
 ): DriveState {
 	const in_flight =
-		token === RESUMED_TOKEN ? state.in_flight : state.in_flight.filter((item) => item !== issue)
-	const exclude = state.exclude.includes(issue) ? state.exclude : [...state.exclude, issue]
+		collected.token === RESUMED_TOKEN
+			? state.in_flight
+			: state.in_flight.filter((item) => item !== issue)
+	const exclude = excluded(issue, collected.outcome, state)
 
 	return { ...state, in_flight, exclude, active }
 }
 
 // One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
-	const token = await ports.merge(issue)
+	const collected = await ports.merge(issue)
+	const { token } = collected
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
 	if (token === '') return ended('merge', state, undefined, issue)
 	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
-	const next = collected_state(issue, token, state, ports.now().toISOString())
+	const next = collected_state(issue, collected, state, ports.now().toISOString())
 
 	return { kind: 'continue', state: token === STOP_VERDICT ? merge_stopped(issue, next) : next }
 }
@@ -182,6 +208,7 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 	let current = state
 
 	for (const issue of finished) {
+		// eslint-disable-next-line no-await-in-loop -- each collect starts from the state the previous one returned
 		const result = await collect(issue, current, ports)
 
 		if (result.kind === 'end') return { ...result, state: current }
@@ -192,22 +219,55 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 	return { kind: 'continue', state: current }
 }
 
+// A `lane:open` refused with every lane taken is a wait, not a judgement (joshuafolkken/kit#3027): the
+// next offer after a lane frees retries it. A step failing after the lane opened is always handed back —
+// that lane holds the last seat itself, so the free count would read the failure as a full pool.
+async function refused(
+	issue: string,
+	outcome: LaunchOutcome['kind'],
+	state: DriveState,
+	ports: DrivePorts,
+): Promise<PassResult> {
+	if (outcome !== UNOPENED) return ended('launch', state, undefined, issue)
+	if ((await ports.free_lanes()) <= NO_FREE_LANES) return { kind: 'continue', state }
+
+	return ended('launch', state, undefined, issue)
+}
+
+// **No more launches than free lanes** (joshuafolkken/kit#3027). `backlog:offer` lists every ready issue
+// without reading the lanes, so launching all of them overran `JOSH_LANE_LIMIT` until `lane:open` ran
+// out of seats. The free count is read once, before the first launch, because every launch here opens
+// a lane the count would otherwise have to be told about.
+//
+// **Only a launch is activity** (joshuafolkken/kit#3027): a pass that started nothing — every lane taken
+// — keeps `active` where it was, or the once-a-minute offer would restart the idle budget for good.
+function launched(state: DriveState, in_flight: Array<string>, ports: DrivePorts): DriveState {
+	if (in_flight.length === state.in_flight.length) return { ...state, in_flight }
+
+	return { ...state, in_flight, active: ports.now().toISOString() }
+}
+
 async function launch_all(
 	issues: ReadonlyArray<string>,
 	state: DriveState,
 	ports: DrivePorts,
 ): Promise<PassResult> {
 	const in_flight = [...state.in_flight]
+	const free = await ports.free_lanes()
 
-	for (const issue of issues) {
-		const is_launched = await ports.launch(issue)
+	for (const issue of issues.slice(0, free)) {
+		// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
+		const outcome = await ports.launch(issue)
 
-		if (!is_launched) return ended('launch', { ...state, in_flight }, undefined, issue)
+		if (outcome !== LAUNCHED) {
+			// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
+			return await refused(issue, outcome, launched(state, in_flight, ports), ports)
+		}
 
 		in_flight.push(issue)
 	}
 
-	return { kind: 'continue', state: { ...state, in_flight, active: ports.now().toISOString() } }
+	return { kind: 'continue', state: launched(state, in_flight, ports) }
 }
 
 // A watch with nothing in flight is the drain: `run:step` owes the retrospective there, so it is the
@@ -337,7 +397,9 @@ async function run_loop(
 	let step = await loop_step(first, config, ports)
 
 	while (step.kind === 'next') {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await ports.sleep(config.poll_ms)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		step = await loop_step(step.run, config, ports)
 	}
 
@@ -348,10 +410,8 @@ async function run_loop(
 
 const backlog_drive = {
 	HANDOFF_TOKENS,
-	collect,
 	initial_state,
 	merge_stopped,
-	on_verdict,
 	run_loop,
 	run_pass,
 }

package/scripts/backlog/backlog-named.ts

@@ -141,9 +141,6 @@ function epic_item_outcome(
 }
 
 const backlog_named = {
-	BACKLOG_KIND,
-	END_KIND,
-	NAMED_KIND,
 	NOTHING_TO_RUN,
 	after_failure,
 	epic_item_outcome,

package/scripts/backlog/backlog-next.ts

@@ -9,8 +9,9 @@ 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_stale } from '#scripts/epic/epic-solo-stale'
 import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
@@ -294,7 +295,13 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 	if (result.verdict !== 'run') return result
 
 	const { repo } = context
-	const read = await epic_busy.read_repository(repo)
+	const { read, notice } = await epic_solo_stale.release(
+		await epic_busy.read_repository(repo),
+		repo,
+	)
+
+	if (notice !== undefined) console.error(notice)
+
 	const gated = backlog_rank.gate(result, read, repo, standalone_keys(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
@@ -410,23 +417,10 @@ const backlog_next = {
 	RETRY_MESSAGE,
 	READ_FAILURES,
 	VERDICT_TOKENS,
-	tokens_of,
-	warn_epic_gap,
-	warn_gaps,
-	report,
-	combine,
-	views_from,
 	resolve,
 	standalone_keys,
-	is_transport_failure,
-	report_retry,
-	report_triage,
 	context_of,
-	answer_pool,
-	report_none,
-	answer,
 	run,
-	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))