@joshuafolkken/kit 1.1514.0 → 1.1784.0

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))
+}

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

@@ -0,0 +1,73 @@
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+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 { z } from 'zod'
+import { backlog_next } from './backlog-next'
+
+// One `josh backlog:next` answer shared by every reader that asks it within a minute
+// (joshuafolkken/kit#4550).
+//
+// **The drive's assignment and the arrival probe each ask every minute, and since a lane waiting on its
+// merge frees its slot (joshuafolkken/kit#4483) a free slot is the usual state** — so both read the
+// whole pool from GitHub every minute, for the same answer.
+//
+// **The key carries the newest event on the run's stream**, so a launch, a merge or a park — anything
+// that can change what may start — is never answered from before it: the first ask after it reads
+// again. Only an answer that read is kept; a failure or a `retry` is asked again by the next reader.
+
+const SUCCESS_EXIT_CODE = 0
+
+const NEXT_CACHE: CacheSlot = { prefix: 'josh-backlog-next-', ttl_ms: 60_000 }
+
+const result_schema = z.object({
+	code: z.number(),
+	out: z.string(),
+	err: z.string().exactOptional(),
+})
+
+// The key a shared plan read is kept under: what was asked, and the newest event on the run's stream.
+// `run:board`'s plan read keys by it too (joshuafolkken/kit#4558).
+async function stream_key(scope: unknown): Promise<string> {
+	const target = await run_event_stream_emit.stream_target()
+	const last = target === undefined ? undefined : run_event_stream.read_last(target)
+
+	return JSON.stringify({ argv: scope, last })
+}
+
+function is_kept(result: JoshResult): boolean {
+	if (result.code !== SUCCESS_EXIT_CODE) return false
+
+	return !result.out.split('\n').includes(backlog_next.VERDICT_TOKENS.retry)
+}
+
+// A kept answer replays its explanation where the live one would have streamed it.
+function replay(result: JoshResult, should_forward_stderr: boolean): JoshResult {
+	if (should_forward_stderr && result.err !== undefined && result.err !== '') {
+		console.error(result.err)
+	}
+
+	return result
+}
+
+async function read(
+	argv: ReadonlyArray<string>,
+	should_forward_stderr = false,
+	timeout_ms?: number,
+): Promise<JoshResult> {
+	const key = await stream_key(argv)
+	const now_ms = Date.now()
+	const kept = shared_cache.read(NEXT_CACHE, key, result_schema, now_ms)
+
+	if (kept !== undefined) return replay(kept, should_forward_stderr)
+
+	const result = await josh_command.josh_run(argv, should_forward_stderr, timeout_ms)
+
+	if (is_kept(result)) shared_cache.write(NEXT_CACHE, key, result, now_ms)
+
+	return result
+}
+
+const backlog_next_shared = { NEXT_CACHE, read, stream_key }
+
+export { backlog_next_shared }

package/scripts/backlog/backlog-next.ts

@@ -1,4 +1,3 @@
-import { fileURLToPath } from 'node:url'
 import { auto_ok_cli, type OptedInRead, type TrackingRead } from '#scripts/auto-ok/auto-ok-cli'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
@@ -13,11 +12,16 @@ import { epic_solo_stale } from '#scripts/epic/epic-solo-stale'
 import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
+import { issue_not_before_label } from '#scripts/issue/issue-not-before-label'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_state } from '#scripts/lane/lane-state'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
 import { backlog_overlap } from './backlog-overlap'
 import { backlog_pool } from './backlog-pool'
 import { backlog_rank, type GateScope } from './backlog-rank'
+import { backlog_wait_cause } from './backlog-wait-cause'
 
 // `josh backlog:next` — what the whole opted-in backlog may run next.
 //
@@ -30,7 +34,6 @@ import { backlog_rank, type GateScope } from './backlog-rank'
 // `auto-ok:next`'s own listing and runnability rules, and the verdict comes from
 // `epic_report.decide_verdict` so it cannot drift from what `epic:next` means by the same word.
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 
@@ -130,6 +133,31 @@ function warn_gaps(context: PoolContext, has_answer: boolean): void {
 	warn_epic_gap(context)
 }
 
+// Why a row on the time side is not offered yet, when the reason is a declared start time or sample
+// condition — the waits a reader cannot see from the labels or the blockers. A sample condition names
+// its pull request as `#N`, linkified like the explanation.
+function warn_not_before(context: PoolContext): void {
+	for (const issue of context.opted_in.issues) {
+		const reason = issue_not_before.waiting_reason(issue.body)
+
+		if (reason === undefined) continue
+
+		const cited = session_cite.issue(issue.number, undefined, context.repo)
+
+		console.error(`${cited} ${issue_citation.linkify(reason, context.repo)}`)
+	}
+}
+
+// Which waiting issues hold the backlog on a dependency chain or a start condition, read back by
+// `backlog:offer` so a lane held by them is told apart in `lane:stats` (joshuafolkken/kit#4513).
+function warn_wait_causes(result: EpicNextResult, context: PoolContext): void {
+	const causes = backlog_wait_cause.classify(result.waiting, context.repo)
+
+	for (const line of backlog_wait_cause.lines_of(causes)) {
+		console.error(issue_citation.linkify(line, context.repo))
+	}
+}
+
 function report(result: EpicNextResult, context: PoolContext): number {
 	warn_gaps(context, result.verdict === 'run')
 	// The explanation names epics and children as `#N` (`tracked by epic #N`); linkified so the text a
@@ -139,8 +167,12 @@ function report(result: EpicNextResult, context: PoolContext): number {
 	const explanation = epic_report.format_result(result, context.repo)
 
 	console.error(issue_citation.linkify(explanation, context.repo))
+	warn_not_before(context)
 
-	for (const token of tokens_of(result, context.repo)) console.info(token)
+	const tokens = tokens_of(result, context.repo)
+
+	if (tokens[0] === VERDICT_TOKENS.wait) warn_wait_causes(result, context)
+	for (const token of tokens) console.info(token)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -297,11 +329,15 @@ function standalone_keys(context: PoolContext): ReadonlySet<string> {
 
 // The running lanes still carry the pickup label, so the opted-in listing holds their bodies too —
 // which is what lets a candidate be held back from a path a running lane already declares.
-// `backlog:plan --waves` reads the same scope, so its first wave is this offer.
-function gate_scope(context: PoolContext): GateScope {
+// `backlog:plan --waves` reads the same scope, so its first wave is this offer. Their lane state
+// records name a paused holder in the wait it causes (joshuafolkken/kit#4270); they are local files.
+async function gate_scope(context: PoolContext): Promise<GateScope> {
+	const { issues } = context.opted_in
+
 	return {
 		standalone: standalone_keys(context),
-		declared: backlog_overlap.declared_of(context.opted_in.issues),
+		declared: backlog_overlap.declared_of(issues),
+		lanes: await lane_state.read_states(issues.map((issue) => String(issue.number))),
 	}
 }
 
@@ -320,7 +356,7 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 
 	if (notice !== undefined) console.error(notice)
 
-	const gated = backlog_rank.gate(result, read, repo, gate_scope(context))
+	const gated = backlog_rank.gate(result, read, repo, await gate_scope(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
 
@@ -393,6 +429,11 @@ async function context_of(
 }
 
 async function answer(opted_in: OptedIn, exclude: ReadonlyArray<number>): Promise<number> {
+	// The scan has every opted-in body and its labels already, so it keeps `not-before` in line with them
+	// and with every other issue the label is on — before any answer, so a drained backlog or a failed
+	// read still takes a passed label off.
+	await issue_not_before_label.sweep(opted_in.issues)
+
 	if (opted_in.issues.length === 0) return report_none()
 
 	const context = await context_of(opted_in, exclude)
@@ -422,13 +463,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await answer(opted_in, options.exclude ?? [])
 }
 
-// `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.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const backlog_next = {
 	USAGE,
 	REPO_UNREADABLE_MESSAGE,
@@ -441,7 +475,5 @@ const backlog_next = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { backlog_next }
 export type { BacklogVerdict, OptedIn, PoolContext }

package/scripts/backlog/backlog-occupied.ts

@@ -1,56 +1,69 @@
 import type { LaneInfo } from '#scripts/lane/lane-registry'
-import type { RunEvent } from '#scripts/run/event/run-event-stream'
-import { run_invocation } from '#scripts/run/run-invocation'
-import { backlog_drive_restore } from './backlog-drive-restore'
+import type { LaneRecords } from '#scripts/lane/lane-state'
 
 // The open lanes that hold a place under the lane limit — the one count `lane:limit`, the drive and
 // `run:board` all subtract from it.
 //
-// **A lane nobody will come back to holds no place.** A `--only` run works its named list and never
-// touches another lane, so a lane an earlier run left with no child in it would fill the limit for the
-// whole run, and the run's own issues would wait on it for good (joshuafolkken/kit#3967). Under a `--only`
-// run such a lane is not counted; its tree and branch stay, for the next run that names its issue.
+// **A lane with no child working in it holds no place, whatever it waits on** (joshuafolkken/kit#4107).
+// The limit caps the load on the machine, and a lane whose child is gone puts none on it — parked,
+// blocked by another issue, waiting on a decision, or left by an earlier run (joshuafolkken/kit#3967,
+// #4028). Its tree, branch and port seat stay; when its issue is picked up again the drive seats it
+// ahead of a fresh launch, inside the free lanes (`backlog-drive-seats.ts`).
 //
-// **Everything else keeps its place, so the count errs toward fewer free lanes.** A run that drains
-// the pool may offer any open lane's issue again, a lane whose child still works is busy whoever owns
-// it, and with no run there is nobody to judge ownership for. The read stays local — no issue label is
-// read — because the count gates the network read behind it (`backlog-ready.ts`).
-
-interface OccupiedRead {
-	// The live run's invocation, `undefined` when no run is live here.
-	invocation: string | undefined
-	// The live run's own events, for the issues it launched or settled; `undefined` where its scope
-	// could not be told, which leaves every open lane counted.
-	events: ReadonlyArray<RunEvent> | undefined
-	// The issues whose lane has no child working in it; read only for a `--only` run.
-	idle: (lanes: ReadonlyArray<LaneInfo>) => ReadonlyArray<string>
-}
-
-// The issues a `--only` run owns — those it names and those it launched or settled — or `undefined`
-// where there is no such run, or its events could not be scoped to it.
-function owned_issues(read: OccupiedRead): ReadonlySet<string> | undefined {
-	const { invocation, events } = read
-	const is_only = invocation !== undefined && run_invocation.has_only(invocation)
-
-	if (!is_only || events === undefined) return undefined
+// **A paused lane holds no place either** (joshuafolkken/kit#4201): a child `lane:pause` suspended
+// puts no load on the machine until it is resumed. **Paused is the lane state record's answer alone**
+// (joshuafolkken/kit#4270) — the `ps` state is not read — so a lane only `lane:pause` paused is
+// uncounted. Its memory stays held, which the free-memory check reads as measured
+// (`backlog-drive-memory.ts`); `lane:prune` still keeps it, since a child is there (`lane-spent.ts`).
+//
+// **A lane with no record is unknown, and keeps its place**, so the count errs toward fewer free
+// lanes. **Whether a child is there at all is not the record's**:
+// a child that parks or dies writes nothing, so only pgrep's own "no match" (`PROCESS_NONE`,
+// `lane_spent.idle_lanes`) clears a lane, and a probe that did not answer keeps it. A stranded lane has
+// no tree to work in and holds no place either. The reads stay local — no issue label is read —
+// because the count gates the network read behind it (`backlog-ready.ts`).
+//
+// **A lane whose detached ship waits on its merge holds no place either** (joshuafolkken/kit#4466). The
+// child ended at the hand-off, and while `josh followup` runs the supervisor only polls CI, CodeRabbit
+// and the merge, so the slot is free for the next launch while every merge check still runs. The wait is
+// unmarked while the followup stage merges and gates again (`run-ship-sync.ts`); a stop there counts
+// the lane again, and past the limit the supervisor waits for a place before it relaunches the child
+// (`run-ship-return.ts`). A named epic's offer discounts the same lanes (`epic-lane-offer.ts`).
 
-	const named = (run_invocation.issue_numbers(invocation) ?? []).map(String)
+// The issues whose lane has no child working in it (`lane_spent.idle_lanes`).
+type IdleRead = (lanes: ReadonlyArray<LaneInfo>) => ReadonlyArray<string>
+// Whether the lane of an issue has a detached ship waiting on its merge (`lane_handoff.merge_wait_reader`).
+type MergeWaitRead = (issue: string) => boolean
 
-	return new Set([...named, ...backlog_drive_restore.mentioned_issues(events)])
+function is_never_merge_waiting(): boolean {
+	return false
 }
 
-function occupied_lanes(lanes: ReadonlyArray<LaneInfo>, read: OccupiedRead): Array<LaneInfo> {
+function occupied_lanes(
+	lanes: ReadonlyArray<LaneInfo>,
+	idle: IdleRead,
+	records: LaneRecords,
+	is_merge_waiting: MergeWaitRead = is_never_merge_waiting,
+): Array<LaneInfo> {
 	const live = lanes.filter((lane) => !lane.is_stranded)
-	const owned = owned_issues(read)
-
-	if (owned === undefined) return live
+	const idle_issues = new Set(idle(live))
 
-	const idle = new Set(read.idle(live))
+	return live.filter(
+		(lane) =>
+			!idle_issues.has(lane.issue) &&
+			records.get(lane.issue)?.state !== 'paused' &&
+			!is_merge_waiting(lane.issue),
+	)
+}
 
-	return live.filter((lane) => owned.has(lane.issue) || !idle.has(lane.issue))
+/** The issues of the live lanes in `lanes` that have no state record. */
+function unknown_lanes(lanes: ReadonlyArray<LaneInfo>, records: LaneRecords): Array<string> {
+	return lanes
+		.filter((lane) => !lane.is_stranded && !records.has(lane.issue))
+		.map((lane) => lane.issue)
 }
 
-const backlog_occupied = { occupied_lanes }
+const backlog_occupied = { occupied_lanes, unknown_lanes }
 
 export { backlog_occupied }
-export type { OccupiedRead }
+export type { IdleRead, MergeWaitRead }