@joshuafolkken/kit 1.1514.0 → 1.1784.0

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'
@@ -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,
 	]
 }

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

@@ -0,0 +1,169 @@
+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 { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_state, type LaneStateRecord } from '#scripts/lane/lane-state'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+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 { 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'
+
+// 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
+// path an open candidate overlaps. A paused lane holds no lane place (`backlog-occupied.ts`), so that
+// overlap is the one way it holds the run; the loop would otherwise watch for ever — a paused lane
+// frees nothing until someone resumes it — so it asks the person once. A drained or parked backlog
+// with a lane paused somewhere is not held by it, and stays quiet.
+//
+// **Once per pause episode**: the marker on the stream (`emit_once_since_with`, reset by the
+// `lane-state` line every `lane:pause` / `lane:resume` writes) holds every repeat back.
+
+const HOLDING_VERDICTS: ReadonlySet<string> = new Set(['watch', 'wait'])
+const BLOCKED_ANSWER = 'blocked'
+const PAUSED_TITLE = 'backlogrun held by paused lanes'
+const PAUSED_HEAD =
+	'No child of this run is running, and these paused lanes hold back work overlapping their paths:'
+const PAUSED_RECOVERY =
+	'Resume a lane with `pnpm josh lane:resume <N>`, or close it with `pnpm josh lane:close <N>`.'
+const SILENT_WINDOW_MS = DEFAULT_SILENT_MINUTES * MS_PER_MINUTE
+// A candidate a person set aside waits on that person, not on the paused lane it overlaps.
+const SET_ASIDE_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, RUN_STALLED_LABEL])
+
+interface PausedPorts {
+	read_records: () => Promise<ReadonlyArray<LaneStateRecord>>
+	// The `auto-ok` pool, or `undefined` when it could not be read.
+	read_issues: () => Promise<ReadonlyArray<OpenIssueData> | undefined>
+	emit: (compose: () => Promise<string>) => Promise<string | undefined>
+	send: (body: string) => Promise<boolean>
+	now_ms: () => number
+}
+
+// The port is asked on every holding offer with nothing in flight; `notify` decides whether a paused
+// lane is what holds it.
+function is_held(result: PassResult, read: OfferRead): boolean {
+	if (read.answer === BLOCKED_ANSWER) return false
+
+	return HOLDING_VERDICTS.has(read.verdict) && result.state.in_flight.length === 0
+}
+
+async function noticed(
+	result: PassResult,
+	read: OfferRead,
+	ports: Pick<DrivePorts, 'paused'>,
+): Promise<PassResult> {
+	if (is_held(result, read)) await ports.paused()
+
+	return result
+}
+
+/** The records paused for at least the silent window at `now_ms`. */
+function long_paused(
+	records: ReadonlyArray<LaneStateRecord>,
+	now_ms: number,
+): Array<LaneStateRecord> {
+	return records.filter(
+		(record) =>
+			record.state === 'paused' && now_ms - Date.parse(record.changed_at) >= SILENT_WINDOW_MS,
+	)
+}
+
+// The open candidates no lane works on and no person set aside — the ones a paused lane can hold.
+function waiting_of(
+	issues: ReadonlyArray<OpenIssueData>,
+	records: ReadonlyArray<LaneStateRecord>,
+): Array<number> {
+	const lanes = new Set(records.map((record) => record.issue))
+
+	return issues
+		.filter((issue) => !lanes.has(String(issue.number)))
+		.filter((issue) => !has_any_label(issue.labels, SET_ASIDE_LABELS))
+		.map((issue) => issue.number)
+}
+
+/** The `paused` records whose declared paths a waiting candidate overlaps. */
+function holding(
+	paused: ReadonlyArray<LaneStateRecord>,
+	issues: ReadonlyArray<OpenIssueData>,
+	records: ReadonlyArray<LaneStateRecord>,
+): Array<LaneStateRecord> {
+	const declared = backlog_overlap.declared_of(issues)
+	const waiting = waiting_of(issues, records)
+
+	return paused.filter((record) =>
+		waiting.some((number) => backlog_overlap.holds(declared, Number(record.issue), number)),
+	)
+}
+
+async function held_by(ports: PausedPorts): Promise<Array<LaneStateRecord>> {
+	const records = await ports.read_records()
+	const paused = long_paused(records, ports.now_ms())
+
+	if (paused.length === 0) return []
+
+	const issues = await ports.read_issues()
+
+	return issues === undefined ? [] : holding(paused, issues, records)
+}
+
+function describe(records: ReadonlyArray<LaneStateRecord>): string {
+	const lines = records.map(
+		(record) => `- ${issue_cite.plain(record.issue)} — ${lane_state.paused_note(record) ?? ''}`,
+	)
+
+	return [PAUSED_HEAD, ...lines].join('\n')
+}
+
+async function read_lane_records(): Promise<ReadonlyArray<LaneStateRecord>> {
+	const lanes = await lane_registry.list_lanes()
+	const records = await lane_state.read_states(lanes.map((lane) => lane.issue))
+
+	return [...records.values()]
+}
+
+async function emit_paused(compose: () => Promise<string>): Promise<string | undefined> {
+	const { PAUSED_NOTICE, LANE_STATE } = run_event_stream.EVENT_KIND
+
+	return await run_event_stream_emit.emit_once_since_with(PAUSED_NOTICE, LANE_STATE, compose)
+}
+
+async function send_paused(body: string): Promise<boolean> {
+	return await telegram_notify.confirm({
+		issue_title: PAUSED_TITLE,
+		body,
+		recovery: PAUSED_RECOVERY,
+		recommended: 'Resume the paused lanes with `pnpm josh lane:resume <N>`',
+		alternatives: ['Close the paused lanes with `pnpm josh lane:close <N>`'],
+	})
+}
+
+const DEFAULT_PORTS: PausedPorts = {
+	read_records: read_lane_records,
+	read_issues: backlog_drive_idle.read_pool,
+	emit: emit_paused,
+	send: send_paused,
+	now_ms: () => Date.now(),
+}
+
+// The production `paused` port. Best-effort, as the idle port is: a failed read or send is dropped.
+async function notify(ports: PausedPorts = DEFAULT_PORTS): Promise<void> {
+	try {
+		const paused = await held_by(ports)
+
+		if (paused.length === 0) return
+
+		const body = await ports.emit(async () => describe(paused))
+
+		if (body !== undefined) await ports.send(body)
+	} catch {
+		// Reporting is best-effort: a paused notice we could not read or send is dropped.
+	}
+}
+
+const backlog_drive_paused = { noticed, notify }
+
+export { backlog_drive_paused }
+export type { PausedPorts }

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

@@ -1,4 +1,6 @@
+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'
 
 const ISSUE_IN_EVENT = /#([1-9]\d*)\b/u
 const SETTLED_KINDS: ReadonlySet<string> = new Set([
@@ -46,14 +48,33 @@ function settled_issues(events: ReadonlyArray<RunEvent>): ReadonlySet<number> {
 	)
 }
 
+function issues_of_kind(events: ReadonlyArray<RunEvent>, kind: string): ReadonlyArray<string> {
+	return events
+		.filter((event) => event.kind === kind)
+		.map((event) => issue_of(event))
+		.filter((issue) => issue !== undefined)
+}
+
+// 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).
+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))
+}
+
+// The offer's exclusion as the stream records it: the merged and withdrawn children and the ones still
+// in flight — the list the drive keeps in memory, read by a reader that has only the stream
+// (joshuafolkken/kit#4349).
+function offer_exclude(events: ReadonlyArray<RunEvent>): ReadonlyArray<string> {
+	const merged = issues_of_kind(events, run_event_stream.EVENT_KIND.MERGE)
+	const settled = [...merged, ...withdrawn_issues(events)]
+
+	return backlog_offer_exclude.exclude_of(settled, active_issues(events))
+}
+
 function parked_issues(events: ReadonlyArray<RunEvent>): ReadonlySet<number> {
-	return new Set(
-		events
-			.filter((event) => event.kind === run_event_stream.EVENT_KIND.PARK)
-			.map((event) => issue_of(event))
-			.filter((issue) => issue !== undefined)
-			.map(Number),
-	)
+	return new Set(issues_of_kind(events, run_event_stream.EVENT_KIND.PARK).map(Number))
 }
 
 // The issues this invocation launched or settled — any other dispatched lane was carried in from an
@@ -87,7 +108,9 @@ function restore(
 export const backlog_drive_restore = {
 	active_issues,
 	mentioned_issues,
+	offer_exclude,
 	restore,
+	withdrawn_issues,
 	settled_issues,
 	parked_issues,
 }

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

@@ -1,25 +1,35 @@
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_vacant } from '#scripts/lane/lane-vacant'
 import type { DrivePorts } from './backlog-drive'
 
-type SeatPorts = Pick<DrivePorts, 'free_lanes' | 'has_lane'>
+type SeatPorts = Pick<DrivePorts, 'free_lanes' | 'has_lane' | 'limit_room'>
 
-// The issues a pass launches: every one that already holds a kept lane, which it reuses, then as many
-// of the rest as there are free lanes.
+// The issues a pass launches: those that already hold a kept lane first, then the rest. A lane with no
+// child in it holds no place under the limit (`backlog-occupied.ts`), so resuming its issue takes one
+// (joshuafolkken/kit#4107) — but it keeps its port seat, so the resumes are cut by the limit room alone:
+// idle kept lanes filling every seat must not shut out their own resumes. Fresh launches take what is
+// left of both.
 async function seated(issues: ReadonlyArray<string>, ports: SeatPorts): Promise<Array<string>> {
 	const kept = await Promise.all(issues.map(async (issue) => await ports.has_lane(issue)))
-	const fresh = issues.filter((_issue, index) => kept[index] !== true)
+	const room = await ports.limit_room()
+	const resumed = issues.filter((_issue, index) => kept[index] === true).slice(0, room)
+	const fresh_room = Math.min(await ports.free_lanes(), room - resumed.length)
 
 	return [
-		...issues.filter((_issue, index) => kept[index] === true),
-		...fresh.slice(0, await ports.free_lanes()),
+		...resumed,
+		...issues.filter((_issue, index) => kept[index] !== true).slice(0, fresh_room),
 	]
 }
 
-// A kept lane is one a child was dispatched into — `lane:launch` reuses it rather than opening one.
+// A kept lane is one a child was dispatched into that holds work — `lane:launch` reuses it rather
+// than opening one. A vacant one holds nothing to resume, so its issue waits in line like any fresh
+// launch (joshuafolkken/kit#4028).
 async function has_kept_lane(issue: string): Promise<boolean> {
 	const lane = await lane_registry.find_open_lane(issue)
 
-	return lane?.output !== undefined
+	if (lane?.output === undefined) return false
+
+	return !(await lane_vacant.is_vacant(lane))
 }
 
 const backlog_drive_seats = { has_kept_lane, seated }

package/scripts/backlog/backlog-drive-token-handling.ts

@@ -0,0 +1,38 @@
+import { run_merge_token, type MergeToken } from '#scripts/run/merge/run-merge-token'
+
+const { MERGE_TOKEN } = run_merge_token
+
+// How the loop reads each `run:merge` token — keyed by the producer's own type, so a token added there
+// is a type error here until it is classified. `hand-back` ends the loop at once: a hand-off, a person's
+// stop, the environment down, a foreign owner, an unreadable state. `stop` — the failure guard, or a
+// failed child left unparked — collects the child, starts nothing more, and collects the children still
+// in flight before the loop ends. `await` is a cut resumed in place: the same lane is awaited again.
+//
+// **The offer `run:merge` passes through is never read here** (joshuafolkken/kit#3781): its `stop` —
+// only person-waiting issues left — is spelled like the control one, and acting on it ended the run
+// without the idle watch. The loop asks `backlog:offer` on the next pass instead, so whether a parked
+// backlog waits or ends is `backlog:budget`'s alone, after a merge as after any other pass.
+type TokenHandling = 'hand-back' | 'stop' | 'await'
+const TOKEN_HANDLING: Readonly<Record<MergeToken, TokenHandling>> = {
+	[MERGE_TOKEN.OVER]: 'hand-back',
+	[MERGE_TOKEN.HUMAN_REVIEW]: 'hand-back',
+	[MERGE_TOKEN.ENVIRONMENT]: 'hand-back',
+	[MERGE_TOKEN.BUSY]: 'hand-back',
+	[MERGE_TOKEN.RETRY]: 'hand-back',
+	[MERGE_TOKEN.STOP]: 'stop',
+	[MERGE_TOKEN.RESUMED]: 'await',
+}
+
+function tokens_handled(...handlings: ReadonlyArray<TokenHandling>): ReadonlySet<string> {
+	const entries = Object.entries(TOKEN_HANDLING)
+
+	return new Set(entries.filter(([, handling]) => handlings.includes(handling)).map(([key]) => key))
+}
+
+const IMMEDIATE_TOKENS = tokens_handled('hand-back')
+// Every token `run:merge` prints first even on a non-zero exit.
+const HANDOFF_TOKENS = tokens_handled('hand-back', 'stop')
+
+const backlog_drive_token_handling = { HANDOFF_TOKENS, IMMEDIATE_TOKENS, TOKEN_HANDLING }
+
+export { backlog_drive_token_handling }