@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/backlog/backlog-defect-priority.ts

@@ -5,7 +5,7 @@ import { defect_rate, type DefectRate, type IssueKind } from '#scripts/issue/def
 import { defect_rate_cli } from '#scripts/issue/defect-rate-cli'
 
 // While the defect rate is above its baseline, `backlog:next` offers defects and hardening first and
-// defers new mechanisms (joshuafolkken/kit#2455). The re-ordering stays inside the runnable set — every
+// defers new mechanisms. The re-ordering stays inside the runnable set — every
 // candidate is already ready to start — so no dependency the graph recorded is crossed.
 
 const UNMEASURED_MESSAGE =

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

@@ -1,15 +1,15 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import type { DriveState } from './backlog-drive'
 
 // The `josh backlog:drive` flags — read into a `DriveContext`, and written back as the `resume:` line —
-// split out of `backlog-drive-cli.ts` when it neared its line limit (joshuafolkken/kit#3264).
+// split out of `backlog-drive-cli.ts` when it neared its line limit.
 // `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 ISSUE_PATTERN = /^[1-9]\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>]'
 
@@ -51,7 +51,7 @@ function to_issues(raw: string | undefined): ReadonlyArray<string> | undefined {
 
 	const issues = raw.split(LIST_SEPARATOR)
 
-	return issues.some((issue) => !ISSUE_PATTERN.test(issue)) ? undefined : issues
+	return issues.some((issue) => !issue_number_shape.is_issue_number(issue)) ? undefined : issues
 }
 
 function forwarded_of(values: Values): ReadonlyArray<string> | undefined {
@@ -72,7 +72,8 @@ function is_valid_window(raw: string | undefined): boolean {
 }
 
 function is_valid_single(values: Values): boolean {
-	const is_valid_stopped = values.stopped === undefined || ISSUE_PATTERN.test(values.stopped)
+	const is_valid_stopped =
+		values.stopped === undefined || issue_number_shape.ISSUE_NUMBER_PATTERN.test(values.stopped)
 
 	return is_valid_stopped && is_valid_window(values.window)
 }

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

@@ -1,11 +1,14 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_sampler } from '#scripts/lane/lane-sampler'
 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'
@@ -29,7 +32,7 @@ import { backlog_drive_retrospective } from './backlog-drive-retrospective'
 import { backlog_offer_cli } from './backlog-offer-cli'
 import { backlog_ready } from './backlog-ready'
 
-// `josh backlog:drive` — the backlogrun parent's loop as one resident wait (joshuafolkken/kit#2499).
+// `josh backlog:drive` — the backlogrun parent's loop as one resident wait.
 // The parent issues it once, in the background, and is woken only when it exits — with a token the model
 // has to read. The loop itself is `backlog-drive.ts`; this file is its ports onto the commands it reuses.
 //
@@ -58,13 +61,7 @@ const offer_read_schema = z.object({
 const offer_schema = z.object({ [backlog_offer_cli.JSON_KEY]: offer_read_schema })
 
 function to_offer(out: string): OfferRead | undefined {
-	try {
-		const parsed = offer_schema.safeParse(JSON.parse(out))
-
-		return parsed.success ? parsed.data[backlog_offer_cli.JSON_KEY] : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(out, offer_schema)?.[backlog_offer_cli.JSON_KEY]
 }
 
 async function read_record(): Promise<RunCarry | undefined> {
@@ -110,7 +107,7 @@ function merge_token(out: string, code: number): string {
 
 // 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 (joshuafolkken/kit#3156).
+// supervisor runs this loop, and a process has no context to cut.
 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)
@@ -165,7 +162,7 @@ async function open_lanes(): Promise<ReadonlyArray<string>> {
 
 function end_line(end: DriveEnd): string {
 	const token = end.token === undefined || end.token === end.reason ? [] : [end.token]
-	const issue = end.issue === undefined ? [] : [`#${end.issue}`]
+	const issue = end.issue === undefined ? [] : [issue_cite.plain(end.issue)]
 	const base = [end.reason, ...token, ...issue].join(' ')
 
 	return end.detail === undefined ? base : `${base} ${end.detail}`
@@ -224,13 +221,19 @@ async function drive(context: DriveContext): Promise<number> {
 	return SUCCESS_EXIT_CODE
 }
 
+// The machine load is sampled for exactly as long as the drive runs, so a `backlogrun` leaves its own
+// load in the lane ledger without a sampler anyone has to start or stop (`lane-sampler.ts`).
 async function run_safe(context: DriveContext): Promise<number> {
+	const stop_sampling = lane_sampler.start()
+
 	try {
 		return await drive(context)
 	} catch (error) {
 		console.info(`error ${error_text.message_of(error)}`)
 
 		return FAILURE_EXIT_CODE
+	} finally {
+		stop_sampling()
 	}
 }
 
@@ -260,6 +263,7 @@ const backlog_drive_cli = {
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse: backlog_drive_args.parse,
 	resume_line: backlog_drive_args.resume_line,
+	run,
 	to_offer,
 }
 

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

@@ -0,0 +1,85 @@
+import { git_gh_repo } from '#scripts/gh/git-gh-repo'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { josh_command } from '#scripts/josh/josh-run'
+import type { DriveState, OfferRead } from './backlog-drive'
+import { backlog_drive_named } from './backlog-drive-named'
+import { backlog_offer } from './backlog-offer'
+
+// A named epic is driven from the epic itself. The work list is the epic's
+// current children as `epic:next` derives them, never a copy in the carry record — so a child filed
+// into the epic mid-run, by any route (`issue:file`, `epic --add`, a hand edit), is dispatched once it
+// is runnable, without `run:add` and without waking a parent session.
+//
+// **Only what needs a person is handed back.** `stop` means every child left waits on a person, which a
+// judgment session reads. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
+// undeclared order, an unreadable child), and its exit code does not tell them apart — so a failure is
+// a `wait` that retries on the next pass, and `backlog:offer`'s consecutive-retry limit of them hands the
+// epic back too, rather than waiting out the idle budget on an anomaly nobody is shown.
+
+const NO_RETRIES = 0
+const SUCCESS_EXIT_CODE = 0
+const FIRST_LINE = 0
+const WAIT: OfferRead = { verdict: 'wait', issues: [], retries: NO_RETRIES }
+
+// `--lanes` lists every child a free lane could take, so one the loop already knows about is passed
+// over rather than standing in front of the rest. `undefined` is an answer that could not be read.
+async function ask_next(epic: string): Promise<ReadonlyArray<string> | undefined> {
+	const repo = await git_gh_repo.repo_get_name_with_owner()
+	if (repo === undefined) return undefined
+	const result = await josh_command.josh_run(['epic:next', epic, '--repo', repo, '--lanes'], true)
+
+	return result.code === SUCCESS_EXIT_CODE ? result.out.trim().split('\n') : undefined
+}
+
+function handed_back(epic: string): OfferRead {
+	return { ...WAIT, verdict: `epic ${issue_cite.plain(epic)}` }
+}
+
+function failed_offer(epic: string, state: DriveState): OfferRead {
+	const retries = state.retries + 1
+
+	return retries >= backlog_offer.RETRY_LIMIT ? handed_back(epic) : { ...WAIT, retries }
+}
+
+// A child the loop already launched, or merged and excluded, can still read as runnable while GitHub
+// catches up, so it is skipped rather than launched twice. One child per offer
+// keeps the carried maximum checked before each launch.
+function child_offer(children: ReadonlyArray<string>, state: DriveState): OfferRead {
+	const child = children.find(
+		(item) => !state.in_flight.includes(item) && !state.exclude.includes(item),
+	)
+
+	return child === undefined ? WAIT : { verdict: 'run', issues: [child], retries: NO_RETRIES }
+}
+
+async function answered_offer(
+	epic: string,
+	answers: ReadonlyArray<string>,
+	state: DriveState,
+	owner: string,
+): Promise<OfferRead> {
+	const token = answers[FIRST_LINE]
+
+	if (token !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) {
+		return child_offer(answers, state)
+	}
+
+	if (token === 'stop') return handed_back(epic)
+
+	if (token === 'complete') {
+		await backlog_drive_named.mark_done(epic, { outcome: 'merged', code: 0, token: 'none' }, owner)
+	}
+
+	return WAIT
+}
+
+async function offer(epic: string, state: DriveState, owner: string): Promise<OfferRead> {
+	const answers = await ask_next(epic)
+
+	return answers === undefined
+		? failed_offer(epic, state)
+		: await answered_offer(epic, answers, state, owner)
+}
+
+export const backlog_drive_epic = { offer }

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

@@ -2,7 +2,7 @@ import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
 import { backlog_drive_owner } from './backlog-drive-owner'
 
-// The driver's lane launch (joshuafolkken/kit#3272). The parent that ran `josh latest` in the primary
+// The driver's lane launch. The parent that ran `josh latest` in the primary
 // checkout leaves its rewritten lock file in a stash under this message — `backlogrun-lanes.md` →
 // "Once per repository, before the first lane opens" — and the lane that pops it carries the update
 // into its pull request. **The stash itself is the "first lane" marker**: each launch asks whether it

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -1,10 +1,14 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { EPIC_LABEL, has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_added } from '#scripts/run/carry/run-carry-added'
 import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
+import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
+import { backlog_drive_epic } from './backlog-drive-epic'
 import { backlog_drive_named } from './backlog-drive-named'
 
 interface NamedContext {
@@ -47,15 +51,20 @@ function budget_offer(
 }
 
 // The outcome a named issue has already reached without this run dispatching it: closed is merged, and
-// a `needs-decision` park waits on a person, so re-dispatching it only repeats the stop it parked on
-// (joshuafolkken/kit#2965). Either is booked done rather than offered.
+// a `needs-decision` park waits on a person, so re-dispatching it only repeats the stop it parked on.
+// Either is booked done rather than offered.
 function settled_outcome(state: IssueState): MergeResult['outcome'] | undefined {
 	if (state.state.toUpperCase() === 'CLOSED') return 'merged'
 
 	return has_label_name(state.labels, NEEDS_DECISION_LABEL) ? 'parked' : undefined
 }
 
-async function classify(issue: string, named: OfferRead, owner: string): Promise<OfferRead> {
+async function classify(
+	issue: string,
+	named: OfferRead,
+	state: DriveState,
+	owner: string,
+): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
 	if (result.kind !== 'state') return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
@@ -68,11 +77,53 @@ async function classify(issue: string, named: OfferRead, owner: string): Promise
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}
 
-	if (has_label_name(result.state.labels, EPIC_LABEL)) {
-		return { verdict: `epic #${issue}`, issues: [], retries: NO_RETRIES }
-	}
+	return has_label_name(result.state.labels, EPIC_LABEL)
+		? await backlog_drive_epic.offer(issue, state, owner)
+		: named
+}
+
+// **A named issue booked done is not thereby merged**: a park and a failure are
+// booked done too, so the run moves past them. One the run's own merges did not record and GitHub does
+// not read as closed ended without a merge — and an unreadable state counts as that, because a false
+// stop reaches a person while a false finish ends the run where nobody sees it.
+async function is_unmerged(issue: number, merged: ReadonlyArray<number>): Promise<boolean> {
+	if (merged.includes(issue)) return false
+
+	const result = await issue_state_cli.read_issue(String(issue))
+
+	return result.kind !== 'state' || result.state.state.toUpperCase() !== 'CLOSED'
+}
+
+// The issues `run:add` put in count too: one that parked is no more a merge
+// than a declared one.
+async function unmerged_of(carry: RunCarry): Promise<Array<number>> {
+	const declared = run_carry_added.ordered(
+		run_invocation.issue_numbers(carry.invocation) ?? [],
+		carry.added,
+	)
+	const merged = carry.merged_issues ?? []
+	const flags = await Promise.all(declared.map(async (issue) => await is_unmerged(issue, merged)))
+
+	return declared.filter((_, index) => flags[index] === true)
+}
+
+// The `--only` run's end: a finish when every named issue merged, otherwise a stop naming the ones that
+// did not, which `backlog-drive-finish.ts` closes with `run:carry --end --stopped` and its ⏸️ notice.
+async function only_end(carry: RunCarry, named: OfferRead): Promise<OfferRead> {
+	const unmerged = await unmerged_of(carry)
+
+	if (unmerged.length === 0) return named
+
+	const listed = unmerged.map((issue) => issue_cite.plain(issue)).join(', ')
 
-	return named
+	return { ...named, reason: `only: ${listed} ended without a merge`, is_finish: false }
+}
+
+async function not_run(
+	carry: RunCarry,
+	named: OfferRead | undefined,
+): Promise<OfferRead | undefined> {
+	return named?.is_finish === true ? await only_end(carry, named) : named
 }
 
 async function read(
@@ -81,12 +132,12 @@ async function read(
 	context: NamedContext,
 ): Promise<OfferRead | undefined> {
 	const named = backlog_drive_named.offer(carry, state, context.is_only)
-	if (named?.verdict !== 'run') return named
+	if (named?.verdict !== 'run') return await not_run(carry, named)
 	const budget = budget_offer(carry, state, context.forwarded)
 	if (budget.verdict !== 'run') return budget
 	const [issue] = named.issues
 
-	return issue === undefined ? undefined : await classify(issue, named, context.owner)
+	return issue === undefined ? undefined : await classify(issue, named, state, context.owner)
 }
 
 export const backlog_drive_named_offer = { read }

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

@@ -3,16 +3,39 @@ import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 import type { RunEvent } from '#scripts/run/event/run-event-stream'
 import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
+import { run_merge_token } from '#scripts/run/merge/run-merge-token'
+import { run_invocation } from '#scripts/run/run-invocation'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_restore } from './backlog-drive-restore'
 import { backlog_named } from './backlog-named'
 
+const { MERGE_TOKEN } = run_merge_token
+
 const NO_RETRIES = 0
 const FIRST = 0
 const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split'])
 
+// The skip follows the declared order alone: an issue `run:add` put in was
+// asked for on its own, so its failure skips nothing and a declared failure does not skip it.
+function is_declared(carry: RunCarry, issue: string): boolean {
+	return run_invocation.issue_numbers(carry.invocation)?.includes(Number(issue)) === true
+}
+
+// An issue `run:add` put in that is already in flight holds nothing up: it was
+// asked for on its own, so the declared item behind it — an epic whose children fill the free lanes —
+// is offered beside it. A declared issue in flight still holds the ones declared after it.
+function is_held(carry: RunCarry, state: DriveState, issue: number): boolean {
+	return !state.in_flight.includes(String(issue)) || is_declared(carry, String(issue))
+}
+
+function next_of(carry: RunCarry, state: DriveState): number | undefined {
+	const remaining = run_carry.remaining_of(carry) ?? []
+
+	return remaining.find((issue) => is_held(carry, state, issue)) ?? remaining[FIRST]
+}
+
 function offer(carry: RunCarry, state: DriveState, is_only: boolean): OfferRead | undefined {
-	const next = run_carry.remaining_of(carry)?.[FIRST]
+	const next = next_of(carry, state)
 
 	if (next !== undefined) {
 		const issue = String(next)
@@ -28,9 +51,11 @@ function offer(carry: RunCarry, state: DriveState, is_only: boolean): OfferRead
 }
 
 function is_done(result: MergeResult): boolean {
-	if (TERMINAL_OUTCOMES.has(result.outcome)) return result.code === 0 && result.token !== 'busy'
+	if (TERMINAL_OUTCOMES.has(result.outcome)) {
+		return result.code === 0 && result.token !== MERGE_TOKEN.BUSY
+	}
 
-	return result.outcome === 'failed' && result.code === 0 && result.token !== 'stop'
+	return result.outcome === 'failed' && result.code === 0 && result.token !== MERGE_TOKEN.STOP
 }
 
 function can_mark(carry: RunCarry, issue: string, owner: string): boolean {
@@ -48,17 +73,22 @@ function mark_one(target: string, issue: string, owner: string): boolean {
 	return true
 }
 
-function skip_after_failure(target: string, issue: string, owner: string): void {
-	const read = run_carry.read_carry(target)
-	if (read.kind !== 'carried') return
-	const remaining = run_carry.remaining_of(read.carry) ?? []
+function skipped_of(carry: RunCarry, issue: string): ReadonlyArray<number> {
+	if (!is_declared(carry, issue)) return []
+	const remaining = run_carry.remaining_of({ ...carry, added: undefined }) ?? []
 	const named = [
 		{ issue: Number(issue), is_epic: false },
 		...remaining.map((number) => ({ issue: number, is_epic: false })),
 	]
-	const { skipped } = backlog_named.after_failure(named, Number(issue))
 
-	for (const number of skipped) {
+	return backlog_named.after_failure(named, Number(issue)).skipped
+}
+
+function skip_after_failure(target: string, issue: string, owner: string): void {
+	const read = run_carry.read_carry(target)
+	if (read.kind !== 'carried') return
+
+	for (const number of skipped_of(read.carry, issue)) {
 		if (!mark_one(target, String(number), owner)) return
 	}
 }

package/scripts/backlog/backlog-drive-offer-argv.ts

@@ -3,7 +3,7 @@ import type { DriveState } from './backlog-drive'
 
 const LIST_SEPARATOR = ','
 
-// **A child in flight is never offered** (joshuafolkken/kit#3156). A lane child merges its own PR and
+// **A child in flight is never offered**. A lane child merges its own PR and
 // drops `in-progress` before GitHub closes the issue and before the loop collects it, so `backlog:next`
 // can offer it again; launching it then is refused by its still-open lane and handed to an AI session.
 function excluded(state: DriveState): ReadonlyArray<string> {

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

@@ -64,4 +64,4 @@ function restore(
 	return lanes.filter((issue) => active.has(issue) && !merged_issues.includes(Number(issue)))
 }
 
-export const backlog_drive_restore = { restore, settled_issues, parked_issues }
+export const backlog_drive_restore = { active_issues, restore, settled_issues, parked_issues }

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

@@ -4,8 +4,8 @@ import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_retrospective } from '#scripts/run/run-retrospective'
 
 // Whether a drain owes the retrospective, read through the owed rule `run:step` reads, so a drain it
-// owes nothing at keeps the idle watch rather than waking a session with nothing to run
-// (joshuafolkken/kit#2750). The drive is the parent's loop, never a lane child's.
+// owes nothing at keeps the idle watch rather than waking a session with nothing to run.
+// The drive is the parent's loop, never a lane child's.
 function is_owed(carry: RunCarry): boolean {
 	const root = find_package_directory(process.cwd())
 

package/scripts/backlog/backlog-drive.ts

@@ -1,10 +1,10 @@
 // The body of `josh backlog:drive`: the backlogrun parent's mechanical transitions, run as one resident
-// wait instead of a model turn per event (joshuafolkken/kit#2499).
+// wait instead of a model turn per event.
 //
-// **What it replaces is the parent's turn between two commands.** Measured after #2492 the parent still
-// spent about half of its backlogrun requests on nothing but glue: a child's process ends, the model
-// wakes, runs `run:merge`, reads a number, runs `lane:launch`, restarts `lane:await`, ends its turn — or,
-// headless, polls in the foreground because its turn cannot end. Every one of those steps is a command
+// **What it replaces is the parent's turn between two commands.** Without it the parent spends about
+// half of its backlogrun requests on nothing but glue: a child's process ends, the model wakes, runs
+// `run:merge`, reads a number, runs `lane:launch`, restarts `lane:await`, ends its turn — or, headless,
+// polls in the foreground because its turn cannot end. Every one of those steps is a command
 // whose answer is already a token, so the loop here only reads tokens and never decides what one means.
 //
 // **It decides nothing another command answers.** Collecting a child is `run:merge`'s, choosing the next
@@ -16,25 +16,40 @@
 // **Everything it touches is a port**, the pattern `run-wake-loop.ts` set, so the sequencing is pinned
 // 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'
 
+const { MERGE_TOKEN } = run_merge_token
 const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
-// The `run:merge` tokens that end the loop at once: a hand-off, a person's stop, the environment down,
-// a foreign owner, an unreadable state. `resumed` is not among them — the same lane is awaited again.
-const IMMEDIATE_TOKENS: ReadonlySet<string> = new Set([
-	'over',
-	'human-review',
-	'environment',
-	'busy',
-	'retry',
-])
-// Every token `run:merge` prints first even on a non-zero exit. `stop` — a parked backlog or the failure
-// guard — is the offer's `stop` reached through a merge: the child is collected, nothing more starts,
-// and the children still in flight are collected before the loop ends (joshuafolkken/kit#2881).
-const HANDOFF_TOKENS: ReadonlySet<string> = new Set([...IMMEDIATE_TOKENS, STOP_VERDICT])
-const RESUMED_TOKEN = 'resumed'
+// 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` — a parked backlog or the
+// failure guard — is the offer's `stop` reached through a merge: the child is collected, nothing more
+// starts, and the children still in flight are collected before the loop ends. `await` is a cut resumed
+// in place: the same lane is awaited again.
+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'
 const WATCH_VERDICT = 'watch'
 // The verdicts the loop acts on without the parent. Any other is handed back as it was printed.
@@ -56,7 +71,7 @@ interface OfferRead {
 	answer?: 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 (joshuafolkken/kit#2750).
+	// reads as not owed, so a drain with the switch off keeps the idle watch.
 	is_retrospective_owed?: boolean
 	is_finish?: boolean | undefined
 }
@@ -65,8 +80,7 @@ interface DriveState {
 	// The children this run has in flight — seeded from the open lanes, so a restarted loop resumes them.
 	in_flight: Array<string>
 	// Every child merged, fed back to `backlog:offer` because GitHub closes a merged issue late. A parked
-	// child is left out: its labels classify it, so one a person released is offered again
-	// (joshuafolkken/kit#3041).
+	// child is left out: its labels classify it, so one a person released is offered again.
 	exclude: Array<string>
 	// When the run last did something, handed to `backlog:budget` as `--active`.
 	active: string
@@ -160,7 +174,7 @@ function merge_stopped(issue: string, state: DriveState): DriveState {
 	return {
 		...state,
 		is_stopping: true,
-		stop_reason: `run:merge #${issue} answered stop`,
+		stop_reason: `run:merge ${issue_cite.plain(issue)} answered stop`,
 		stopped_by: issue,
 	}
 }
@@ -181,7 +195,7 @@ function collected_state(
 	active: string,
 ): DriveState {
 	const in_flight =
-		collected.token === RESUMED_TOKEN
+		collected.token === MERGE_TOKEN.RESUMED
 			? state.in_flight
 			: state.in_flight.filter((item) => item !== issue)
 	const exclude = excluded(issue, collected.outcome, state)
@@ -200,7 +214,7 @@ async function collect(issue: string, state: DriveState, ports: DrivePorts): Pro
 
 	const next = collected_state(issue, collected, state, ports.now().toISOString())
 
-	return { kind: 'continue', state: token === STOP_VERDICT ? merge_stopped(issue, next) : next }
+	return { kind: 'continue', state: token === MERGE_TOKEN.STOP ? merge_stopped(issue, next) : next }
 }
 
 async function collect_finished(state: DriveState, ports: DrivePorts): Promise<PassResult> {
@@ -219,7 +233,7 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 	return { kind: 'continue', state: current }
 }
 
-// A `lane:open` refused with every lane taken is a wait, not a judgement (joshuafolkken/kit#3027): the
+// 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(
@@ -234,12 +248,12 @@ async function refused(
 	return ended('launch', state, undefined, issue)
 }
 
-// **No more launches than free lanes** (joshuafolkken/kit#3027). `backlog:offer` lists every ready issue
+// **No more launches 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. The free count is read once, before the first launch, because every launch here opens
 // a lane the count would otherwise have to be told about.
 //
-// **Only a launch is activity** (joshuafolkken/kit#3027): a pass that started nothing — every lane taken
+// **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 }
@@ -410,6 +424,7 @@ async function run_loop(
 
 const backlog_drive = {
 	HANDOFF_TOKENS,
+	TOKEN_HANDLING,
 	initial_state,
 	merge_stopped,
 	run_loop,