@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/run/event/run-event-overrun.ts

@@ -0,0 +1,197 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+
+// The notes an overrun investigation leaves on the run's event stream (joshuafolkken/kit#4751): every
+// merged lane's net time, at or under the threshold or over it, or why there is none
+// (joshuafolkken/kit#4818); an overrun's start, naming the session's pid and start time; and its end —
+// the session's result or the launch's failure. `lane-overrun.ts` writes them and `run:board` reads them
+// back, both through this module, so the two never spell them differently.
+
+// What a note says of the investigation of `issue`. `start` is the session's `process_identity` start
+// token, which tells the session from a later process holding its pid; a launcher that could not read it
+// leaves it off. A start note that launched no session is a failure with its minutes.
+type OverrunNote =
+	| { kind: 'within'; issue: number; minutes: number }
+	| { kind: 'skipped'; issue: number; reason: string }
+	| {
+			kind: 'started'
+			issue: number
+			minutes: number
+			pid: number
+			start: string | undefined
+			longest: Longest | undefined
+	  }
+	| { kind: 'ended'; issue: number; result: string }
+	| { kind: 'failed'; issue: number; minutes: number | undefined }
+
+// The lane's longest stage in whole minutes (joshuafolkken/kit#4995, `lane-breakdown.ts`); a start note
+// written before it was carried has none.
+interface Longest {
+	name: string
+	minutes: number
+}
+
+type Groups = Partial<Record<string, string>>
+
+const WITHIN_PATTERN = /^#(?<issue>\d+) net: (?<minutes>\d+) min$/u
+const SKIPPED_PATTERN = /^#(?<issue>\d+) overrun skipped: (?<reason>.+)$/u
+const OVERRAN_PATTERN =
+	/^#(?<issue>\d+) overran: (?<minutes>\d+) min net(?:, longest (?<stage>.+?) (?<stage_minutes>\d+) min)? — (?<outcome>.*)$/u
+const INVESTIGATING_PATTERN = /^investigating in pid (?<pid>\d+)(?: started (?<start>.+))?$/u
+const ENDED_PATTERN = /^#(?<issue>\d+) overrun: (?<result>.*)$/u
+const FAILED_PATTERN = /^#(?<issue>\d+) overrun investigation failed: /u
+
+// Why an overrun was skipped with the switch off (joshuafolkken/kit#5044); the board draws it only
+// once the switch is on, hiding every merged row's minutes and skip while it stays off
+// (joshuafolkken/kit#5132, joshuafolkken/kit#5194).
+const DISABLED_REASON = 'disabled (JOSH_LANE_INVESTIGATION is not on)'
+// The result an investigation that filed records; the board shows the filings themselves.
+const FILED_RESULT = 'filed'
+const NONE_LEAD = 'none: '
+// What a result ends with for the stages the investigation judged not reducible (joshuafolkken/kit#4995).
+const NOT_REDUCIBLE_LEAD = '; not reducible: '
+const RECURRED_PATTERN = /^recurred #(?<number>\d+)/u
+// The result of an investigation that appended causes to open Issues, which file no new one
+// (joshuafolkken/kit#4858); any it filed besides show as filings.
+const FOLDED_LEAD = 'folded '
+const FOLDED_SEPARATOR = ','
+const FOLDED_PATTERN = /^folded (?<list>#\d+(?:,#\d+)*)/u
+const NUMBER_PATTERN = /#(?<number>\d+)/gu
+
+function started_text(issue: number, minutes: number, outcome: string, longest?: Longest): string {
+	const stage =
+		longest === undefined ? '' : `, longest ${longest.name} ${String(longest.minutes)} min`
+
+	return `${issue_cite.plain(issue)} overran: ${String(minutes)} min net${stage} — ${outcome}`
+}
+
+function within_text(issue: number, minutes: number): string {
+	return `${issue_cite.plain(issue)} net: ${String(minutes)} min`
+}
+
+function skipped_text(issue: number, reason: string): string {
+	return `${issue_cite.plain(issue)} overrun skipped: ${reason}`
+}
+
+// The start note's outcome for a launched session.
+function investigating(pid: number, start: string | undefined): string {
+	const outcome = `investigating in pid ${String(pid)}`
+
+	return start === undefined ? outcome : `${outcome} started ${start}`
+}
+
+function ended_text(issue: number, result: string): string {
+	return `${issue_cite.plain(issue)} overrun: ${result}`
+}
+
+function failed_text(issue: number, note: string): string {
+	return `${issue_cite.plain(issue)} overrun investigation failed: ${note}`
+}
+
+function none_result(reason: string): string {
+	return `${NONE_LEAD}${reason}`
+}
+
+function recurred_result(issue: number | string): string {
+	return `recurred ${issue_cite.plain(issue)}`
+}
+
+// The issue a `recurred #N` result commented on.
+function recurred_of(result: string): number | undefined {
+	const number = RECURRED_PATTERN.exec(result)?.groups?.['number']
+
+	return number === undefined ? undefined : Number(number)
+}
+
+function folded_result(issues: ReadonlyArray<number | string>): string {
+	return `${FOLDED_LEAD}${issues.map((issue) => issue_cite.plain(issue)).join(FOLDED_SEPARATOR)}`
+}
+
+// The Issues a `folded #A,#B` result appended to, else none; any text after the list is not read.
+function folded_of(result: string): ReadonlyArray<number> {
+	const list = FOLDED_PATTERN.exec(result)?.groups?.['list'] ?? ''
+
+	return [...list.matchAll(NUMBER_PATTERN)].map((match) => Number(match.groups?.['number']))
+}
+
+// The reason a `none: <reason>` result gives, else the result as it is — its stages not reducible left
+// out.
+function reason_of(result: string): string {
+	const [lead = ''] = result.split(NOT_REDUCIBLE_LEAD)
+
+	return lead.startsWith(NONE_LEAD) ? lead.slice(NONE_LEAD.length) : lead
+}
+
+function longest_of(groups: Groups): Longest | undefined {
+	const name = groups['stage']
+
+	return name === undefined ? undefined : { name, minutes: Number(groups['stage_minutes']) }
+}
+
+function overran(groups: Groups): OverrunNote {
+	const issue = Number(groups['issue'])
+	const minutes = Number(groups['minutes'])
+	const launched = INVESTIGATING_PATTERN.exec(groups['outcome'] ?? '')?.groups
+
+	if (launched === undefined) return { kind: 'failed', issue, minutes }
+
+	const pid = Number(launched['pid'])
+	const longest = longest_of(groups)
+
+	return { kind: 'started', issue, minutes, pid, start: launched['start'], longest }
+}
+
+function within(groups: Groups): OverrunNote {
+	return { kind: 'within', issue: Number(groups['issue']), minutes: Number(groups['minutes']) }
+}
+
+function skipped(groups: Groups): OverrunNote {
+	return { kind: 'skipped', issue: Number(groups['issue']), reason: groups['reason'] ?? '' }
+}
+
+function failed(groups: Groups): OverrunNote {
+	return { kind: 'failed', issue: Number(groups['issue']), minutes: undefined }
+}
+
+function ended(groups: Groups): OverrunNote {
+	return { kind: 'ended', issue: Number(groups['issue']), result: groups['result'] ?? '' }
+}
+
+const READERS: ReadonlyArray<readonly [RegExp, (groups: Groups) => OverrunNote]> = [
+	[WITHIN_PATTERN, within],
+	[SKIPPED_PATTERN, skipped],
+	[OVERRAN_PATTERN, overran],
+	[FAILED_PATTERN, failed],
+	[ENDED_PATTERN, ended],
+]
+
+function parse(text: string): OverrunNote | undefined {
+	for (const [pattern, read] of READERS) {
+		const groups = pattern.exec(text)?.groups
+
+		if (groups !== undefined) return read(groups)
+	}
+
+	return undefined
+}
+
+const run_event_overrun = {
+	DISABLED_REASON,
+	ended_text,
+	failed_text,
+	FILED_RESULT,
+	folded_of,
+	folded_result,
+	investigating,
+	none_result,
+	NOT_REDUCIBLE_LEAD,
+	parse,
+	reason_of,
+	recurred_of,
+	recurred_result,
+	skipped_text,
+	started_text,
+	within_text,
+}
+
+export { run_event_overrun }
+export type { Longest, OverrunNote }

package/scripts/run/event/run-event-render.ts

@@ -25,6 +25,7 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	park: { ja: '保留', en: 'parked' },
 	split: { ja: '分割', en: 'split' },
 	outage: { ja: '障害', en: 'outage' },
+	'usage-limit': { ja: '利用上限', en: 'usage limit' },
 	cut: { ja: 'セッション交代', en: 'session cut' },
 	resume: { ja: '実装を再開', en: 'implementation resumed' },
 	restart: { ja: '止めて出し直し', en: 'restarted' },
@@ -40,6 +41,7 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	heartbeat: { ja: '生存確認', en: 'heartbeat' },
 	'ship-launch': { ja: '出荷を開始', en: 'ship launched' },
 	'ship-stop': { ja: '出荷が停止', en: 'ship stopped' },
+	'relaunch-failed': { ja: '再起動に失敗', en: 'relaunch failed' },
 	filed: { ja: '起票', en: 'filed' },
 	note: { ja: '意見', en: 'note' },
 	'lane-phase': { ja: 'レーンの段階', en: 'lane phase' },
@@ -50,6 +52,8 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	'idle-notice': { ja: '待機の通知', en: 'idle notice' },
 	'lane-state': { ja: 'レーンの状態', en: 'lane state' },
 	'paused-notice': { ja: '一時停止の通知', en: 'paused notice' },
+	measured: { ja: '計測で完了', en: 'measured' },
+	sleep: { ja: 'ホストのスリープ', en: 'host sleep' },
 }
 
 const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))

package/scripts/run/event/run-event-stream.ts

@@ -1,4 +1,5 @@
 import { repository_lock } from '#scripts/git/repository-lock'
+import { durable_state } from '#scripts/josh/durable-state'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
@@ -24,7 +25,7 @@ import { z } from 'zod'
 // must never fail the work it reports on, so `run-event-stream-emit.ts` wraps
 // every append in a swallow; this module is free to throw on a genuinely broken write.
 
-const EVENT_PREFIX = 'josh-run-events-'
+const EVENT_PREFIX = durable_state.PREFIX.EVENTS
 // `.jsonl` rather than `.json`: the file is one JSON event per line, appended to, and the suffix tells
 // every reader — a person, an editor — that it is a line stream rather than a single document, the same
 // distinction the ambient `.log` draws.
@@ -56,6 +57,10 @@ const EVENT_KIND = {
 	PARK: 'park',
 	SPLIT: 'split',
 	OUTAGE: 'outage',
+	// A Claude usage limit stopped a lane child (joshuafolkken/kit#4745). Its text names the reset time,
+	// which `backlog:drive` reads to hold launches until then; it counts against no streak, so it is not an
+	// `OUTAGE`.
+	USAGE_LIMIT: 'usage-limit',
 	CUT: 'cut',
 	// A fresh session adopted an implementation cut — `run:cut --resume` answered `resume-impl`. The
 	// resume clears the cut record, so without this the `cut` would stay the newest position and
@@ -116,6 +121,11 @@ const EVENT_KIND = {
 	// The position that hands control back: `run:step` prints the command that
 	// shows the stopped report, so the agent fixes it and relaunches rather than rebuilding the context.
 	SHIP_STOP: 'ship-stop',
+	// The relaunch meant to answer a `SHIP_STOP` started nothing — the broker refused it, or the direct
+	// spawn failed (joshuafolkken/kit#4765). `run:merge` reads it, not the transcript's mtime, to tell the
+	// stop went unanswered, and a re-dispatch cap's park names its reason. A trace: the stop stays the
+	// position `run:step` answers.
+	RELAUNCH_FAILED: 'relaunch-failed',
 	// An Issue the run filed on its way, written by `issue:file`, so a run started from the command line
 	// still surfaces what it found — `run:board`'s findings section reads it.
 	FILED: 'filed',
@@ -157,6 +167,14 @@ const EVENT_KIND = {
 	// silent window (joshuafolkken/kit#4270). Emitted once per pause episode (`emit_once_since_with`,
 	// reset by `LANE_STATE`), it is the dedup marker for the one paused-lane Telegram. A trace.
 	PAUSED_NOTICE: 'paused-notice',
+	// `backlog:drive` ran a due issue's measurement declaration itself, found it within its bound and
+	// closed the issue through `issue:measured` — no lane was launched for it (joshuafolkken/kit#4621).
+	// `run:board` draws it merged. A trace: the parent's position is the drive's, not this close.
+	MEASURED: 'measured',
+	// The host slept while `backlog:drive` sampled its load (joshuafolkken/kit#5032): the sampler's timer
+	// ran late by more than a few intervals. `at` is the wake and `elapsed_ms` how long the sleep
+	// lasted; every lane's net time takes it out (`lane-sleep.ts`). A trace.
+	SLEEP: 'sleep',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -179,6 +197,9 @@ const TRACE_KINDS: ReadonlySet<string> = new Set([
 	EVENT_KIND.IDLE_NOTICE,
 	EVENT_KIND.LANE_STATE,
 	EVENT_KIND.PAUSED_NOTICE,
+	EVENT_KIND.MEASURED,
+	EVENT_KIND.RELAUNCH_FAILED,
+	EVENT_KIND.SLEEP,
 ])
 
 // The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
@@ -199,7 +220,8 @@ const event_schema = z.object({
 	kind: z.string(),
 	text: z.string(),
 	// The child's time on a lane, recorded once by the writer of an ending (joshuafolkken/kit#4481), so a
-	// reader never has to find its launch again. An event written before it has none.
+	// reader never has to find its launch again. An event written before it has none. A `sleep` event
+	// carries the sleep's length here.
 	elapsed_ms: z.number().optional(),
 })
 
@@ -224,7 +246,7 @@ function is_event_kind(value: string): value is EventKind {
 // The stream's path, keyed on the run's identity the caller resolved. `.jsonl` so the append surface is
 // named for what it is.
 function target_of(repository: string): string {
-	return stamp_file.stamp_path(EVENT_PREFIX, repository, EVENT_SUFFIX)
+	return durable_state.path(EVENT_PREFIX, repository, EVENT_SUFFIX)
 }
 
 function is_present(event: RunEvent | undefined): event is RunEvent {

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

@@ -3,6 +3,7 @@ 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'
@@ -22,9 +23,6 @@ const TITLE_PLACEHOLDER = '<title>'
 const PR_PLACEHOLDER = '<pr-url>'
 const HALFRUN = 'halfrun'
 const PRRUN = 'prrun'
-// Single quotes expand nothing, so a title stays one argument whatever it carries; its own `'` closes
-// the quote, emits an escaped one and reopens.
-const QUOTE = "'"
 
 interface StopFacts {
 	issue: string
@@ -38,17 +36,14 @@ interface Composed {
 	title: string | undefined
 }
 
-function single_quoted(text: string): string {
-	return QUOTE + text.replaceAll(QUOTE, String.raw`'\''`) + QUOTE
-}
-
 // 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 {
-	return single_quoted(`${facts.title ?? TITLE_PLACEHOLDER} ${reference_of(facts)}`)
+	// 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 {

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,10 +1,11 @@
-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'
@@ -16,6 +17,8 @@ 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
@@ -128,8 +131,8 @@ function valid_child(parsed: ParsedArguments): string | undefined {
 }
 
 // `backlog:drive` has no context to cut, so its merge is never handed back `over`.
-function threshold_of(values: ParsedArguments['values']): number | undefined {
-	return values.driver === true ? undefined : CONTEXT_CUT_THRESHOLD
+function cut_check_of(values: ParsedArguments['values']): true | undefined {
+	return values.driver === true ? undefined : true
 }
 
 function to_context(parsed: ParsedArguments): MergeContext | undefined {
@@ -149,7 +152,7 @@ function to_context(parsed: ParsedArguments): MergeContext | undefined {
 		child,
 		epic: valid_epic(parsed.values.epic),
 		repo: valid_repo(parsed.values.repo),
-		over: threshold_of(parsed.values),
+		over: cut_check_of(parsed.values),
 		owner,
 		output: parsed.values.output,
 	}
@@ -205,22 +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
+async function is_on_record(text: string): Promise<boolean> {
+	const events = await run_event_stream_emit.invocation_or_all_events()
+
+	return events.some(
+		(event) => event.kind === run_event_stream.EVENT_KIND.MERGE && event.text === text,
+	)
+}
+
+// **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
+
+	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> {
-	const refused = await run_merge_steps.do_merged(ctx)
-
-	if (refused !== undefined) return refused
-
-	await run_event_stream_emit.emit(
-		run_event_stream.EVENT_KIND.MERGE,
-		`${issue_cite.plain(ctx.child)} merged`,
-	)
-	await lane_ledger.record_merge(Number(ctx.child))
-
-	return 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
@@ -230,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)
 	}
@@ -308,6 +324,14 @@ async function on_unauthenticated(ctx: MergeContext): Promise<MergeVerdict> {
 	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
@@ -356,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 lane
-// and put itself on the stream, leaving its issue open for the next run, 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> {
@@ -385,11 +425,13 @@ const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<Mer
 	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: read its state, classify it, and run the handler.
@@ -404,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_streak_exempt } = 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_streak_exempt })) }
+	return { outcome, ...(await HANDLERS[outcome](handled)) }
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

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

@@ -4,12 +4,14 @@
 const CHILD_OUTCOMES = [
 	'merged',
 	'withdrawn',
+	'yielded',
 	'human-review',
 	'parked',
 	'split',
 	'cut',
 	'outage',
 	'unauthenticated',
+	'usage-limit',
 	'failed',
 	'unresolved',
 	'shipping',

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

@@ -75,19 +75,29 @@ function cause(child: string, directory: string = process.cwd()): StallCause | u
 	return cause_of(run_ship_detach.read_result(repository, child), events, child)
 }
 
+function is_relaunch_failed(event: RunEvent): boolean {
+	return event.kind === run_event_stream.EVENT_KIND.RELAUNCH_FAILED
+}
+
 // Whether the ended ship was never answered: a session relaunched to fix a stop writes to the
 // transcript after it, so a transcript last written before the newest stop means no fix-up ran — its
-// broker or relaunch could not start. A ship with no stop at all ended abnormally only when its supervisor
-// died before reaching a stage.
+// broker or relaunch could not start. **A `relaunch-failed` after the stop reads it unanswered whatever the
+// mtime says** (joshuafolkken/kit#4765): the dispatch log's header is written before a spawn that may fail.
+// A ship with no stop at all ended abnormally only when its supervisor died before reaching a stage.
 function is_stop_unanswered(
 	ending: ShipEnding,
 	attempt: Events,
 	written_at: number | undefined,
 ): boolean {
-	const stop = attempt.findLast((event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP)
+	const index = attempt.findLastIndex(
+		(event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP,
+	)
+	const stop = attempt[index]
 
 	if (stop === undefined) return ending?.result === 'abnormal'
 
+	if (attempt.slice(index + 1).some((event) => is_relaunch_failed(event))) return true
+
 	return written_at !== undefined && written_at < Date.parse(stop.at)
 }