@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/backlog/backlog-drive.ts

@@ -17,45 +17,23 @@
 // without a process, a network or a clock.
 
 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 { backlog_drive_seats } from './backlog-drive-seats'
+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_launch_pass, type DriveLaunch } from './backlog-drive-launch-pass'
+import { backlog_drive_memory } from './backlog-drive-memory'
+import { backlog_drive_paused } from './backlog-drive-paused'
+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([
@@ -65,17 +43,19 @@ const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
 	'wait',
 ])
 const NO_RETRIES = 0
-const NO_FREE_LANES = 0
 const EXHAUSTED_ANSWER = 'exhausted'
 const JUDGE_REASON = 'judge'
-const LAUNCHED = 'launched'
-const UNOPENED = 'unopened'
+// The `hold` reason a pass held by a Claude usage limit records.
+const USAGE_LIMIT_REASON = 'usage-limit'
+const { launch_all } = backlog_drive_launch_pass
 
-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 +78,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,19 +100,40 @@ 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).
-	launch: (issue: string) => Promise<LaunchOutcome['kind']>
+	// Where `lane:launch`'s chain ended — `launched`, `unopened` (no lane taken) or `failed` (one taken) —
+	// or `measured`, the issue closed by its declaration with no lane taken.
+	launch: (issue: string) => Promise<DriveLaunch>
 	// 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>
+	// Whether a Claude usage limit that stopped a child has yet to reset — `run_merge_usage_limit.is_held`
+	// in production (joshuafolkken/kit#4745).
+	usage_limited: () => 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 +157,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 {
-	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 {
+// 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 === STOP_VERDICT &&
+		read.verdict === verdict &&
 		read.answer === EXHAUSTED_ANSWER &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
@@ -196,10 +191,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,66 +248,19 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 		current = result.state
 	}
 
-	return { kind: 'continue', state: current }
-}
-
-// A `lane:open` refused with every lane taken is a wait, not a judgement: the
-// next offer after a lane frees retries it. A step failing after the lane opened is always handed back —
-// that lane holds the last seat itself, so the free count would read the failure as a full pool.
-async function refused(
-	issue: string,
-	outcome: LaunchOutcome['kind'],
-	state: DriveState,
-	ports: DrivePorts,
-): Promise<PassResult> {
-	if (outcome !== UNOPENED) return ended('launch', state, undefined, issue)
-	if ((await ports.free_lanes()) <= NO_FREE_LANES) return { kind: 'continue', state }
-
-	return ended('launch', state, undefined, issue)
-}
-
-// **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.
-//
-// **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.
-function launched(state: DriveState, in_flight: Array<string>, ports: DrivePorts): DriveState {
-	if (in_flight.length === state.in_flight.length) return { ...state, in_flight }
-
-	return { ...state, in_flight, active: ports.now().toISOString() }
-}
-
-async function launch_all(
-	issues: ReadonlyArray<string>,
-	state: DriveState,
-	ports: DrivePorts,
-): Promise<PassResult> {
-	const in_flight = [...state.in_flight]
-
-	const launching = await backlog_drive_seats.seated(issues, ports)
+	await backlog_drive_hold.stopped(state, current, ports)
 
-	for (const issue of launching) {
-		// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
-		const outcome = await ports.launch(issue)
-
-		if (outcome !== LAUNCHED) {
-			// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
-			return await refused(issue, outcome, launched(state, in_flight, ports), ports)
-		}
-
-		in_flight.push(issue)
-	}
-
-	return { kind: 'continue', state: launched(state, in_flight, ports) }
+	return { kind: 'continue', state: current }
 }
 
 // A watch with nothing in flight is the drain: `run:step` owes the retrospective there, so it is the
 // 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 +274,53 @@ 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 }
+}
+
+async function usage_held(state: DriveState, ports: DrivePorts): Promise<PassResult> {
+	await ports.hold(USAGE_LIMIT_REASON)
 
 	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
+// An offer answered `run`: launched while the machine has memory to spare and no usage limit is in
+// force, held until both hold otherwise. A usage-limited pass polls on as a held one does.
+async function run_offered(
+	issues: ReadonlyArray<string>,
+	state: DriveState,
+	ports: DrivePorts,
+): Promise<PassResult> {
+	if (await ports.usage_limited()) return await usage_held(state, ports)
 
-	if (!is_exhausted || (await ports.free_lanes()) <= NO_FREE_LANES) return false
+	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 run_offered(read.issues, next, ports)
+	if (await backlog_drive_judge.is_owed(read, ports)) return ended(JUDGE_REASON, next, JUDGE_REASON)
 
-	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)
+	const idle = await backlog_drive_idle.noticed(on_verdict(read, next), read, ports)
+	const result = await backlog_drive_paused.noticed(idle, read, ports)
 
-	return on_verdict(read, next)
+	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 +337,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 +380,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)
@@ -460,6 +424,7 @@ async function run_loop(
 const backlog_drive = {
 	HANDOFF_TOKENS,
 	TOKEN_HANDLING,
+	USAGE_LIMIT_REASON,
 	initial_state,
 	merge_stopped,
 	run_loop,

package/scripts/backlog/backlog-gate-scope.ts

@@ -0,0 +1,61 @@
+import type { OptedInRead, TrackingRead } from '#scripts/auto-ok/auto-ok-cli'
+import { epic_graph } from '#scripts/epic/epic-graph'
+import { epic_index } from '#scripts/epic/epic-index'
+import { lane_plan } from '#scripts/lane/lane-plan'
+import { lane_state } from '#scripts/lane/lane-state'
+import { backlog_plan_comment } from './backlog-plan-comment'
+import { backlog_pool } from './backlog-pool'
+import type { GateScope } from './backlog-rank'
+
+type OptedIn = Extract<OptedInRead, { kind: 'read' }>
+type Tracking = Extract<TrackingRead, { kind: 'read' }>
+
+// Everything the answer is assembled from, read once and passed down rather than re-fetched.
+interface PoolContext {
+	opted_in: OptedIn
+	tracking: Tracking
+	repo: string
+	exclude: ReadonlyArray<number>
+}
+
+// The rows the offer's cap bounds — the standalone half.
+function standalone_keys(context: PoolContext): ReadonlySet<string> {
+	return backlog_pool.standalone_keys(context.opted_in.issues, {
+		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
+		exclude: context.exclude,
+		repo: context.repo,
+	})
+}
+
+// The issues whose lane yielded on a plan it kept (`lane-yield.ts`) — offered first (`backlog-rank.ts`,
+// joshuafolkken/kit#5107).
+function yielded_keys(context: PoolContext, directory: string): ReadonlySet<string> {
+	const yielded = context.opted_in.issues.filter((issue) =>
+		lane_plan.is_yielded(issue.number, directory),
+	)
+
+	return new Set(yielded.map(({ number }) => epic_graph.key_of({ number, repo: context.repo })))
+}
+
+// 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. Their lane state
+// records name a paused holder in the wait it causes (joshuafolkken/kit#4270); they are local files.
+// A lane's recorded plan (joshuafolkken/kit#4864), else a plan comment (joshuafolkken/kit#4923), is
+// read in place of the body (joshuafolkken/kit#4937).
+async function gate_scope(context: PoolContext): Promise<GateScope> {
+	const { issues } = context.opted_in
+	const directory = process.cwd()
+
+	return {
+		standalone: standalone_keys(context),
+		declared: await backlog_plan_comment.declared_of(issues, directory),
+		lanes: await lane_state.read_states(issues.map((issue) => String(issue.number))),
+		yielded: yielded_keys(context, directory),
+	}
+}
+
+const backlog_gate_scope = { gate_scope }
+
+export { backlog_gate_scope }
+export type { OptedIn, PoolContext }

package/scripts/backlog/backlog-measure-close.ts

@@ -0,0 +1,112 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_measured_close } from '#scripts/issue/issue-measured-close'
+import {
+	measure_declaration,
+	type MeasureDeclaration,
+	type MeasureVerdict,
+} from '#scripts/issue/measure-declaration'
+import { trusted_measure, type CommandRun } from '#scripts/issue/trusted-measure'
+import { error_text } from '#scripts/lib/error-message'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+
+// joshuafolkken/kit#4621: the drive runs a due issue's measurement declaration (`measure-declaration.ts`)
+// before it opens a lane. A value within the bound closes the issue the way `issue:measured` does — the
+// result comment, the `measured` label, the close and the epic's progress — and puts a `measured` event
+// on the stream, so no lane is spent. Anything else — no declaration, an untrusted body, a value out of
+// bound, a failed command, output that is not one number — launches the lane as before; where a
+// command ran, its result is commented first, so the child starts from the measurement, not a re-run.
+
+const FENCE = '```'
+const VERDICT_WORDS: Readonly<Record<MeasureVerdict['kind'], string>> = {
+	pass: 'within the bound, so the issue is closed without a lane.',
+	fail: 'out of the bound, so the issue goes to a lane.',
+	unreadable: 'no value could be read from the output, so the issue goes to a lane.',
+}
+
+interface Measurement {
+	declaration: MeasureDeclaration
+	run: CommandRun
+	verdict: MeasureVerdict
+}
+
+async function declared(issue: string): Promise<MeasureDeclaration | undefined> {
+	const read = await trusted_measure.read_trusted_body(issue)
+
+	return read.kind === 'trusted' ? measure_declaration.parse(read.body) : undefined
+}
+
+function measured(declaration: MeasureDeclaration): Measurement {
+	const run = trusted_measure.run_command(declaration.command)
+	const verdict: MeasureVerdict =
+		run.kind === 'ok' ? measure_declaration.judge(declaration, run.output) : { kind: 'unreadable' }
+
+	return { declaration, run, verdict }
+}
+
+function value_words(verdict: MeasureVerdict): string {
+	return verdict.kind === 'unreadable' ? 'unreadable' : String(verdict.value)
+}
+
+// The result comment: the declaration, the value read, what follows and the command's own output.
+// Script-emitted, so English (`run-merge.ts` → `park_comment`).
+function report(measurement: Measurement): string {
+	const { declaration, run, verdict } = measurement
+
+	return [
+		'`backlog:drive` ran the measurement declaration.',
+		'',
+		`- Declaration: ${measure_declaration.format(declaration)}`,
+		`- Value: ${value_words(verdict)}`,
+		`- Verdict: ${VERDICT_WORDS[verdict.kind]}`,
+		'',
+		FENCE,
+		trusted_measure.text_of(run),
+		FENCE,
+	].join('\n')
+}
+
+async function close_passed(issue: string, measurement: Measurement): Promise<boolean> {
+	const is_closed = await issue_measured_close.close(issue, report(measurement))
+	const value = value_words(measurement.verdict)
+	const bound = `${measurement.declaration.operator} ${String(measurement.declaration.threshold)}`
+
+	if (is_closed) {
+		await run_event_stream_emit.emit(
+			run_event_stream.EVENT_KIND.MEASURED,
+			`${issue_cite.plain(issue)} measured by backlog:drive: ${value} ${bound}`,
+		)
+	}
+
+	return is_closed
+}
+
+// The result handed to the lane on the issue itself, which the child reads with its comments. A comment
+// that cannot be posted still launches the lane: the child re-runs the declaration.
+async function hand_over(issue: string, measurement: Measurement): Promise<false> {
+	try {
+		await git_gh_command.issue_comment(issue, report(measurement))
+	} catch (error) {
+		console.error(`Measurement result not posted: ${error_text.message_of(error)}`)
+	}
+
+	return false
+}
+
+// Whether the drive closed the issue by its declaration; `false` launches its lane.
+async function closed(issue: string): Promise<boolean> {
+	const declaration = await declared(issue)
+
+	if (declaration === undefined) return false
+
+	const measurement = measured(declaration)
+
+	return measurement.verdict.kind === 'pass'
+		? await close_passed(issue, measurement)
+		: await hand_over(issue, measurement)
+}
+
+const backlog_measure_close = { closed }
+
+export { backlog_measure_close }

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 }