@joshuafolkken/kit 1.1514.0 → 1.2114.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-memory.ts

@@ -0,0 +1,126 @@
+import { machine_capacity, type MachineSample } from '#scripts/gate/machine-capacity'
+import {
+	run_board_machine,
+	type MachineGauges,
+	type MachineMark,
+} from '#scripts/run/board/run-board-machine'
+import type { DrivePorts, DriveState, PassResult } from './backlog-drive'
+
+// Whether the machine has room for one more lane (joshuafolkken/kit#4084). The lane limit counts lanes,
+// not memory, so a lane opened while the machine swapped slowed every gate already running.
+//
+// **The reading is `run:board`'s own** (`run-board-machine.ts`): 🧠 and 💾 are the figures a person
+// sees beside the waiting row, and the thresholds are the gauges' red and yellow.
+//
+// **Stopping is looser than resuming, so a machine near one threshold does not open and stop in turn.**
+// A lane stops being opened when the kernel calls the memory critical, 🧠 turns red or 💾 swaps at a
+// red rate. It resumes only once the kernel reads under critical and 🧠 and 💾 are both back under
+// yellow. The kernel's warning is no hold (joshuafolkken/kit#4199): macOS keeps it long after the
+// pressure passed, so a run held on it never resumed.
+//
+// **The 🧠 resume bar stays at yellow (70%) on measurement** (joshuafolkken/kit#4529). Across the
+// 2026-10-22 run on an 18 GB machine (106 one-minute samples, 24 after the whole-suite and vitest-worker
+// cuts merged) 🧠 never reached 70%, peaking at 67%; every memory hold, 1.3 minutes in all, came with a
+// swap burst. 💾 is what holds a lane, so a lower 🧠 bar would admit nothing sooner and only risk swap.
+//
+// **A figure that could not be read is no limit**, as in the gate's core budget: a machine without
+// `sysctl` dispatches as it did before memory was read.
+
+const { MEMORY_RED, MEMORY_YELLOW, SWAP_RED_MB_PER_S, SWAP_YELLOW_MB_PER_S } = run_board_machine
+const { PRESSURE_HOLD } = machine_capacity
+// Two readings closer than this give no swap rate: a page swapped in a few milliseconds is no rate.
+const MIN_RATE_MS = 1000
+// The `hold` reason a pass held by memory records, read back by `run:board` and `lane:stats`.
+const HOLD_REASON = 'memory'
+
+type MemoryGauges = Pick<MachineGauges, 'memory_percent' | 'swap_mb_per_s' | 'memory_pressure'>
+
+function is_kernel_pressured(gauges: MemoryGauges): boolean {
+	return (gauges.memory_pressure ?? 0) >= PRESSURE_HOLD
+}
+
+function is_stop(gauges: MemoryGauges): boolean {
+	return (
+		is_kernel_pressured(gauges) ||
+		(gauges.memory_percent ?? 0) >= MEMORY_RED ||
+		(gauges.swap_mb_per_s ?? 0) >= SWAP_RED_MB_PER_S
+	)
+}
+
+function is_resume(gauges: MemoryGauges): boolean {
+	return (
+		!is_kernel_pressured(gauges) &&
+		(gauges.memory_percent ?? 0) < MEMORY_YELLOW &&
+		(gauges.swap_mb_per_s ?? 0) < SWAP_YELLOW_MB_PER_S
+	)
+}
+
+interface GaugePorts {
+	read: () => Promise<MachineSample>
+	now: () => number
+}
+
+const PRODUCTION: GaugePorts = { read: machine_capacity.read_sample, now: Date.now }
+
+// What one gauge carries between calls.
+interface GaugeMemo {
+	last: MachineMark | undefined
+	// The last swap rate measured, kept for a reading too close to the last to measure its own.
+	swap_mb_per_s: number | undefined
+	is_held: boolean
+}
+
+// The reading's gauges, the rate measured from the last reading at least `MIN_RATE_MS` old; the last
+// moves on only then, so two close calls keep measuring from the same one. A reading too close to
+// measure keeps the last rate measured, so a held machine still swapping does not read 0 and resume.
+function is_rate_of(last: MachineMark | undefined, mark: MachineMark): last is MachineMark {
+	return last !== undefined && mark.at_ms - last.at_ms >= MIN_RATE_MS
+}
+
+function rated(memo: GaugeMemo, mark: MachineMark): MemoryGauges {
+	const { last } = memo
+	const is_rated = is_rate_of(last, mark)
+
+	if (last === undefined || is_rated) memo.last = mark
+
+	const gauges = run_board_machine.gauges_of(is_rated ? last : undefined, mark)
+
+	if (is_rated) memo.swap_mb_per_s = gauges.swap_mb_per_s
+
+	return { ...gauges, swap_mb_per_s: memo.swap_mb_per_s }
+}
+
+// The production `memory_held` port: each call reads the machine once, and the hold is carried
+// between calls — a held machine waits for the resume, a free one for the stop.
+function gauge(ports: GaugePorts = PRODUCTION): () => Promise<boolean> {
+	const memo: GaugeMemo = { last: undefined, swap_mb_per_s: undefined, is_held: false }
+
+	return async function memory_held(): Promise<boolean> {
+		const gauges = rated(memo, { sample: await ports.read(), at_ms: ports.now() })
+
+		memo.is_held = memo.is_held ? !is_resume(gauges) : is_stop(gauges)
+
+		return memo.is_held
+	}
+}
+
+// An offer that answered `run` on a machine with no room: nothing launches, the pass records why, and
+// the loop polls the memory until it clears.
+async function held(state: DriveState, ports: Pick<DrivePorts, 'hold'>): Promise<PassResult> {
+	await ports.hold(HOLD_REASON)
+
+	return { kind: 'continue', state: { ...state, is_memory_held: true } }
+}
+
+// Whether a held run's memory cleared since: the pass asks the offer again, not waiting out its interval.
+async function is_cleared(
+	state: DriveState,
+	ports: Pick<DrivePorts, 'memory_held'>,
+): Promise<boolean> {
+	return state.is_memory_held === true && !(await ports.memory_held())
+}
+
+const backlog_drive_memory = { HOLD_REASON, gauge, held, is_cleared }
+
+export { backlog_drive_memory }
+export type { MemoryGauges }

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

@@ -1,16 +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, NEEDS_DECISION_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 { run_carry_added } from '#scripts/run/carry/run-carry-added'
-import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
-import { run_invocation } from '#scripts/run/run-invocation'
 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
@@ -51,13 +57,11 @@ 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.
+// 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 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
+function is_settled(state: IssueState): boolean {
+	return state.state.toUpperCase() === 'CLOSED' || has_parked_label(state.labels)
 }
 
 async function classify(
@@ -70,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 }
 	}
@@ -90,26 +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>> {
-	const declared = run_carry_added.ordered(
-		run_invocation.issue_numbers(carry.invocation) ?? [],
-		carry.added,
-	)
+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
@@ -119,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(
@@ -131,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

@@ -1,5 +1,6 @@
 import { lane_parked } from '#scripts/lane/lane-parked'
 import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_added } from '#scripts/run/carry/run-carry-added'
 import type { RunEvent } from '#scripts/run/event/run-event-stream'
 import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { run_merge_token } from '#scripts/run/merge/run-merge-token'
@@ -23,18 +24,46 @@ function is_declared(carry: RunCarry, issue: string): boolean {
 // An issue `run:add` put in that is already in flight holds nothing up: it was
 // asked for on its own, so the declared item behind it — an epic whose children fill the free lanes —
 // is offered beside it. A declared issue in flight still holds the ones declared after it.
-function is_held(carry: RunCarry, state: DriveState, issue: number): boolean {
-	return !state.in_flight.includes(String(issue)) || is_declared(carry, String(issue))
+function is_held(carry: RunCarry, in_flight: ReadonlyArray<string>, issue: number): boolean {
+	return !in_flight.includes(String(issue)) || is_declared(carry, String(issue))
 }
 
-function next_of(carry: RunCarry, state: DriveState): number | undefined {
+function next_of(carry: RunCarry, in_flight: ReadonlyArray<string>): number | undefined {
 	const remaining = run_carry.remaining_of(carry) ?? []
 
-	return remaining.find((issue) => is_held(carry, state, issue)) ?? remaining[FIRST]
+	return remaining.find((issue) => is_held(carry, in_flight, issue)) ?? remaining[FIRST]
+}
+
+// The declared issue `issue` starts after while the declared order holds it: the one declared just
+// before it, once it is behind `next_of` — what `offer` runs or waits on — whether that has started yet
+// or not (joshuafolkken/kit#4279). `run:board` names it on the queued row; an issue `run:add` put in, or
+// one already in flight, is held by nothing.
+function held_after(
+	carry: RunCarry,
+	in_flight: ReadonlyArray<string>,
+	issue: number,
+): number | undefined {
+	const next = next_of(carry, in_flight)
+	if (next === undefined || in_flight.includes(String(issue))) return undefined
+	const declared = (run_carry.remaining_of(carry) ?? []).filter((number) =>
+		is_declared(carry, String(number)),
+	)
+	const index = declared.indexOf(issue)
+
+	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)
+	const next = next_of(carry, state.in_flight)
 
 	if (next !== undefined) {
 		const issue = String(next)
@@ -44,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 {
@@ -101,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>,
@@ -129,4 +169,32 @@ async function reconcile(
 	}
 }
 
-export const backlog_drive_named = { offer, mark_done, reconcile }
+// The issues the run names: the declared list in its order, with the ones `run:add` put in.
+function named_issues(carry: RunCarry): ReadonlyArray<number> {
+	return run_carry_added.ordered(run_invocation.issue_numbers(carry.invocation) ?? [], carry.added)
+}
+
+// **A `--only` run adopts only the carried lanes it names** (joshuafolkken/kit#4282): it drains
+// nothing, and its stop waits for every lane in flight, so a lane an earlier invocation dispatched for
+// another issue would hold the run's end until that issue settled. The next draining run collects it.
+function own_carried(
+	carry: RunCarry,
+	dispatched: ReadonlyArray<string>,
+	is_only: boolean,
+): ReadonlyArray<string> {
+	if (!is_only) return dispatched
+	const named = named_issues(carry)
+
+	return dispatched.filter((issue) => named.includes(Number(issue)))
+}
+
+export const backlog_drive_named = {
+	next_of,
+	offer,
+	held_after,
+	mark_done,
+	mark_settled,
+	named_issues,
+	own_carried,
+	reconcile,
+}

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

@@ -1,21 +1,16 @@
 import type { RunCarry } from '#scripts/run/carry/run-carry'
 import type { DriveState } from './backlog-drive'
-
-const LIST_SEPARATOR = ','
+import { backlog_offer_exclude } from './backlog-offer-exclude'
 
 // **A child in flight is never offered**. A lane child merges its own PR and
 // drops `in-progress` before GitHub closes the issue and before the loop collects it, so `backlog:next`
 // can offer it again; launching it then is refused by its still-open lane and handed to an AI session.
-function excluded(state: DriveState): ReadonlyArray<string> {
-	return [...new Set([...state.exclude, ...state.in_flight])]
-}
-
 function offer_argv(
 	state: DriveState,
 	carry: RunCarry,
 	forwarded: ReadonlyArray<string>,
 ): ReadonlyArray<string> {
-	const exclude = excluded(state)
+	const exclude = backlog_offer_exclude.exclude_of(state.exclude, state.in_flight)
 
 	return [
 		'backlog:offer',
@@ -30,7 +25,7 @@ function offer_argv(
 		String(state.in_flight.length),
 		'--retries',
 		String(state.retries),
-		...(exclude.length === 0 ? [] : ['--exclude', exclude.join(LIST_SEPARATOR)]),
+		...backlog_offer_exclude.exclude_argv(exclude),
 		...forwarded,
 	]
 }