@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -0,0 +1,162 @@
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import type { DriveEnd, DrivePorts, DriveState, OfferRead, PassResult } from './backlog-drive'
+import { backlog_ready } from './backlog-ready'
+
+// Why a free lane stayed empty, written where `josh lane:stats` reads it (joshuafolkken/kit#3995).
+//
+// **The driver already dispatches the moment a lane frees**: a pass that collected a child asks the
+// offer at once (`backlog-drive.ts` → `is_offering`). What a backlog stall episode could not say is
+// why a free lane then stayed empty — an offer that started nothing, or the driver handed back to a
+// session that had not restarted it yet. Each such pass records its reason; the time is derived in
+// `lane-held-stats.ts`, so a hold is told apart from a dispatch that was simply slow.
+//
+// **Only a free lane is a hold.** Every lane taken is the limit doing its job, not idle capacity, and a
+// finished run — a `stop`, the drain's `watch` or `retrospective` — owes no lane a child. Either writes
+// a `released` entry instead, which ends the hold before it: a lane opened outside this driver can
+// fill the pool, and no dispatch of this driver's would end that hold. A full pool's release is written
+// once per hold, so it does not add a line on every pass; the finished run's is written every time.
+
+const NO_FREE_LANES = 0
+const OFFER_PREFIX = 'offer'
+const HAND_BACK_PREFIX = 'hand-back'
+const REASON_SEPARATOR = ':'
+// The verdict that starts nothing more: the run is finishing, so the lanes it frees are no hold.
+const STOP_VERDICT = 'stop'
+// The ends that finished the run: nothing is owed a lane after them.
+const FINISHED_REASONS: ReadonlySet<string> = new Set([STOP_VERDICT, 'watch', 'retrospective'])
+
+interface HoldRecorder {
+	hold: DrivePorts['hold']
+	end: (end: DriveEnd) => Promise<void>
+}
+
+// The issues an offer that started nothing waited on, when it named them (joshuafolkken/kit#4513).
+interface HeldWaiting {
+	waiting?: ReadonlyArray<number> | undefined
+}
+
+// A hold's reason, `undefined` for the finished run, and the issues its offer waited on.
+interface HeldDraft extends HeldWaiting {
+	reason: string | undefined
+}
+
+// Whether a hold may still be open — at a driver's start, one an earlier driver's hand-back left.
+interface HoldLedger {
+	is_open: boolean
+}
+
+// The reason an offer that started nothing holds a free lane, or `undefined` for the run's stop. The
+// offer's cause stands in for its answer, so a `run:solo` wait is `offer:watch:solo` rather than one
+// more `offer:watch:blocked` (joshuafolkken/kit#4396), and a dependency-chain or start-condition wait is
+// `offer:watch:chain`, `offer:watch:gate` or `offer:watch:chain+gate` (joshuafolkken/kit#4513).
+function offer_reason(read: OfferRead): string | undefined {
+	if (read.verdict === STOP_VERDICT) return undefined
+
+	const detail = read.cause ?? read.answer
+	const parts = [OFFER_PREFIX, read.verdict, ...(detail === undefined ? [] : [detail])]
+
+	return parts.join(REASON_SEPARATOR)
+}
+
+// A continuing pass after an offer that started nothing is a hold; an ended one is the hand-back's.
+async function held(
+	result: PassResult,
+	read: OfferRead,
+	ports: Pick<DrivePorts, 'hold'>,
+): Promise<PassResult> {
+	if (result.kind === 'continue') await ports.hold(offer_reason(read), read.waiting)
+
+	return result
+}
+
+// A collection whose `run:merge` answered `stop` — the consecutive-failure guard — finishes the run as
+// an offer's `stop` does, but no offer follows it to release the hold, so it is released here. Left
+// open, the lanes it freed read as held until the next driver's first offer (joshuafolkken/kit#4571).
+async function stopped(
+	before: DriveState,
+	after: DriveState,
+	ports: Pick<DrivePorts, 'hold'>,
+): Promise<void> {
+	if (after.is_stopping && !before.is_stopping) await ports.hold(undefined)
+}
+
+// The reason a driver's end leaves the lanes waiting on a session, or `undefined` for the finished run.
+function hand_back_reason(end: DriveEnd): string | undefined {
+	if (FINISHED_REASONS.has(end.reason)) return undefined
+
+	return [HAND_BACK_PREFIX, end.reason].join(REASON_SEPARATOR)
+}
+
+// The free count, or `undefined` where the lane limit is unreadable: no hold is known then. The
+// finished run (`reason` absent) reads as a full pool — it holds no lane either way.
+async function free_count(
+	free_lanes: () => Promise<number>,
+	reason: string | undefined,
+): Promise<number | undefined> {
+	if (reason === undefined) return NO_FREE_LANES
+
+	try {
+		return await free_lanes()
+	} catch {
+		return undefined
+	}
+}
+
+async function release(ledger: HoldLedger): Promise<void> {
+	ledger.is_open = false
+	await lane_ledger.record_released()
+}
+
+async function release_open(ledger: HoldLedger): Promise<void> {
+	if (ledger.is_open) await release(ledger)
+}
+
+// A ledger line only while a lane is free. The finished run always writes its release: children parked
+// since a full pool's release still wait for an offer answer, and only this line ends their wait
+// (joshuafolkken/kit#4571). A full pool releases the open hold once, not on every pass.
+async function record(
+	ledger: HoldLedger,
+	draft: HeldDraft,
+	count: number | undefined,
+): Promise<void> {
+	if (count === undefined) return
+
+	if (draft.reason === undefined) {
+		await release(ledger)
+
+		return
+	}
+
+	if (count === NO_FREE_LANES) {
+		await release_open(ledger)
+
+		return
+	}
+
+	ledger.is_open = true
+	await lane_ledger.record_held({ reason: draft.reason, waiting: draft.waiting })
+}
+
+// The production `hold` port and the driver's end, sharing whether a hold is open. Best-effort like
+// every ledger write — an unreadable lane limit records nothing rather than failing the driver.
+function recorder(
+	free_lanes: () => Promise<number> = backlog_ready.drive_free_lane_count,
+): HoldRecorder {
+	const ledger: HoldLedger = { is_open: true }
+
+	async function write(reason: string | undefined, waiting?: ReadonlyArray<number>): Promise<void> {
+		await record(ledger, { reason, waiting }, await free_count(free_lanes, reason))
+	}
+
+	return {
+		hold: write,
+		end: async (end) => {
+			await write(hand_back_reason(end))
+		},
+	}
+}
+
+const backlog_drive_hold = { hand_back_reason, held, recorder, stopped }
+
+export { backlog_drive_hold }
+export type { HeldWaiting, HoldRecorder }

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

@@ -0,0 +1,151 @@
+import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { has_any_label, NEEDS_DECISION_LABEL, RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+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 type { DrivePorts, DriveState, OfferRead, PassResult } from './backlog-drive'
+
+// The one notification an idle backlogrun sends (joshuafolkken/kit#4015): a watch with no child running
+// is where a person's hand is wanted — a parked issue to decide, a dated one to wait out, or the next run
+// to start. A stall was notified instead and reached nobody with anything to do, since the next dispatch
+// resolved it; this fires only once nothing is left for the loop itself to do.
+//
+// **Once per idle episode**: the loop asks once a minute while it watches, so the marker on the stream
+// (`emit_once_since_with`, reset by a `child-launch`) holds every repeat back, and the pool is read only
+// for an episode that is new.
+
+const WATCH_VERDICT = 'watch'
+const BLOCKED_ANSWER = 'blocked'
+const DECISION_HEADING = `Waiting on a decision (${NEEDS_DECISION_LABEL}):`
+const STALLED_HEADING = `Stalled mechanically (${RUN_STALLED_LABEL}):`
+const IDLE_HEAD = 'No child running and nothing left to dispatch.'
+const IDLE_RECOVERY =
+	'Decide the parked issues, fix and release the stalled ones, or start the next run with `backlogrun`.'
+
+interface IdlePorts {
+	read_issues: () => Promise<ReadonlyArray<OpenIssueData> | undefined>
+	emit: (compose: () => Promise<string>) => Promise<string | undefined>
+	send: (body: string) => Promise<boolean>
+	now_ms: () => number
+}
+
+interface IdleReading {
+	merged: number
+	// The `auto-ok` pool, or `undefined` when it could not be read.
+	issues: ReadonlyArray<OpenIssueData> | undefined
+	now_ms: number
+}
+
+// Idle is any watch with nothing in flight, not only the drain: a watch over parked or dated issues
+// alone waits on a person just the same. A `blocked` watch is not: with nothing in flight it is only a
+// transient `retry`, which says nothing about whether work is left to dispatch.
+function is_idle(result: PassResult, read: OfferRead): boolean {
+	if (read.answer === BLOCKED_ANSWER) return false
+
+	return read.verdict === WATCH_VERDICT && result.state.in_flight.length === 0
+}
+
+async function noticed(
+	result: PassResult,
+	read: OfferRead,
+	ports: Pick<DrivePorts, 'idle'>,
+): Promise<PassResult> {
+	if (is_idle(result, read)) await ports.idle(result.state)
+
+	return result
+}
+
+function cited(issue: OpenIssueData, suffix = ''): string {
+	return `- ${issue_cite.plain(issue.number)} ${issue.title}${suffix}`
+}
+
+// The cited issues carrying one park label. `needs-decision` and `run:stalled` are listed apart: one asks
+// a person for a judgement, the other for a mechanical fix (`issue-labels.ts`).
+function labelled_lines(issues: ReadonlyArray<OpenIssueData>, label: string): Array<string> {
+	return issues
+		.filter((issue) => has_any_label(issue.labels, new Set([label])))
+		.map((issue) => cited(issue))
+}
+
+function dated_lines(issues: ReadonlyArray<OpenIssueData>, now_ms: number): Array<string> {
+	const lines: Array<string> = []
+
+	for (const issue of issues) {
+		const reason = issue_not_before.waiting_reason(issue.body, now_ms)
+
+		if (reason !== undefined) lines.push(cited(issue, ` — ${reason}`))
+	}
+
+	return lines
+}
+
+function section(heading: string, lines: ReadonlyArray<string>): Array<string> {
+	return lines.length === 0 ? [] : [heading, ...lines]
+}
+
+function remaining_lines(reading: IdleReading): Array<string> {
+	if (reading.issues === undefined) return ['Remaining issues: unreadable']
+
+	const lines = [
+		...section(DECISION_HEADING, labelled_lines(reading.issues, NEEDS_DECISION_LABEL)),
+		...section(STALLED_HEADING, labelled_lines(reading.issues, RUN_STALLED_LABEL)),
+		...section('Waiting on a date:', dated_lines(reading.issues, reading.now_ms)),
+	]
+
+	return lines.length === 0 ? ['Nothing parked or dated is left.'] : lines
+}
+
+function describe(reading: IdleReading): string {
+	const merged = `Merged this run: ${String(reading.merged)}`
+
+	return [IDLE_HEAD, merged, ...remaining_lines(reading)].join('\n')
+}
+
+async function read_pool(): Promise<ReadonlyArray<OpenIssueData> | undefined> {
+	const read = await auto_ok_cli.fetch_opted_in()
+
+	return read.kind === 'read' ? read.issues : undefined
+}
+
+async function emit_idle(compose: () => Promise<string>): Promise<string | undefined> {
+	const { IDLE_NOTICE, CHILD_LAUNCH } = run_event_stream.EVENT_KIND
+
+	return await run_event_stream_emit.emit_once_since_with(IDLE_NOTICE, CHILD_LAUNCH, compose)
+}
+
+async function send_idle(body: string): Promise<boolean> {
+	return await telegram_notify.idle({ body, recovery: IDLE_RECOVERY })
+}
+
+const DEFAULT_PORTS: IdlePorts = {
+	read_issues: read_pool,
+	emit: emit_idle,
+	send: send_idle,
+	now_ms: () => Date.now(),
+}
+
+// The production `idle` port. Best-effort: the loop is only reporting, so a failed read or send is
+// dropped rather than raised into the watch.
+async function notify(state: DriveState, ports: IdlePorts = DEFAULT_PORTS): Promise<void> {
+	try {
+		const body = await ports.emit(async () =>
+			describe({
+				merged: state.exclude.length,
+				issues: await ports.read_issues(),
+				now_ms: ports.now_ms(),
+			}),
+		)
+
+		if (body !== undefined) await ports.send(body)
+	} catch {
+		// Reporting is best-effort: an idle notice we could not read or send is dropped.
+	}
+}
+
+const backlog_drive_idle = { describe, noticed, notify, read_pool }
+
+export { backlog_drive_idle }
+export type { IdlePorts }

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

@@ -0,0 +1,25 @@
+import type { DrivePorts, OfferRead } from './backlog-drive'
+
+// **A free lane with nothing opted in is the open backlog's turn to be judged**
+// (joshuafolkken/kit#3854): a watch over an exhausted pool hands back `judge` while an open issue
+// lacking `auto-ok` still owes a judgement, ahead of the drain it would otherwise be. Once every one
+// carries its judgement comment the count is zero and the watch is the driver's again.
+
+const WATCH_VERDICT = 'watch'
+const EXHAUSTED_ANSWER = 'exhausted'
+const NO_FREE_LANES = 0
+
+async function is_owed(
+	read: OfferRead,
+	ports: Pick<DrivePorts, 'free_lanes' | 'judgement_owed'>,
+): Promise<boolean> {
+	const is_exhausted = read.verdict === WATCH_VERDICT && read.answer === EXHAUSTED_ANSWER
+
+	if (!is_exhausted || (await ports.free_lanes()) <= NO_FREE_LANES) return false
+
+	return (await ports.judgement_owed()) > 0
+}
+
+const backlog_drive_judge = { is_owed }
+
+export { backlog_drive_judge }

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,11 +1,9 @@
 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 } 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/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'
@@ -52,12 +50,12 @@ 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.
-// Either is booked done rather than offered.
+// 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_label_name(state.labels, NEEDS_DECISION_LABEL) ? 'parked' : undefined
+	return has_parked_label(state.labels) ? 'parked' : undefined
 }
 
 async function classify(
@@ -102,10 +100,7 @@ async function is_unmerged(issue: number, merged: ReadonlyArray<number>): Promis
 // 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,
-	)
+	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)))
 

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'
@@ -12,7 +13,7 @@ const { MERGE_TOKEN } = run_merge_token
 
 const NO_RETRIES = 0
 const FIRST = 0
-const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split'])
+const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split', 'withdrawn'])
 
 // The skip follows the declared order alone: an issue `run:add` put in was
 // asked for on its own, so its failure skips nothing and a declared failure does not skip it.
@@ -23,18 +24,37 @@ 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
 }
 
 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)
@@ -129,4 +149,31 @@ 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,
+	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,
 	]
 }