@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/run/hold/run-stop-notify.ts

@@ -0,0 +1,178 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
+import { git_gh_repo } from '#scripts/gh/git-gh-repo'
+import { git_command } from '#scripts/git/git-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { shell_quote } from '#scripts/lib/shell-quote'
+import { stdout_on_stderr } from '#scripts/lib/stdout-on-stderr'
+import { telegram_test } from '#scripts/notify/telegram-test'
+import type { CliValues } from '#scripts/notify/telegram-test-logic'
+import { run_stage } from '#scripts/run/run-stage'
+import { run_hold_session } from './run-hold-session'
+
+// The `confirmation` a `halfrun`, `needs-human-review` or `prrun` stop sends from `josh run:hold
+// --halfrun-stop` / `--human-review-stop` / `--prrun-stop` (joshuafolkken/kit#4135, #4156): every line is fixed once the Issue, its title and the pull
+// request are known, so it is composed here rather than copied from prose. The send goes through
+// `josh notify`'s own call and is stamped on the hold, so the `Stop` hook's own confirmation
+// (`stop-actions.ts`) finds the pause announced and does not send it again.
+//
+// **A failed send does not fail the stop**: the mark is written, and an unstamped hold is exactly what
+// lets the `Stop` hook send the confirmation in its place.
+
+const TITLE_PLACEHOLDER = '<title>'
+const PR_PLACEHOLDER = '<pr-url>'
+const HALFRUN = 'halfrun'
+const PRRUN = 'prrun'
+
+interface StopFacts {
+	issue: string
+	title: string | undefined
+	issue_url: string | undefined
+	pr_url?: string | undefined
+}
+
+interface Composed {
+	values: CliValues
+	title: string | undefined
+}
+
+// Plain, not linked: every line is a command a person copies out of the Telegram.
+function reference_of(facts: StopFacts): string {
+	return issue_cite.plain(facts.issue)
+}
+
+function commit_title(facts: StopFacts): string {
+	// Single quotes expand nothing, so a title stays one argument whatever it carries.
+	return shell_quote.single_quoted(`${facts.title ?? TITLE_PLACEHOLDER} ${reference_of(facts)}`)
+}
+
+function with_urls(values: CliValues, facts: StopFacts): CliValues {
+	const with_issue =
+		facts.issue_url === undefined ? values : { ...values, 'issue-url': facts.issue_url }
+
+	return facts.pr_url === undefined ? with_issue : { ...with_issue, 'pr-url': facts.pr_url }
+}
+
+function halfrun_values(facts: StopFacts): CliValues {
+	const title = commit_title(facts)
+	const body = [
+		'halfrun ready for manual verification',
+		run_stage.next_line(HALFRUN, facts.issue),
+		`Without an agent: pnpm josh git -y ${title} && pnpm josh followup ${title}`,
+	].join('\n')
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body,
+		recommended: `Verify by hand, then prrun ${reference_of(facts)}`,
+		alternative: [`fullrun ${reference_of(facts)}`],
+	}
+
+	return with_urls(values, facts)
+}
+
+// A `needs-human-review` stop resumes as `halfrun`'s does, so its next line is `halfrun`'s; the lane
+// directory is named because the uncommitted work a person must look at lives only there.
+function human_review_values(facts: StopFacts, directory: string): CliValues {
+	const body = [
+		'needs-human-review: implemented and gated, stopped before the commit',
+		run_stage.next_line(HALFRUN, facts.issue),
+		`Working tree: ${directory}`,
+	].join('\n')
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body,
+		recommended: `Review the working tree, then prrun ${reference_of(facts)}`,
+		alternative: [`fullrun ${reference_of(facts)}`],
+	}
+
+	return with_urls(values, facts)
+}
+
+function prrun_values(facts: StopFacts): CliValues {
+	const body = [
+		`prrun ready to merge: ${facts.pr_url ?? PR_PLACEHOLDER}`,
+		run_stage.next_line(PRRUN, facts.issue),
+		`After a manual merge, without an agent: pnpm josh followup ${commit_title(facts)}`,
+	].join('\n')
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body,
+		recommended: `fullrun ${reference_of(facts)}`,
+		alternative: ['Merge by hand, then pnpm josh followup'],
+	}
+
+	return with_urls(values, facts)
+}
+
+async function issue_facts(issue: string): Promise<StopFacts> {
+	const slug = await git_gh_repo.repo_get_name_with_owner()
+	const title = await git_gh_issue_read.issue_get_title(issue)
+
+	return {
+		issue,
+		title,
+		issue_url: slug === undefined ? undefined : issue_cite.issue_url(slug, issue),
+	}
+}
+
+async function prrun_facts(issue: string): Promise<StopFacts> {
+	const pr_url = await git_gh_pr_read.pr_get_url(await git_command.branch())
+
+	return { ...(await issue_facts(issue)), pr_url }
+}
+
+// The title is passed with the values, so the send does not read it a second time.
+async function send_composed(target: string, compose: () => Promise<Composed>): Promise<void> {
+	const { values, title } = await compose()
+	const titled = title === undefined ? values : { ...values, 'issue-title': title }
+
+	await stdout_on_stderr.run(async () => {
+		await telegram_test.send_values(titled)
+	})
+	run_hold_session.mark_notified(target)
+}
+
+// A `gh` read that fails is a send that did not happen, never a failed stop: the mark is already written.
+async function send(target: string, compose: () => Promise<Composed>): Promise<void> {
+	try {
+		await send_composed(target, compose)
+	} catch (error) {
+		console.error(`⚠️  run:hold could not send the stop confirmation: ${String(error)}`)
+	}
+}
+
+async function send_halfrun(target: string, issue: string): Promise<void> {
+	await send(target, async () => {
+		const facts = await issue_facts(issue)
+
+		return { values: halfrun_values(facts), title: facts.title }
+	})
+}
+
+async function send_prrun(target: string, issue: string): Promise<void> {
+	await send(target, async () => {
+		const facts = await prrun_facts(issue)
+
+		return { values: prrun_values(facts), title: facts.title }
+	})
+}
+
+async function send_human_review(target: string, issue: string): Promise<void> {
+	await send(target, async () => {
+		const facts = await issue_facts(issue)
+		const directory = await git_command.repository_root()
+
+		return { values: human_review_values(facts, directory), title: facts.title }
+	})
+}
+
+const run_stop_notify = {
+	halfrun_values,
+	human_review_values,
+	prrun_values,
+	send_halfrun,
+	send_human_review,
+	send_prrun,
+}
+
+export { run_stop_notify }

package/scripts/run/merge/run-merge-auth.ts

@@ -0,0 +1,31 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+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'
+
+// A returned child whose session could not authenticate (joshuafolkken/kit#4216). Nothing is counted
+// and no label is touched — the child keeps `in-progress`, so it resumes once a person runs `/login` —
+// and the run stops, since every child dispatched before that fails the same way. The stop is pushed
+// as a `confirmation`: `/login` is a person's to run, and the driver's own stop notice names no cause.
+// Script-emitted, so English.
+
+const RECOVERY =
+	'If this did not arrive, `pnpm josh run:wake --list` relays the last progress line.'
+
+async function stop(child: string): Promise<void> {
+	const cite = issue_cite.plain(child)
+	const text = `${cite} could not authenticate — run /login, then resume it`
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.OUTAGE, text)
+	await telegram_notify.confirm({
+		issue_title: 'backlogrun stopped: Claude authentication failed',
+		body: `${text}. The child stays in-progress and was neither parked nor counted as a failure.`,
+		recovery: RECOVERY,
+		recommended: `Run /login, then run backlogrun again to resume ${cite}`,
+		alternatives: ['Leave the backlog stopped until a later session'],
+	})
+}
+
+const run_merge_auth = { stop }
+
+export { run_merge_auth }

package/scripts/run/merge/run-merge-cap.ts

@@ -0,0 +1,57 @@
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_stalled, type StallCause } from '#scripts/run/park/run-stalled'
+import { run_merge_ship } from './run-merge-ship'
+
+// Why a child the per-child re-dispatch cap stopped is parked (joshuafolkken/kit#4765). The cap turns a
+// re-dispatchable ending into `failed`, and the park then named only the ship's stop — never that the cap
+// was reached, how often the child was re-dispatched, or why its last relaunch started nothing.
+
+type Events = ReadonlyArray<RunEvent>
+
+const NO_RELAUNCH_FAILURE = 'none was recorded'
+
+function is_own(event: RunEvent, kind: string, child: string): boolean {
+	return event.kind === kind && run_event_scope.issue_named(event) === child
+}
+
+// Every re-dispatch `child` was counted for, across the run.
+function outages(events: Events, child: string): number {
+	return events.filter((event) => is_own(event, run_event_stream.EVENT_KIND.OUTAGE, child)).length
+}
+
+function last_relaunch_failure(events: Events, child: string): string {
+	const kind = run_event_stream.EVENT_KIND.RELAUNCH_FAILED
+	const failed = events.findLast((event) => is_own(event, kind, child))
+
+	return failed === undefined ? NO_RELAUNCH_FAILURE : failed.text
+}
+
+// The cap's line, put before what the park judged.
+function note_of(events: Events, child: string, limit: number): string {
+	const count = outages(events, child)
+	const failure = last_relaunch_failure(events, child)
+
+	return `it reached the re-dispatch cap (${String(limit)}) after ${String(count)} re-dispatches; the last failed relaunch: ${failure}.`
+}
+
+// What a failed child is parked for: the caller's cause, else its ended ship's, else the unfinished
+// session — led by the cap's line where the cap stopped its re-dispatch. A caller's cause parked the
+// child on its own path, so the cap's line stays off it.
+function park_cause(
+	child: string,
+	cause: StallCause | undefined,
+	note: string | undefined,
+): StallCause {
+	if (cause !== undefined) return cause
+
+	const judged = run_merge_ship.cause(child) ?? run_stalled.SESSION_UNFINISHED
+
+	if (note === undefined) return judged
+
+	return { short: judged.short, why: `${note} ${judged.why}` }
+}
+
+const run_merge_cap = { note_of, outages, park_cause }
+
+export { run_merge_cap }

package/scripts/run/merge/run-merge-cli.ts

@@ -1,20 +1,24 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
-import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { issue_cite } from '#scripts/issue/issue-cite'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_baseline } from '#scripts/lane/lane-baseline'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
-import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { lane_overrun } from '#scripts/lane/lane-overrun'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryOwner, type RunCarry } from '#scripts/run/carry/run-carry'
 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 { run_label } from '#scripts/run/run-label'
+import { run_stalled, type StallCause } from '#scripts/run/park/run-stalled'
 import { run_merge, type ChildOutcome } from './run-merge'
+import { run_merge_auth } from './run-merge-auth'
+import { run_merge_driver } from './run-merge-driver'
 import { run_merge_signals } from './run-merge-signals'
 import { run_merge_steps, type FailedResult, type MergeContext } from './run-merge-steps'
 import { run_merge_token, type MergeToken } from './run-merge-token'
+import { run_merge_usage_limit } from './run-merge-usage-limit'
+import { run_merge_withdrawn, type Collected } from './run-merge-withdrawn'
 
 // `josh run:merge <N>` — one composite command for a `backlogrun` merge event. The parent's context is
 // the largest and its per-turn cost the highest, so it calls this once at a child's return and reads
@@ -26,15 +30,12 @@ import { run_merge_token, type MergeToken } from './run-merge-token'
 // (stop — the child's own ending), `stop` (the consecutive-failure guard tripped, or a failed child could not be parked) and `retry` (the
 // child's state could not be read; re-read before deciding).
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const FIRST = 0
 const MIN_PID = 1
 const { MERGE_TOKEN } = run_merge_token
-const PARK_FAILURE_NOTE = 'The failed child could not be parked with needs-decision; stopping.'
-// The same digit shape `run-carry-args.ts` reads an owner pid under; a count is a bare run of digits.
-const DIGITS = /^\d+$/u
+const PARK_FAILURE_NOTE = `The failed child could not be parked with ${RUN_STALLED_LABEL}; stopping.`
 // A GitHub `owner/repo` slug: an owner and a repository name around a single slash, each starting with
 // an alphanumeric so neither half can begin with `-`. `epic` and `repo` flow into `pnpm josh`
 // subprocess arguments, so a value shaped like an option (`--foo`, or `--evil/x`) would be read as a
@@ -43,9 +44,10 @@ const DIGITS = /^\d+$/u
 // itself forbids (names cannot start with a hyphen) and which the taint analyzer keeps flagging.
 const REPO_PATTERN = /^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*$/u
 const USAGE =
-	'Usage: josh run:merge <issue> [--over <deprecated>] [--epic <E> --repo <owner/repo>] [--owner <pid>] [--output <path>]'
+	'Usage: josh run:merge <issue> [--over <deprecated>] [--epic <E> --repo <owner/repo>] [--owner <pid>] [--output <path>] [--driver]'
 
 const OPTIONS = {
+	driver: { type: 'boolean' },
 	epic: { type: 'string' },
 	output: { type: 'string' },
 	over: { type: 'string' },
@@ -55,7 +57,9 @@ const OPTIONS = {
 
 interface ParsedArguments {
 	positionals: ReadonlyArray<string>
-	values: Partial<Record<'epic' | 'output' | 'over' | 'owner' | 'repo', string>>
+	values: Partial<Record<'epic' | 'output' | 'over' | 'owner' | 'repo', string>> & {
+		driver?: boolean
+	}
 }
 
 // Absent owner is "no owner declared", which the carry guard reads as not provably foreign; a present
@@ -63,11 +67,10 @@ interface ParsedArguments {
 function to_owner(raw: string | undefined): CarryOwner | undefined {
 	if (raw === undefined) return run_carry.NO_OWNER
 
-	if (!DIGITS.test(raw)) return undefined
-
-	const pid = Number(raw)
+	// The same count shape `run-carry-args.ts` reads an owner pid under.
+	const pid = cli_flags.to_count(raw)
 
-	return pid < MIN_PID ? undefined : run_carry.owner_of(pid)
+	return pid === undefined || pid < MIN_PID ? undefined : run_carry.owner_of(pid)
 }
 
 // The epic form needs a repository (`epic:next --lanes` refuses without one), so an epic named with
@@ -116,7 +119,7 @@ function has_invalid_offer(values: ParsedArguments['values']): boolean {
 function has_invalid_legacy_over(raw: string | undefined): boolean {
 	if (raw === undefined) return false
 
-	return !DIGITS.test(raw) || !Number.isSafeInteger(Number(raw))
+	return cli_flags.to_count(raw) === undefined
 }
 
 function valid_child(parsed: ParsedArguments): string | undefined {
@@ -127,6 +130,11 @@ function valid_child(parsed: ParsedArguments): string | undefined {
 	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(child) ? child : undefined
 }
 
+// `backlog:drive` has no context to cut, so its merge is never handed back `over`.
+function cut_check_of(values: ParsedArguments['values']): true | undefined {
+	return values.driver === true ? undefined : true
+}
+
 function to_context(parsed: ParsedArguments): MergeContext | undefined {
 	if (has_invalid_offer(parsed.values) || has_invalid_legacy_over(parsed.values.over)) {
 		return undefined
@@ -144,7 +152,7 @@ function to_context(parsed: ParsedArguments): MergeContext | undefined {
 		child,
 		epic: valid_epic(parsed.values.epic),
 		repo: valid_repo(parsed.values.repo),
-		over: CONTEXT_CUT_THRESHOLD,
+		over: cut_check_of(parsed.values),
 		owner,
 		output: parsed.values.output,
 	}
@@ -156,8 +164,8 @@ function parse(argv: ReadonlyArray<string>): MergeContext | undefined {
 	return parsed === undefined ? undefined : to_context(parsed)
 }
 
-// One handled return: the stdout token and the exit code. Returned rather than printed, so the
-// in-process caller (`backlog:drive`) reads the same verdict the CLI prints.
+// One handled return: the stdout token and the exit code. Returned rather than printed, so
+// `merge_child` carries the verdict to `run_merge_driver.printed`, which prints it.
 interface ControlVerdict {
 	token: MergeToken
 	code: number
@@ -183,8 +191,13 @@ function emit(token: MergeToken, code: number): ControlVerdict {
 	return { token, code, is_offer: false }
 }
 
+// No threshold is `backlog:drive`, which asks `backlog:offer` itself in the pass that collected the
+// child: `backlog:next` here would only hold back its next launch (joshuafolkken/kit#4406).
 async function offered(ctx: MergeContext): Promise<OfferVerdict> {
-	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE, is_offer: true }
+	const token =
+		ctx.over === undefined ? run_merge_driver.DEFERRED_OFFER : await run_merge_steps.ask_next(ctx)
+
+	return { token, code: SUCCESS_EXIT_CODE, is_offer: true }
 }
 
 // A refused count means this session is not the carry record's owner, so the whole operation is
@@ -195,21 +208,32 @@ function report_count_refused(carry: RunCarry | undefined): MergeVerdict {
 	return emit(MERGE_TOKEN.BUSY, FAILURE_EXIT_CODE)
 }
 
-// A merged child counted and its lane closed, the merge put on the stream and in the ledger. Returns the
-// carry when the ownership check refused it, `undefined` once recorded. `run:carry --end` records the
-// merges a run ended with through it too (`run-merge-collect.ts`).
-async function record_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
-	const refused = await run_merge_steps.do_merged(ctx)
+async function is_on_record(text: string): Promise<boolean> {
+	const events = await run_event_stream_emit.invocation_or_all_events()
 
-	if (refused !== undefined) return refused
-
-	await run_event_stream_emit.emit(
-		run_event_stream.EVENT_KIND.MERGE,
-		`${issue_cite.plain(ctx.child)} merged`,
+	return events.some(
+		(event) => event.kind === run_event_stream.EVENT_KIND.MERGE && event.text === text,
 	)
-	await lane_ledger.record_merge(Number(ctx.child))
+}
+
+// **Put on record once, dated to the merge's confirmation**: a pass that collects a child already on
+// record — `run:carry --end` after `run:merge` — writes neither again.
+async function put_merge_on_record(child: string, at: Date): Promise<void> {
+	const text = `${issue_cite.plain(child)} merged`
+
+	if (await is_on_record(text)) return
 
-	return undefined
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.MERGE, text, at)
+	await lane_ledger_write.record_merge(Number(child), at)
+}
+
+// A merged child counted and its lane closed, the merge put on the stream and in the ledger ahead of the
+// lane close, dated to the ownership check rather than to the end of the sync (joshuafolkken/kit#4734). Returns the
+// carry when the ownership check refused it, `undefined` once recorded. `run:carry --end` records the
+// merges a run ended with through it too (`run-merge-collect.ts`). The lane's `ended` record is
+// `lane:close`'s alone: an `incomplete` close leaves the lane open on it (joshuafolkken/kit#4300).
+async function record_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
+	return await run_merge_steps.do_merged(ctx, put_merge_on_record)
 }
 
 // A merge is the only outcome that asks the hand-off check, because it is the only one that returned
@@ -219,6 +243,9 @@ async function on_merged(ctx: MergeContext): Promise<MergeVerdict> {
 
 	if (refused !== undefined) return report_count_refused(refused)
 
+	await lane_overrun.investigate(Number(ctx.child))
+	await lane_baseline.investigate(Number(ctx.child))
+
 	if (await run_merge_steps.is_over_budget(ctx.over)) {
 		return emit(MERGE_TOKEN.OVER, SUCCESS_EXIT_CODE)
 	}
@@ -226,16 +253,13 @@ async function on_merged(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
-// A child released to wait on its open blockers: settled for this run like a parked one, so it goes on
-// the stream the same way, but nothing was counted — the failure guard is not read, and the next child
-// is offered.
-async function on_waiting(
-	ctx: MergeContext,
-	blockers: ReadonlyArray<string>,
-): Promise<MergeVerdict> {
+// A child released to wait on its open blockers or its start date: settled for this run like a parked
+// one, so it goes on the stream the same way, but nothing was counted — the failure guard is not read,
+// and the next child is offered.
+async function on_waiting(ctx: MergeContext, waits: ReadonlyArray<string>): Promise<MergeVerdict> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.PARK,
-		`${issue_cite.plain(ctx.child)} waiting on ${blockers.join(', ')}`,
+		`${issue_cite.plain(ctx.child)} waiting on ${waits.join(', ')}`,
 	)
 
 	return await offered(ctx)
@@ -248,9 +272,11 @@ async function on_parked_failure(ctx: MergeContext, result: FailedResult): Promi
 		return emit(MERGE_TOKEN.STOP, FAILURE_EXIT_CODE)
 	}
 
+	const cause = result.cause ?? run_stalled.SESSION_UNFINISHED.short
+
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.PARK,
-		`${issue_cite.plain(ctx.child)} parked (needs-decision)`,
+		run_stalled.park_event(ctx.child, cause),
 	)
 
 	if (result.carry !== undefined && run_merge.is_guard_tripped(result.carry.failures)) {
@@ -260,12 +286,12 @@ async function on_parked_failure(ctx: MergeContext, result: FailedResult): Promi
 	return await offered(ctx)
 }
 
-async function on_failed(ctx: MergeContext, cause?: string): Promise<MergeVerdict> {
+async function on_failed(ctx: MergeContext, cause?: StallCause): Promise<MergeVerdict> {
 	const result = await run_merge_steps.do_failed(ctx, cause)
 
 	if (result.is_refused) return report_count_refused(result.carry)
 
-	if (result.blockers.length > 0) return await on_waiting(ctx, result.blockers)
+	if (result.waits.length > 0) return await on_waiting(ctx, result.waits)
 
 	return await on_parked_failure(ctx, result)
 }
@@ -290,6 +316,22 @@ async function on_outage(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
+// A child whose session could not authenticate: the run stops with nothing counted or parked
+// (`run-merge-auth.ts`).
+async function on_unauthenticated(ctx: MergeContext): Promise<MergeVerdict> {
+	await run_merge_auth.stop(ctx.child)
+
+	return emit(MERGE_TOKEN.ENVIRONMENT, SUCCESS_EXIT_CODE)
+}
+
+// A child a usage limit stopped: released uncounted, its reset recorded (`run-merge-usage-limit.ts`).
+async function on_usage_limit(ctx: MergeContext): Promise<MergeVerdict> {
+	await run_merge_steps.release_child(ctx.child)
+	await run_merge_usage_limit.record(ctx.child, ctx.resume_ms ?? Date.now())
+
+	return await offered(ctx)
+}
+
 // A child that ended its session with a cut no successor adopted: its successor is relaunched,
 // nothing is counted and nothing is parked, and `resumed` tells the parent to await the same lane
 // again rather than dispatch into it. A successor that could not be started — or a cut the
@@ -301,7 +343,7 @@ async function on_cut(ctx: MergeContext): Promise<MergeVerdict> {
 	if (refused !== undefined) return report_count_refused(refused)
 
 	if (!(await run_merge_steps.resume_cut(ctx.child))) {
-		return await on_failed(ctx, run_merge_steps.CUT_RELAUNCH_CAUSE)
+		return await on_failed(ctx, run_stalled.CUT_NOT_RELAUNCHED)
 	}
 
 	await run_event_stream_emit.emit(
@@ -314,10 +356,10 @@ async function on_cut(ctx: MergeContext): Promise<MergeVerdict> {
 
 // A child that parked itself: nothing is counted, but the park is written to the stream as a failed
 // child's is, so a reader restoring the run from its events sees the child settled. Its `in-progress`
-// is dropped as a failed child's is: left on, it would outlive the `needs-decision` a person later
-// lifts, and a `run:solo` child would then hold the whole backlog.
+// is dropped as a failed child's is: left on, it would outlive the park label a person later
+// lifts, and a `run:solo` child would then hold the whole backlog. A lane it left empty is closed.
 async function on_parked(ctx: MergeContext): Promise<MergeVerdict> {
-	await run_label.unmark(ctx.child)
+	await run_merge_steps.release_child(ctx.child)
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.PARK,
 		`${issue_cite.plain(ctx.child)} parked`,
@@ -338,13 +380,29 @@ async function on_skipped(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
-// A child a person withdrew with `lane:withdraw`: the withdrawal already stopped it, closed its issue
-// and lane and put itself on the stream, so nothing is counted or written here and its seat goes to the
-// next child.
-async function on_withdrawn(ctx: MergeContext): Promise<MergeVerdict> {
+// The seat of a child whose lane was collected goes to the next child — or a retry, where the
+// withdrawal could not read the child.
+async function on_collected(ctx: MergeContext, collected: Collected): Promise<MergeVerdict> {
+	if (collected.note !== undefined) console.error(collected.note)
+	if (collected.is_retry) return emit(MERGE_TOKEN.RETRY, FAILURE_EXIT_CODE)
+
 	return await offered(ctx)
 }
 
+// A child a person withdrew with `lane:withdraw`, or whose issue closed without a merge: nothing is
+// counted and no merge is put on record, and its lane is withdrawn unless a person already did
+// (`run-merge-withdrawn.ts`).
+async function on_withdrawn(ctx: MergeContext): Promise<MergeVerdict> {
+	return await on_collected(ctx, await run_merge_withdrawn.collect(ctx.child))
+}
+
+// A child that gave its lane back on its `lane:plan` (`lane-yield.ts`): its lane is closed the same way,
+// but the issue stays in the run — `backlog:drive` does not exclude a `yielded` child, and its kept
+// plan holds it back until the holder ends.
+async function on_yielded(ctx: MergeContext): Promise<MergeVerdict> {
+	return await on_collected(ctx, await run_merge_withdrawn.collect_yield(ctx.child))
+}
+
 // The child's own ending: it stopped before its commit for a person to look at, so nothing is counted
 // and no next child is offered.
 async function on_human_review(): Promise<MergeVerdict> {
@@ -366,15 +424,19 @@ const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<Mer
 	'human-review': on_human_review,
 	merged: on_merged,
 	outage: on_outage,
+	unauthenticated: on_unauthenticated,
+	'usage-limit': on_usage_limit,
 	parked: on_parked,
 	split: on_skipped,
 	unresolved: on_unresolved,
 	shipping: on_shipping,
 	withdrawn: on_withdrawn,
+	yielded: on_yielded,
 }
 
-// The whole merge event for one returned child, in-process: read its state, classify it, and run the
-// handler. The CLI prints the token; `backlog:drive` branches on the outcome.
+// The whole merge event for one returned child: read its state, classify it, and run the handler.
+// The CLI prints the token and the outcome; `backlog:drive` runs it as a child process
+// (`run-merge-driver.ts`) and branches on the printed outcome.
 async function merge_child(ctx: MergeContext): Promise<MergeResult> {
 	if (lane_handoff.is_ship_running(ctx.child, process.cwd())) {
 		return { outcome: 'shipping', ...(await on_shipping()) }
@@ -384,9 +446,10 @@ async function merge_child(ctx: MergeContext): Promise<MergeResult> {
 	const signals = await run_merge_signals.read_signals(ctx, read)
 	const outcome = run_merge_signals.outcome_of(read, signals)
 
-	const { merged_pr, is_unanswered } = signals
+	const { merged_pr, is_streak_exempt, capped_note, resume_ms } = signals
+	const handled = { ...ctx, merged_pr, is_streak_exempt, capped_note, resume_ms }
 
-	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr, is_unanswered })) }
+	return { outcome, ...(await HANDLERS[outcome](handled)) }
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -400,15 +463,11 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	const result = await merge_child(ctx)
 
-	console.info(result.token)
+	console.info(run_merge_driver.printed(argv, result))
 
 	return result.code
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_merge_cli = {
 	merge_child,
 	parse,
@@ -417,7 +476,5 @@ const run_merge_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { MergeResult }
 export { run_merge_cli }