@joshuafolkken/kit 1.1471.0 → 1.1784.0

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,16 +1,20 @@
+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([
 	run_event_stream.EVENT_KIND.MERGE,
 	run_event_stream.EVENT_KIND.PARK,
 	run_event_stream.EVENT_KIND.SPLIT,
+	run_event_stream.EVENT_KIND.WITHDRAW,
 	run_event_stream.EVENT_KIND.OUTAGE,
 ])
 const DONE_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.MERGE,
 	run_event_stream.EVENT_KIND.PARK,
 	run_event_stream.EVENT_KIND.SPLIT,
+	run_event_stream.EVENT_KIND.WITHDRAW,
 ])
 
 function issue_of(event: RunEvent): string | undefined {
@@ -44,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
@@ -82,4 +105,12 @@ function restore(
 	)
 }
 
-export const backlog_drive_restore = { active_issues, restore, settled_issues, parked_issues }
+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 }

package/scripts/backlog/backlog-drive.ts

@@ -19,43 +19,22 @@
 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, type MergeToken } from '#scripts/run/merge/run-merge-token'
+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_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
+const { HANDOFF_TOKENS, IMMEDIATE_TOKENS, TOKEN_HANDLING } = backlog_drive_token_handling
 const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
-// 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 MERGED_OUTCOME = 'merged'
+// The outcomes that keep a child out of the rest of this run's offers.
+const EXCLUDED_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'withdrawn'])
 const WATCH_VERDICT = 'watch'
 // The verdicts the loop acts on without the parent. Any other is handed back as it was printed.
 const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
@@ -71,11 +50,13 @@ const JUDGE_REASON = 'judge'
 const LAUNCHED = 'launched'
 const UNOPENED = 'unopened'
 
-interface OfferRead {
+interface OfferRead extends HeldWaiting {
 	verdict: string
 	issues: ReadonlyArray<string>
 	retries: number
 	answer?: string | undefined
+	// Why a `blocked` answer started nothing — `solo`, or `backlog-wait-cause.ts`'s with its `waiting`.
+	cause?: string | undefined
 	reason?: string | undefined
 	// Whether a drain here owes the retrospective: the opt-in switch is on and it has not run yet. Absent
 	// reads as not owed, so a drain with the switch off keeps the idle watch.
@@ -98,6 +79,8 @@ interface DriveState {
 	stop_is_finish?: boolean | undefined
 	// The child whose merge answered `stop`, carried on the resume line: no offer re-derives that stop.
 	stopped_by?: string | undefined
+	// The last offer answered `run` on a machine with no memory to spare (`backlog-drive-memory.ts`).
+	is_memory_held?: boolean | undefined
 }
 
 interface DriveEnd {
@@ -118,6 +101,9 @@ interface DrivePorts {
 	is_finished: (issue: string) => boolean
 	// `run:merge <N>`'s first stdout token and the outcome it handled the child as.
 	merge: (issue: string) => Promise<Collected>
+	// The lanes on a child this run launched and never settled that the loop does not hold — one the
+	// parent dispatched itself with `lane:launch` (`backlog_drive_adopt.adoptable` in production).
+	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).
@@ -125,12 +111,26 @@ interface DrivePorts {
 	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
 	// open lanes.
 	free_lanes: () => Promise<number>
-	// Whether the issue already holds a kept lane (one a child was dispatched into) — it is reused, so it
-	// takes no free seat.
+	// The places left under the limit, port seats aside — `backlog_ready.drive_limit_room` in production.
+	limit_room: () => Promise<number>
+	// Whether the issue already holds a kept lane (one a child was dispatched into) — it is reused, and
+	// seated ahead of a fresh launch inside the limit room (`backlog-drive-seats.ts`).
 	has_lane: (issue: string) => Promise<boolean>
 	// How many open issues lacking `auto-ok` still owe a judgement — `auto_ok_judge_read.owed` in
 	// production, `0` when the read failed.
 	judgement_owed: () => Promise<number>
+	// 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>
+	// 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>
+	// A watch with nothing in flight — the one idle notification (`backlog-drive-idle.ts`), deduplicated
+	// per episode by the port itself.
+	idle: (state: DriveState) => Promise<void>
+	// A holding offer with nothing in flight — the paused-lane notice (`backlog-drive-paused.ts`), which
+	// reads the lane records itself and is deduplicated per pause episode by the port.
+	paused: () => Promise<void>
 	now: () => Date
 }
 
@@ -154,20 +154,12 @@ function ended(reason: string, state: DriveState, token?: string, issue?: string
 	}
 }
 
-// Only an empty backlog drains: `backlog:offer` marks the drain on `exhausted` alone, so a watch over a
-// parked or unreadable backlog has no retrospective for `run:step` to fire and stays the driver's.
-function is_drain(read: OfferRead, state: DriveState): boolean {
+// A drain owing the retrospective, read under a `watch` or a `stop` verdict. Only an empty backlog
+// drains: `backlog:offer` marks the drain on `exhausted` alone, so a watch over a parked or unreadable
+// backlog has no retrospective for `run:step` to fire and stays the driver's.
+function is_drain_owed(read: OfferRead, state: DriveState, verdict: string): boolean {
 	return (
-		read.verdict === WATCH_VERDICT &&
-		read.answer === EXHAUSTED_ANSWER &&
-		state.in_flight.length === 0 &&
-		read.is_retrospective_owed === true
-	)
-}
-
-function needs_retrospective(read: OfferRead, state: DriveState): boolean {
-	return (
-		read.verdict === STOP_VERDICT &&
+		read.verdict === verdict &&
 		read.answer === EXHAUSTED_ANSWER &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
@@ -196,10 +188,12 @@ function merge_stopped(issue: string, state: DriveState): DriveState {
 	}
 }
 
-// Only a merged child is excluded: `backlog:next` may still read it OPEN. Any other is classified by
-// its labels, so excluding it would hide a child a person released for the rest of the process.
+// A merged child is excluded because `backlog:next` may still read it OPEN, and a withdrawn one because
+// `lane:withdraw` leaves it OPEN for the next run, not this one (joshuafolkken/kit#4365). Any other is
+// classified by its labels, so excluding it would hide a child a person released for the rest of the
+// process.
 function excluded(issue: string, outcome: Collected['outcome'], state: DriveState): Array<string> {
-	if (outcome !== MERGED_OUTCOME || state.exclude.includes(issue)) return state.exclude
+	if (!EXCLUDED_OUTCOMES.has(outcome) || state.exclude.includes(issue)) return state.exclude
 
 	return [...state.exclude, issue]
 }
@@ -251,6 +245,8 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 		current = result.state
 	}
 
+	await backlog_drive_hold.stopped(state, current, ports)
+
 	return { kind: 'continue', state: current }
 }
 
@@ -271,8 +267,8 @@ async function refused(
 
 // **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 it and takes no seat (`backlog-drive-seats.ts`); the rest launch
-// up to the free count, read once before the first launch.
+// 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.
@@ -310,7 +306,10 @@ async function launch_all(
 // parent's. With children still running the watch is only waiting on them.
 function on_verdict(read: OfferRead, state: DriveState): PassResult {
 	if (!KNOWN_VERDICTS.has(read.verdict)) return ended(read.verdict, state, read.verdict)
-	if (needs_retrospective(read, state)) return ended('retrospective', state, 'retrospective')
+
+	if (is_drain_owed(read, state, STOP_VERDICT)) {
+		return ended('retrospective', state, 'retrospective')
+	}
 
 	if (read.verdict === STOP_VERDICT) {
 		return {
@@ -324,43 +323,44 @@ function on_verdict(read: OfferRead, state: DriveState): PassResult {
 		}
 	}
 
-	if (is_drain(read, state)) return ended(WATCH_VERDICT, state, WATCH_VERDICT)
+	if (is_drain_owed(read, state, WATCH_VERDICT)) return ended(WATCH_VERDICT, state, WATCH_VERDICT)
 
 	return { kind: 'continue', state }
 }
 
-// **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.
-async function is_judgement_owed(read: OfferRead, ports: DrivePorts): 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
+// An offer answered `run`: launched while the machine has memory to spare, held until it does otherwise.
+async function run_offered(
+	issues: ReadonlyArray<string>,
+	state: DriveState,
+	ports: DrivePorts,
+): Promise<PassResult> {
+	if (await ports.memory_held()) return await backlog_drive_memory.held(state, ports)
 
-	return (await ports.judgement_owed()) > 0
+	return await launch_all(issues, state, ports)
 }
 
+// Every offer answers the memory hold afresh: one that is not `run` leaves nothing held for memory.
 async function ask_offer(state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const read = await ports.offer(state)
 
 	if (read === undefined) return ended('offer', state)
 
-	const next = { ...state, retries: read.retries }
+	const next = { ...state, retries: read.retries, is_memory_held: false }
 
-	if (read.verdict === RUN_VERDICT) return await launch_all(read.issues, next, ports)
-	if (await is_judgement_owed(read, ports)) return ended(JUDGE_REASON, next, JUDGE_REASON)
+	if (read.verdict === RUN_VERDICT) return await run_offered(read.issues, next, ports)
+	if (await backlog_drive_judge.is_owed(read, ports)) return ended(JUDGE_REASON, next, JUDGE_REASON)
 
-	return on_verdict(read, next)
+	const idle = await backlog_drive_idle.noticed(on_verdict(read, next), read, ports)
+	const result = await backlog_drive_paused.noticed(idle, read, ports)
+
+	return await backlog_drive_hold.held(result, read, ports)
 }
 
 // One pass: collect every child that ended, then — unless a `stop` has been read — ask what to start.
 // `should_offer` is the caller's throttle on the one network read; a collection always asks, because a
 // lane just freed.
 function is_offering(before: DriveState, after: DriveState, should_offer: boolean): boolean {
-	if (after.is_stopping) return false
-
-	return should_offer || after.in_flight.length !== before.in_flight.length
+	return !after.is_stopping && (should_offer || after.in_flight.length !== before.in_flight.length)
 }
 
 // A stopping run with nothing left in flight has ended.
@@ -377,10 +377,11 @@ async function run_pass(
 	should_offer: boolean,
 	ports: DrivePorts,
 ): Promise<PassResult> {
-	const collected = await collect_finished(state, ports)
+	const held = await backlog_drive_adopt.held(state, should_offer, ports)
+	const collected = await collect_finished(held, ports)
 
 	if (collected.kind === 'end') return collected
-	if (!is_offering(state, collected.state, should_offer)) return settle(collected)
+	if (!is_offering(held, collected.state, should_offer)) return settle(collected)
 
 	return settle(await ask_offer(collected.state, ports))
 }
@@ -419,10 +420,13 @@ function is_window_spent(run: LoopRun, config: LoopConfig, now_ms: number): bool
 type LoopStep = { kind: 'end'; end: DriveEnd } | { kind: 'next'; run: LoopRun }
 
 // One pass of the loop: the offer is due on the first pass and then no oftener than `offer_ms`, bar the
-// passes that collected a child. A `next` carries the run to sleep on and pass again.
+// passes that collected a child and the one that finds a memory hold cleared. A `next` carries the run
+// to sleep on and pass again.
 async function loop_step(run: LoopRun, config: LoopConfig, ports: LoopPorts): Promise<LoopStep> {
 	const now_ms = ports.now().getTime()
-	const is_due = now_ms - run.offered_ms >= config.offer_ms
+	const is_due =
+		now_ms - run.offered_ms >= config.offer_ms ||
+		(await backlog_drive_memory.is_cleared(run.state, ports))
 	const result = await run_pass(run.state, is_due, ports)
 
 	ports.on_state(result.state)

package/scripts/backlog/backlog-next-main.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { backlog_next } from './backlog-next'
+
+// The `josh backlog:next` entry, kept apart from `backlog-next.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+//
+// `process.exitCode` rather than `process.exit()`, for the reason `auto-ok:next` records: the whole
+// contract is `answers=$(pnpm josh backlog:next)`, and exiting outright can cut the pipe before it
+// has drained.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await backlog_next.run(process.argv.slice(ARGV_OFFSET))
+}