@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,5 +1,6 @@
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import type { DriveState } from './backlog-drive'
 
 // The `josh backlog:drive` flags — read into a `DriveContext`, and written back as the `resume:` line —
@@ -7,9 +8,7 @@ import type { DriveState } from './backlog-drive'
 // `backlog_drive_cli` re-exports `parse` and `resume_line` under the names they always had, so the move
 // changed no call site and no suite that reads them through `backlog_drive_cli`.
 
-const MS_PER_MINUTE = 60_000
 const LIST_SEPARATOR = ','
-const COUNT_PATTERN = /^\d+$/u
 const USAGE =
 	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>] [--stopped <n>]'
 
@@ -57,7 +56,7 @@ function to_issues(raw: string | undefined): ReadonlyArray<string> | undefined {
 function forwarded_of(values: Values): ReadonlyArray<string> | undefined {
 	const pairs = (['max', 'idle'] as const).filter((name) => values[name] !== undefined)
 
-	if (pairs.some((name) => !COUNT_PATTERN.test(values[name] ?? ''))) return undefined
+	if (pairs.some((name) => cli_flags.to_count(values[name]) === undefined)) return undefined
 
 	return pairs.flatMap((name) => [`--${name}`, values[name] ?? ''])
 }
@@ -68,7 +67,7 @@ function window_of(raw: string | undefined): number | undefined {
 }
 
 function is_valid_window(raw: string | undefined): boolean {
-	return raw === undefined || COUNT_PATTERN.test(raw)
+	return raw === undefined || cli_flags.to_count(raw) !== undefined
 }
 
 function is_valid_single(values: Values): boolean {
@@ -81,7 +80,7 @@ function is_valid_single(values: Values): boolean {
 function owner_of(values: Values | undefined): string | undefined {
 	const owner = values?.owner
 
-	return owner !== undefined && COUNT_PATTERN.test(owner) ? owner : undefined
+	return cli_flags.to_count(owner) === undefined ? undefined : owner
 }
 
 function to_context(values: Values, owner: string): DriveContext | undefined {

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

@@ -12,7 +12,8 @@ import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
 import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
-import { run_merge_cli, type MergeResult } from '#scripts/run/merge/run-merge-cli'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
+import { run_merge_driver } from '#scripts/run/merge/run-merge-driver'
 import { z } from 'zod'
 import { backlog_budget } from './backlog-budget'
 import {
@@ -23,14 +24,19 @@ import {
 	type LoopPorts,
 	type OfferRead,
 } from './backlog-drive'
+import { backlog_drive_adopt } from './backlog-drive-adopt'
 import { backlog_drive_args, type DriveContext } from './backlog-drive-args'
 import { backlog_drive_carried } from './backlog-drive-carried'
 import { backlog_drive_finish } from './backlog-drive-finish'
+import { backlog_drive_hold, type HoldRecorder } from './backlog-drive-hold'
+import { backlog_drive_idle } from './backlog-drive-idle'
 import { backlog_drive_launch } from './backlog-drive-launch'
+import { backlog_drive_memory } from './backlog-drive-memory'
 import { backlog_drive_named } from './backlog-drive-named'
 import { backlog_drive_named_offer } from './backlog-drive-named-offer'
 import { backlog_drive_offer_argv } from './backlog-drive-offer-argv'
 import { backlog_drive_owner } from './backlog-drive-owner'
+import { backlog_drive_paused } from './backlog-drive-paused'
 import { backlog_drive_restore } from './backlog-drive-restore'
 import { backlog_drive_retrospective } from './backlog-drive-retrospective'
 import { backlog_drive_seats } from './backlog-drive-seats'
@@ -59,6 +65,8 @@ const offer_read_schema = z.object({
 	issues: z.array(z.string()),
 	retries: z.number(),
 	answer: z.string().optional(),
+	cause: z.string().optional(),
+	waiting: z.array(z.number()).optional(),
 	reason: z.string().optional(),
 	is_finish: z.boolean().optional(),
 })
@@ -106,20 +114,21 @@ function merge_token(out: string, code: number): string {
 	return ''
 }
 
+// A `run:merge` that printed no result — a crash before its verdict — answers no token, which the loop
+// never reads as a collection.
+function unprinted(code: number): MergeResult {
+	return { token: '', code, is_offer: true, outcome: 'unresolved' }
+}
+
 // The child's transcript, where its lane recorded one, so `run:merge` can tell an API outage from a
-// failure exactly as it does for the parent that passes `--output` by hand. No hand-off threshold: the
-// supervisor runs this loop, and a process has no context to cut.
+// failure exactly as it does for the parent that passes `--output` by hand. Run as its own process
+// (`run-merge-driver.ts`), so a fix merged since this loop started is the code that decides the child.
 async function merge(issue: string, owner: string): Promise<MergeResult> {
 	await backlog_drive_owner.assert_current(owner)
 	const lane = await lane_registry.find_open_lane(issue)
-	const result = await run_merge_cli.merge_child({
-		child: issue,
-		epic: undefined,
-		repo: undefined,
-		over: undefined,
-		owner: run_carry.owner_of(Number(owner)),
-		output: lane?.output,
-	})
+	const argv = run_merge_driver.argv_of({ child: issue, owner, output: lane?.output })
+	const ran = await josh_command.josh_run(argv, should_forward_stderr)
+	const result = run_merge_driver.read(ran.out) ?? unprinted(ran.code)
 
 	await backlog_drive_named.mark_done(issue, result, owner)
 
@@ -130,17 +139,18 @@ async function merge(issue: string, owner: string): Promise<MergeResult> {
 // a restart after it ended — is read as having appeared, so it is collected after the re-confirm window
 // rather than waited on until the never-appeared timeout. One that never appeared is collected too:
 // `run:merge` reads its state rather than this loop guessing.
-function finished_checker(seeded: ReadonlyArray<string>): (issue: string) => boolean {
+function finished_checker(seeded: ReadonlySet<string>): (issue: string) => boolean {
 	const states = new Map<string, AwaitState>()
 	const config = {
 		is_running: lane_await.is_process_running_default,
+		is_shipped: lane_await.is_shipped_default,
 		reconfirm_ms: lane_await.RECONFIRM_MS,
 		never_appeared_timeout_ms: lane_await.NEVER_APPEARED_TIMEOUT_MS,
 	}
 
 	return (issue: string): boolean => {
 		const state = states.get(issue) ?? {
-			appeared: seeded.includes(issue),
+			appeared: seeded.has(issue),
 			disappeared_at: undefined,
 			first_polled_at: undefined,
 		}
@@ -181,19 +191,61 @@ function judgement_reader(): () => Promise<number> {
 	}
 }
 
+// The reports an offered pass leaves: why it started nothing, the idle notice and the paused notice.
+function reporters(holds: HoldRecorder): Pick<LoopPorts, 'hold' | 'idle' | 'paused'> {
+	return {
+		hold: holds.hold,
+		idle: backlog_drive_idle.notify,
+		paused: async () => {
+			await backlog_drive_paused.notify()
+		},
+	}
+}
+
+// What a launch is weighed against: the free lanes, a kept lane, and the memory for one more.
+function room_ports(): Pick<LoopPorts, 'free_lanes' | 'has_lane' | 'limit_room' | 'memory_held'> {
+	return {
+		free_lanes: backlog_ready.drive_free_lane_count,
+		limit_room: backlog_ready.drive_limit_room,
+		has_lane: backlog_drive_seats.has_kept_lane,
+		memory_held: backlog_drive_memory.gauge(),
+	}
+}
+
+// The children's ports. An adopted lane was dispatched like a seeded one, so a child already gone is
+// collected rather than waited on until the never-appeared timeout.
+function child_ports(
+	seeded: ReadonlyArray<string>,
+	owner: string,
+): Pick<LoopPorts, 'adoptable' | 'is_finished' | 'merge'> {
+	const known = new Set(seeded)
+
+	return {
+		is_finished: finished_checker(known),
+		merge: async (issue) => await merge(issue, owner),
+		adoptable: async (in_flight) => {
+			const adopting = await backlog_drive_adopt.adoptable(in_flight)
+
+			for (const issue of adopting) known.add(issue)
+
+			return adopting
+		},
+	}
+}
+
 function ports_of(
 	context: DriveContext,
 	seeded: ReadonlyArray<string>,
 	last: { state: DriveState },
+	holds: HoldRecorder,
 ): LoopPorts {
 	return {
-		is_finished: finished_checker(seeded),
-		merge: async (issue) => await merge(issue, context.owner),
+		...child_ports(seeded, context.owner),
 		offer: async (state) => await read_offer(state, context),
 		launch: async (issue) => await backlog_drive_launch.launch(issue, context.owner),
-		free_lanes: backlog_ready.drive_free_lane_count,
-		has_lane: backlog_drive_seats.has_kept_lane,
+		...room_ports(),
 		judgement_owed: judgement_reader(),
+		...reporters(holds),
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
 			await sleep(milliseconds)
@@ -205,7 +257,15 @@ function ports_of(
 	}
 }
 
-async function seeded_lanes(context: DriveContext): Promise<ReadonlyArray<string> | undefined> {
+// The lanes still in flight, and the children this run withdrew: a withdrawal while the drive was
+// handed back is never collected by this invocation, so its exclusion is read from the stream
+// (joshuafolkken/kit#4365).
+interface Seeded {
+	lanes: ReadonlyArray<string>
+	withdrawn: ReadonlyArray<string>
+}
+
+async function seeded_lanes(context: DriveContext): Promise<Seeded | undefined> {
 	const carry = await read_record()
 
 	if (carry === undefined) return undefined
@@ -216,9 +276,13 @@ async function seeded_lanes(context: DriveContext): Promise<ReadonlyArray<string
 
 	const open = await open_lanes()
 	const lanes = [...new Set([...open.map((lane) => lane.issue), ...context.awaited])]
-	const dispatched = await backlog_drive_carried.carried(open)
+	const carried = await backlog_drive_carried.carried(open)
+	const dispatched = backlog_drive_named.own_carried(carry, carried, context.is_only)
 
-	return backlog_drive_restore.restore(lanes, events, carry.merged_issues ?? [], dispatched)
+	return {
+		lanes: backlog_drive_restore.restore(lanes, events, carry.merged_issues ?? [], dispatched),
+		withdrawn: backlog_drive_restore.withdrawn_issues(events),
+	}
 }
 
 // The interval between two asks is `backlog:budget`'s own, so the driver keeps the one its reason prints.
@@ -226,19 +290,39 @@ function loop_config(window_ms: number | undefined): LoopConfig {
 	return { poll_ms: POLL_MS, offer_ms: backlog_budget.OFFER_INTERVAL_MS, window_ms }
 }
 
+// The hand-back, the ledger's hold included — the lanes now wait on a session — and the resume line.
+async function report_end(
+	end: DriveEnd,
+	state: DriveState,
+	context: DriveContext,
+	holds: HoldRecorder,
+): Promise<void> {
+	await holds.end(end)
+	console.info(end_line(end))
+	console.info(backlog_drive_args.resume_line(state, context))
+}
+
+function seeded_state(seeded: Seeded, context: DriveContext): DriveState {
+	const fresh = backlog_drive.initial_state(
+		seeded.lanes,
+		context.active ?? new Date().toISOString(),
+	)
+	const initial =
+		context.stopped === undefined ? fresh : backlog_drive.merge_stopped(context.stopped, fresh)
+
+	return { ...initial, exclude: [...new Set([...context.exclude, ...seeded.withdrawn])] }
+}
+
 async function drive(context: DriveContext): Promise<number> {
 	const seeded = await seeded_lanes(context)
 
 	if (seeded === undefined) return FAILURE_EXIT_CODE
-	const fresh = backlog_drive.initial_state(seeded, context.active ?? new Date().toISOString())
-	const initial =
-		context.stopped === undefined ? fresh : backlog_drive.merge_stopped(context.stopped, fresh)
-	const last = { state: { ...initial, exclude: [...context.exclude] } }
-	const config = loop_config(context.window_ms)
-	const end = await backlog_drive.run_loop(last.state, config, ports_of(context, seeded, last))
+	const last = { state: seeded_state(seeded, context) }
+	const holds = backlog_drive_hold.recorder()
+	const ports = ports_of(context, seeded.lanes, last, holds)
+	const end = await backlog_drive.run_loop(last.state, loop_config(context.window_ms), ports)
 
-	console.info(end_line(end))
-	console.info(backlog_drive_args.resume_line(last.state, context))
+	await report_end(end, last.state, context, holds)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -288,6 +372,7 @@ const backlog_drive_cli = {
 	read_offer,
 	resume_line: backlog_drive_args.resume_line,
 	run,
+	seeded_state,
 	to_offer,
 }
 

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

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

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

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

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

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