@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/backlog/backlog-drive-launch-pass.ts

@@ -0,0 +1,90 @@
+import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import type { DrivePorts, DriveState, PassResult } from './backlog-drive'
+import { backlog_drive_seats } from './backlog-drive-seats'
+
+// The launches of one offered pass, out of `backlog-drive.ts` so the loop stays within its size.
+
+const NO_FREE_LANES = 0
+const LAUNCHED = 'launched'
+const UNOPENED = 'unopened'
+// The launch port's answer for an issue its measurement declaration closed (`backlog-measure-close.ts`).
+const MEASURED_LAUNCH = 'measured' as const
+
+type DriveLaunch = LaunchOutcome['kind'] | typeof MEASURED_LAUNCH
+
+interface Settled {
+	in_flight: Array<string>
+	measured: Array<string>
+}
+
+function handed_back(issue: string, state: DriveState): PassResult {
+	return { kind: 'end', end: { reason: 'launch', token: undefined, issue }, state }
+}
+
+// A `lane:open` refused with every lane taken is a wait, not a judgement: 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: DriveLaunch,
+	state: DriveState,
+	ports: DrivePorts,
+): Promise<PassResult> {
+	if (outcome !== UNOPENED) return handed_back(issue, state)
+	if ((await ports.free_lanes()) <= NO_FREE_LANES) return { kind: 'continue', state }
+
+	return handed_back(issue, state)
+}
+
+// **Only a launch or a measured close is activity**: 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. A
+// measured issue is closed but may still read OPEN to `backlog:next`, so it is excluded as a merge is.
+function launched(state: DriveState, settled: Settled, ports: DrivePorts): DriveState {
+	const { in_flight, measured } = settled
+
+	if (in_flight.length === state.in_flight.length && measured.length === 0) {
+		return { ...state, in_flight }
+	}
+
+	const exclude = [...state.exclude, ...measured]
+
+	return { ...state, in_flight, exclude, active: ports.now().toISOString() }
+}
+
+// Whether the launch settled the issue — into flight, or closed by its measurement.
+function is_settled(settled: Settled, issue: string, outcome: DriveLaunch): boolean {
+	if (outcome === MEASURED_LAUNCH) settled.measured.push(issue)
+	if (outcome === LAUNCHED) settled.in_flight.push(issue)
+
+	return outcome === MEASURED_LAUNCH || outcome === LAUNCHED
+}
+
+// **No more new lanes than free lanes**. `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. An issue
+// that already holds a kept lane reuses its port seat but takes a place under the limit, ahead of a
+// fresh launch; the rest launch up to the free count (`backlog-drive-seats.ts`), read before the first.
+async function launch_all(
+	issues: ReadonlyArray<string>,
+	state: DriveState,
+	ports: DrivePorts,
+): Promise<PassResult> {
+	const settled: Settled = { in_flight: [...state.in_flight], measured: [] }
+	const launching = await backlog_drive_seats.seated(issues, ports)
+
+	for (const issue of launching) {
+		// 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_settled(settled, issue, outcome)) {
+			// 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, settled, ports), ports)
+		}
+	}
+
+	return { kind: 'continue', state: launched(state, settled, ports) }
+}
+
+const backlog_drive_launch_pass = { MEASURED_LAUNCH, launch_all }
+
+export type { DriveLaunch }
+export { backlog_drive_launch_pass }

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

@@ -1,7 +1,11 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
-import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import { lane_launch_cli } from '#scripts/lane/lane-launch-cli'
 import { run_event_setup } from '#scripts/run/event/run-event-setup'
+import { backlog_drive_launch_pass, type DriveLaunch } from './backlog-drive-launch-pass'
 import { backlog_drive_owner } from './backlog-drive-owner'
+import { backlog_measure_close } from './backlog-measure-close'
+
+const { MEASURED_LAUNCH } = backlog_drive_launch_pass
 
 // The driver's lane launch. The parent that ran `josh latest` in the primary
 // checkout leaves its rewritten lock file in a stash under this message — `backlogrun-lanes.md` →
@@ -27,8 +31,10 @@ async function latest_stash(): Promise<string | undefined> {
 	return selection.kind === 'match' ? LATEST_STASH_MESSAGE : undefined
 }
 
-async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
+// An issue its measurement declaration closed takes no lane (`backlog-measure-close.ts`).
+async function launch(issue: string, owner: string): Promise<DriveLaunch> {
 	await backlog_drive_owner.assert_current(owner)
+	if (await backlog_measure_close.closed(issue)) return MEASURED_LAUNCH
 	await run_event_setup.emit(run_event_setup.opening_lane(issue))
 
 	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })

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

@@ -1,14 +1,22 @@
+import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { EPIC_LABEL, has_label_name, has_parked_label } from '#scripts/issue/issue-labels'
+import {
+	EPIC_LABEL,
+	has_label_name,
+	has_parked_label,
+	parked_label_of,
+} from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_plan } from '#scripts/lane/lane-plan'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
-import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_epic } from './backlog-drive-epic'
 import { backlog_drive_named } from './backlog-drive-named'
 import { backlog_drive_unread } from './backlog-drive-unread'
+import type { Declared } from './backlog-overlap'
+import { backlog_plan_comment } from './backlog-plan-comment'
 
 interface NamedContext {
 	is_only: boolean
@@ -49,13 +57,11 @@ function budget_offer(
 	}
 }
 
-// The outcome a named issue has already reached without this run dispatching it: closed is merged, and
-// a park (`PARKED_LABELS`) waits on a person, so re-dispatching it only repeats the stop it parked on.
-// Either is booked done rather than offered — the same reading `run:merge` gives a parked child.
-function settled_outcome(state: IssueState): MergeResult['outcome'] | undefined {
-	if (state.state.toUpperCase() === 'CLOSED') return 'merged'
-
-	return has_parked_label(state.labels) ? 'parked' : undefined
+// Whether a named issue has already settled without this run dispatching it: closed is merged, and a
+// park (`PARKED_LABELS`) waits on a person, so re-dispatching it only repeats the stop it parked on.
+// Either is booked done rather than offered.
+function is_settled(state: IssueState): boolean {
+	return state.state.toUpperCase() === 'CLOSED' || has_parked_label(state.labels)
 }
 
 async function classify(
@@ -68,14 +74,8 @@ async function classify(
 
 	if (result.kind !== 'state') return backlog_drive_unread.offer(issue, result, state.retries)
 
-	const outcome = settled_outcome(result.state)
-
-	if (outcome !== undefined) {
-		await backlog_drive_named.mark_done(
-			issue,
-			{ outcome, code: 0, token: 'none', is_offer: true },
-			owner,
-		)
+	if (is_settled(result.state)) {
+		await backlog_drive_named.mark_settled(issue, owner)
 
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}
@@ -88,23 +88,37 @@ async function classify(
 // **A named issue booked done is not thereby merged**: a park and a failure are
 // booked done too, so the run moves past them. One the run's own merges did not record and GitHub does
 // not read as closed ended without a merge — and an unreadable state counts as that, because a false
-// stop reaches a person while a false finish ends the run where nobody sees it.
-async function is_unmerged(issue: number, merged: ReadonlyArray<number>): Promise<boolean> {
-	if (merged.includes(issue)) return false
+// stop reaches a person while a false finish ends the run where nobody sees it. The answer is why it
+// did not merge (joshuafolkken/kit#4746): the park it sits on, or that it is open without one.
+async function unmerged_reason(
+	issue: number,
+	merged: ReadonlyArray<number>,
+): Promise<string | undefined> {
+	if (merged.includes(issue)) return undefined
 
 	const result = await issue_state_cli.read_issue(String(issue))
 
-	return result.kind !== 'state' || result.state.state.toUpperCase() !== 'CLOSED'
+	if (result.kind !== 'state') return 'state unreadable'
+	if (result.state.state.toUpperCase() === 'CLOSED') return undefined
+
+	return parked_label_of(result.state.labels) ?? 'open'
 }
 
-// The issues `run:add` put in count too: one that parked is no more a merge
-// than a declared one.
-async function unmerged_of(carry: RunCarry): Promise<Array<number>> {
+function cite(issue: number, reason: string | undefined): string | undefined {
+	return reason === undefined ? undefined : `${issue_cite.plain(issue)} (${reason})`
+}
+
+// Each named issue that did not merge, with its reason. The issues `run:add` put in count too: one that
+// parked is no more a merge than a declared one.
+async function unmerged_of(carry: RunCarry): Promise<Array<string>> {
 	const declared = backlog_drive_named.named_issues(carry)
 	const merged = carry.merged_issues ?? []
-	const flags = await Promise.all(declared.map(async (issue) => await is_unmerged(issue, merged)))
+	const reasons = await Promise.all(
+		declared.map(async (issue) => await unmerged_reason(issue, merged)),
+	)
+	const cited = declared.map((issue, index) => cite(issue, reasons[index]))
 
-	return declared.filter((_, index) => flags[index] === true)
+	return cited.filter((line) => line !== undefined)
 }
 
 // The `--only` run's end: a finish when every named issue merged, otherwise a stop naming the ones that
@@ -114,9 +128,11 @@ async function only_end(carry: RunCarry, named: OfferRead): Promise<OfferRead> {
 
 	if (unmerged.length === 0) return named
 
-	const listed = unmerged.map((issue) => issue_cite.plain(issue)).join(', ')
-
-	return { ...named, reason: `only: ${listed} ended without a merge`, is_finish: false }
+	return {
+		...named,
+		reason: `only: ${unmerged.join(', ')} ended without a merge`,
+		is_finish: false,
+	}
 }
 
 async function not_run(
@@ -126,12 +142,39 @@ async function not_run(
 	return named?.is_finish === true ? await only_end(carry, named) : named
 }
 
+// What the lanes in flight declare — recorded plan, else plan comment, else body, the scope `lane:plan` and
+// `backlog:next` read. A lane the listing does not carry, or an unread listing, declares its plan alone.
+async function in_flight_declared(in_flight: ReadonlyArray<string>): Promise<Declared> {
+	const listing = await auto_ok_cli.fetch_opted_in()
+	const listed = listing.kind === 'read' ? listing.issues : []
+	const pool = in_flight
+		.map(Number)
+		.map((number) => listed.find((issue) => issue.number === number) ?? { number })
+
+	return await backlog_plan_comment.declared_of(pool, process.cwd())
+}
+
+// The issues in flight, with each named one whose yielded plan a running lane still holds: the offer
+// waits on it as on a lane, so the run does not relaunch it into the same yield (joshuafolkken/kit#4926).
+// The listing is read only when a named issue yielded and a lane runs.
+async function holding(carry: RunCarry, in_flight: ReadonlyArray<string>): Promise<Array<string>> {
+	const yielded = backlog_drive_named
+		.named_issues(carry)
+		.filter((issue) => lane_plan.is_yielded(issue, process.cwd()))
+	if (yielded.length === 0 || in_flight.length === 0) return [...in_flight]
+	const declared = await in_flight_declared(in_flight)
+	const held = yielded.filter((issue) => lane_plan.is_yield_held(issue, declared, process.cwd()))
+
+	return [...new Set([...in_flight, ...held.map(String)])]
+}
+
 async function read(
 	carry: RunCarry,
 	state: DriveState,
 	context: NamedContext,
 ): Promise<OfferRead | undefined> {
-	const named = backlog_drive_named.offer(carry, state, context.is_only)
+	const waiting = { ...state, in_flight: await holding(carry, state.in_flight) }
+	const named = backlog_drive_named.offer(carry, waiting, context.is_only)
 	if (named?.verdict !== 'run') return await not_run(carry, named)
 	const budget = budget_offer(carry, state, context.forwarded)
 	if (budget.verdict !== 'run') return budget

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

@@ -53,6 +53,15 @@ function held_after(
 	return index > declared.indexOf(next) ? declared[index - 1] : undefined
 }
 
+// **An `--only` run ends once nothing it named is left and nothing is in flight**
+// (joshuafolkken/kit#4746): the stop's reason is read when it is offered, so one offered while a lane
+// still ran would name that lane's issue unmerged even after it merged.
+function only_end(state: DriveState): OfferRead {
+	return state.in_flight.length > 0
+		? { verdict: 'wait', issues: [], retries: NO_RETRIES }
+		: { verdict: 'stop', issues: [], retries: NO_RETRIES, reason: 'only', is_finish: true }
+}
+
 function offer(carry: RunCarry, state: DriveState, is_only: boolean): OfferRead | undefined {
 	const next = next_of(carry, state.in_flight)
 
@@ -64,9 +73,7 @@ function offer(carry: RunCarry, state: DriveState, is_only: boolean): OfferRead
 			: { verdict: 'run', issues: [issue], retries: NO_RETRIES }
 	}
 
-	return is_only
-		? { verdict: 'stop', issues: [], retries: NO_RETRIES, reason: 'only', is_finish: true }
-		: undefined
+	return is_only ? only_end(state) : undefined
 }
 
 function is_done(result: MergeResult): boolean {
@@ -121,15 +128,28 @@ async function should_skip(issue: string, outcome: MergeResult['outcome']): Prom
 	return await lane_parked.is_parked(issue)
 }
 
+async function carry_target(): Promise<string | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	return directory === undefined ? undefined : run_carry.carry_path(directory)
+}
+
 async function mark_done(issue: string, result: MergeResult, owner: string): Promise<void> {
 	if (!is_done(result)) return
-	const directory = await run_carry.repository_directory()
-	if (directory === undefined) return
-	const target = run_carry.carry_path(directory)
-	if (!mark_one(target, issue, owner)) return
+	const target = await carry_target()
+	if (target === undefined || !mark_one(target, issue, owner)) return
 	if (await should_skip(issue, result.outcome)) skip_after_failure(target, issue, owner)
 }
 
+// **A named issue settled before this run dispatched it skips nothing** (joshuafolkken/kit#4746): it
+// did not fail inside the run, so booking the ones declared after it done would end an `--only` run
+// over issues no lane ever started.
+async function mark_settled(issue: string, owner: string): Promise<void> {
+	const target = await carry_target()
+
+	if (target !== undefined) mark_one(target, issue, owner)
+}
+
 async function reconcile(
 	carry: RunCarry,
 	events: ReadonlyArray<RunEvent>,
@@ -173,6 +193,7 @@ export const backlog_drive_named = {
 	offer,
 	held_after,
 	mark_done,
+	mark_settled,
 	named_issues,
 	own_carried,
 	reconcile,

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

@@ -11,6 +11,7 @@ import { DEFAULT_SILENT_MINUTES } from '#scripts/run/run-liveness'
 import type { DrivePorts, OfferRead, PassResult } from './backlog-drive'
 import { backlog_drive_idle } from './backlog-drive-idle'
 import { backlog_overlap } from './backlog-overlap'
+import { backlog_plan_comment } from './backlog-plan-comment'
 
 // A run held only by paused lanes (joshuafolkken/kit#4270): nothing of this run in flight, nothing
 // dispatched, and a lane a person paused past the silent window `run:liveness` waits out declares a
@@ -85,12 +86,12 @@ function waiting_of(
 }
 
 /** The `paused` records whose declared paths a waiting candidate overlaps. */
-function holding(
+async function holding(
 	paused: ReadonlyArray<LaneStateRecord>,
 	issues: ReadonlyArray<OpenIssueData>,
 	records: ReadonlyArray<LaneStateRecord>,
-): Array<LaneStateRecord> {
-	const declared = backlog_overlap.declared_of(issues)
+): Promise<Array<LaneStateRecord>> {
+	const declared = await backlog_plan_comment.declared_of(issues, process.cwd())
 	const waiting = waiting_of(issues, records)
 
 	return paused.filter((record) =>
@@ -106,7 +107,7 @@ async function held_by(ports: PausedPorts): Promise<Array<LaneStateRecord>> {
 
 	const issues = await ports.read_issues()
 
-	return issues === undefined ? [] : holding(paused, issues, records)
+	return issues === undefined ? [] : await holding(paused, issues, records)
 }
 
 function describe(records: ReadonlyArray<LaneStateRecord>): string {

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

@@ -1,3 +1,4 @@
+import { lane_yield } from '#scripts/lane/lane-yield'
 import { run_event_scope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 import { backlog_offer_exclude } from './backlog-offer-exclude'
@@ -9,6 +10,7 @@ const SETTLED_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.SPLIT,
 	run_event_stream.EVENT_KIND.WITHDRAW,
 	run_event_stream.EVENT_KIND.OUTAGE,
+	run_event_stream.EVENT_KIND.USAGE_LIMIT,
 ])
 const DONE_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.MERGE,
@@ -37,8 +39,11 @@ function active_issues(events: ReadonlyArray<RunEvent>): ReadonlySet<string> {
 	return active
 }
 
+// A yield is not among them: it gave its lane back without settling the issue (`lane-yield.ts`).
 function settled_issues(events: ReadonlyArray<RunEvent>): ReadonlySet<number> {
-	const settled = events.filter((event) => DONE_KINDS.has(event.kind))
+	const settled = events.filter(
+		(event) => DONE_KINDS.has(event.kind) && !lane_yield.is_yield(event),
+	)
 
 	return new Set(
 		settled
@@ -56,11 +61,14 @@ function issues_of_kind(events: ReadonlyArray<RunEvent>, kind: string): Readonly
 }
 
 // The issues a person withdrew from this run and nobody launched again: the withdrawal leaves the issue
-// open for the next run, so this one keeps it out of the offer (joshuafolkken/kit#4365).
+// open for the next run, so this one keeps it out of the offer (joshuafolkken/kit#4365). A lane that
+// yielded stays in the run: its retained plan holds it back until the holder ends (`lane-yield.ts`).
 function withdrawn_issues(events: ReadonlyArray<RunEvent>): ReadonlyArray<string> {
 	const named = issues_of_kind(events, run_event_stream.EVENT_KIND.WITHDRAW)
 
-	return named.filter((issue) => run_event_scope.is_withdrawn(events, issue))
+	return named.filter(
+		(issue) => run_event_scope.is_withdrawn(events, issue) && !lane_yield.is_yielded(events, issue),
+	)
 }
 
 // The offer's exclusion as the stream records it: the merged and withdrawn children and the ones still

package/scripts/backlog/backlog-drive.ts

@@ -17,16 +17,15 @@
 // without a process, a network or a clock.
 
 import { issue_cite } from '#scripts/issue/issue-cite'
-import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
 import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { run_merge_token } from '#scripts/run/merge/run-merge-token'
 import { backlog_drive_adopt } from './backlog-drive-adopt'
 import { backlog_drive_hold, type HeldWaiting } from './backlog-drive-hold'
 import { backlog_drive_idle } from './backlog-drive-idle'
 import { backlog_drive_judge } from './backlog-drive-judge'
+import { backlog_drive_launch_pass, type DriveLaunch } from './backlog-drive-launch-pass'
 import { backlog_drive_memory } from './backlog-drive-memory'
 import { backlog_drive_paused } from './backlog-drive-paused'
-import { backlog_drive_seats } from './backlog-drive-seats'
 import { backlog_drive_token_handling } from './backlog-drive-token-handling'
 
 const { MERGE_TOKEN } = run_merge_token
@@ -44,11 +43,11 @@ const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
 	'wait',
 ])
 const NO_RETRIES = 0
-const NO_FREE_LANES = 0
 const EXHAUSTED_ANSWER = 'exhausted'
 const JUDGE_REASON = 'judge'
-const LAUNCHED = 'launched'
-const UNOPENED = 'unopened'
+// The `hold` reason a pass held by a Claude usage limit records.
+const USAGE_LIMIT_REASON = 'usage-limit'
+const { launch_all } = backlog_drive_launch_pass
 
 interface OfferRead extends HeldWaiting {
 	verdict: string
@@ -106,8 +105,9 @@ interface DrivePorts {
 	adoptable: (in_flight: ReadonlyArray<string>) => Promise<ReadonlyArray<string>>
 	// `backlog:offer`'s answer for the state, or `undefined` when it exited non-zero.
 	offer: (state: DriveState) => Promise<OfferRead | undefined>
-	// Where `lane:launch`'s chain ended — `launched`, `unopened` (no lane taken) or `failed` (one taken).
-	launch: (issue: string) => Promise<LaunchOutcome['kind']>
+	// Where `lane:launch`'s chain ended — `launched`, `unopened` (no lane taken) or `failed` (one taken) —
+	// or `measured`, the issue closed by its declaration with no lane taken.
+	launch: (issue: string) => Promise<DriveLaunch>
 	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
 	// open lanes.
 	free_lanes: () => Promise<number>
@@ -122,6 +122,9 @@ interface DrivePorts {
 	// Whether the machine has no memory for one more lane — `backlog_drive_memory.gauge()` in production,
 	// which carries its hysteresis between calls.
 	memory_held: () => Promise<boolean>
+	// Whether a Claude usage limit that stopped a child has yet to reset — `run_merge_usage_limit.is_held`
+	// in production (joshuafolkken/kit#4745).
+	usage_limited: () => Promise<boolean>
 	// Why an offered pass started nothing (`backlog-drive-hold.ts`). Production records it in the lane
 	// ledger only while a lane is free. `undefined` is the run's stop, which owes no lane a child.
 	hold: (reason: string | undefined, waiting?: ReadonlyArray<number>) => Promise<void>
@@ -250,58 +253,6 @@ 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: 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 new lanes than free lanes**. `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. An issue
-// that already holds a kept lane reuses its port seat but takes a place under the limit, ahead of a
-// fresh launch; the rest launch up to the free count (`backlog-drive-seats.ts`), read before the first.
-//
-// **Only a launch is activity**: 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 launching = await backlog_drive_seats.seated(issues, ports)
-
-	for (const issue of launching) {
-		// 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 (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: launched(state, in_flight, ports) }
-}
-
 // A watch with nothing in flight is the drain: `run:step` owes the retrospective there, so it is the
 // parent's. With children still running the watch is only waiting on them.
 function on_verdict(read: OfferRead, state: DriveState): PassResult {
@@ -328,12 +279,21 @@ function on_verdict(read: OfferRead, state: DriveState): PassResult {
 	return { kind: 'continue', state }
 }
 
-// An offer answered `run`: launched while the machine has memory to spare, held until it does otherwise.
+async function usage_held(state: DriveState, ports: DrivePorts): Promise<PassResult> {
+	await ports.hold(USAGE_LIMIT_REASON)
+
+	return { kind: 'continue', state }
+}
+
+// An offer answered `run`: launched while the machine has memory to spare and no usage limit is in
+// force, held until both hold otherwise. A usage-limited pass polls on as a held one does.
 async function run_offered(
 	issues: ReadonlyArray<string>,
 	state: DriveState,
 	ports: DrivePorts,
 ): Promise<PassResult> {
+	if (await ports.usage_limited()) return await usage_held(state, ports)
+
 	if (await ports.memory_held()) return await backlog_drive_memory.held(state, ports)
 
 	return await launch_all(issues, state, ports)
@@ -464,6 +424,7 @@ async function run_loop(
 const backlog_drive = {
 	HANDOFF_TOKENS,
 	TOKEN_HANDLING,
+	USAGE_LIMIT_REASON,
 	initial_state,
 	merge_stopped,
 	run_loop,

package/scripts/backlog/backlog-gate-scope.ts

@@ -0,0 +1,61 @@
+import type { OptedInRead, TrackingRead } from '#scripts/auto-ok/auto-ok-cli'
+import { epic_graph } from '#scripts/epic/epic-graph'
+import { epic_index } from '#scripts/epic/epic-index'
+import { lane_plan } from '#scripts/lane/lane-plan'
+import { lane_state } from '#scripts/lane/lane-state'
+import { backlog_plan_comment } from './backlog-plan-comment'
+import { backlog_pool } from './backlog-pool'
+import type { GateScope } from './backlog-rank'
+
+type OptedIn = Extract<OptedInRead, { kind: 'read' }>
+type Tracking = Extract<TrackingRead, { kind: 'read' }>
+
+// Everything the answer is assembled from, read once and passed down rather than re-fetched.
+interface PoolContext {
+	opted_in: OptedIn
+	tracking: Tracking
+	repo: string
+	exclude: ReadonlyArray<number>
+}
+
+// The rows the offer's cap bounds — the standalone half.
+function standalone_keys(context: PoolContext): ReadonlySet<string> {
+	return backlog_pool.standalone_keys(context.opted_in.issues, {
+		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
+		exclude: context.exclude,
+		repo: context.repo,
+	})
+}
+
+// The issues whose lane yielded on a plan it kept (`lane-yield.ts`) — offered first (`backlog-rank.ts`,
+// joshuafolkken/kit#5107).
+function yielded_keys(context: PoolContext, directory: string): ReadonlySet<string> {
+	const yielded = context.opted_in.issues.filter((issue) =>
+		lane_plan.is_yielded(issue.number, directory),
+	)
+
+	return new Set(yielded.map(({ number }) => epic_graph.key_of({ number, repo: context.repo })))
+}
+
+// The running lanes still carry the pickup label, so the opted-in listing holds their bodies too —
+// which is what lets a candidate be held back from a path a running lane already declares.
+// `backlog:plan --waves` reads the same scope, so its first wave is this offer. Their lane state
+// records name a paused holder in the wait it causes (joshuafolkken/kit#4270); they are local files.
+// A lane's recorded plan (joshuafolkken/kit#4864), else a plan comment (joshuafolkken/kit#4923), is
+// read in place of the body (joshuafolkken/kit#4937).
+async function gate_scope(context: PoolContext): Promise<GateScope> {
+	const { issues } = context.opted_in
+	const directory = process.cwd()
+
+	return {
+		standalone: standalone_keys(context),
+		declared: await backlog_plan_comment.declared_of(issues, directory),
+		lanes: await lane_state.read_states(issues.map((issue) => String(issue.number))),
+		yielded: yielded_keys(context, directory),
+	}
+}
+
+const backlog_gate_scope = { gate_scope }
+
+export { backlog_gate_scope }
+export type { OptedIn, PoolContext }