@joshuafolkken/kit 1.2116.0 → 1.3041.0

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

@@ -0,0 +1,137 @@
+import { mkdtemp, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { issue_body_keys } from '#scripts/issue/issue-body-keys'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { PRIORITY_CRITICAL_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { run_event_filed } from '#scripts/run/event/run-event-filed'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { execa } from 'execa'
+
+// The failure guard's check (joshuafolkken/kit#7078): a streak of failed children asks whether `main`
+// itself is broken by running CI's whole-tree verification there — `pnpm josh gate` alone reads only a
+// branch's changed files, which on `main` are none. Green, the failures are the children's own — each
+// already parked — and the run goes on. Red twice in a row (one red can be a memory-pressure flake,
+// `backlogrun-lanes.md`), kit's own verification is broken for every lane, so a `run:solo` Issue is
+// filed; the backlog runs it alone and holds every other launch until it has merged
+// (`backlogrun-lanes.md` → "A solo run"). Either way nobody is waited on. One filing stands until the
+// next merge, so a streak still red is not filed twice. The child processes' output is captured, so
+// `run:merge`'s stdout stays its one token. Script-emitted, so English.
+
+interface HealthCheck {
+	args: ReadonlyArray<string>
+	env: Readonly<Record<string, string>>
+}
+
+const TITLE = 'Repair the verification gate failing on main'
+const OUTPUT_TAIL_LINES = 20
+// CI's split: the static gate, whole-tree under `CI`, and the whole unit suite on its own.
+const STATIC_CHECK: HealthCheck = { args: ['josh', 'gate', '--no-unit'], env: { CI: 'true' } }
+const UNIT_CHECK: HealthCheck = { args: ['josh', 'test:unit'], env: {} }
+const COMMANDS = '`CI=true pnpm josh gate --no-unit` and `pnpm josh test:unit`'
+
+function is_filed(events: ReadonlyArray<RunEvent>): boolean {
+	return run_event_stream
+		.since(events, run_event_stream.EVENT_KIND.MERGE)
+		.some(
+			(event) =>
+				event.kind === run_event_stream.EVENT_KIND.FILED &&
+				run_event_filed.parse(event.text)?.title === TITLE,
+		)
+}
+
+// The lines `issue:file` requires of a defect whose origin is unknown (`issue:file --check`).
+const DECLARATIONS = [
+	issue_body_keys.heading('background'),
+	'',
+	issue_body_keys.line('kind', 'bug'),
+	issue_body_keys.line('purpose', 'bug_fix'),
+	issue_body_keys.line('judgement', 'not_needed'),
+	`${issue_body_keys.line('origin', 'unknown')}（found by the backlogrun health check, not traced yet）`,
+	`${issue_body_keys.prefix('size')} ${issue_body_keys.size_value('1', '20')}`,
+]
+const SYMPTOM = [
+	issue_body_keys.heading('symptom'),
+	'',
+	`${COMMANDS} fail on \`main\`, twice in a row.`,
+]
+const EXPECTED = [
+	issue_body_keys.heading('expected'),
+	'',
+	`${COMMANDS} pass on \`main\`.`,
+	'',
+	issue_body_keys.heading('criteria'),
+	'',
+	`- [ ] ${COMMANDS} pass on \`main\`.`,
+]
+
+function body_of(child: string, output: string): string {
+	const tail = output.split('\n').slice(-OUTPUT_TAIL_LINES).join('\n')
+	const origin = `Filed by \`pnpm josh run:merge\` after ${issue_cite.plain_for('github', child)}: a streak of children failed, and the whole-tree verification on \`main\` failed too, so it is broken for every lane.`
+	const reproduction = [
+		issue_body_keys.heading('reproduction'),
+		'',
+		`${COMMANDS} on \`main\`:`,
+		'',
+		'```text',
+		tail,
+		'```',
+	]
+
+	return [...DECLARATIONS, '', origin, '', ...SYMPTOM, '', ...reproduction, '', ...EXPECTED].join(
+		'\n',
+	)
+}
+
+async function file_solo(child: string, output: string): Promise<void> {
+	const directory = await mkdtemp(path.join(tmpdir(), 'josh-health-'))
+	const body_file = path.join(directory, 'body.md')
+	const answers = ['--defect', 'yes', '--verification', 'yes', '--every-run', 'yes']
+	const labels = ['--label', RUN_SOLO_LABEL, '--label', PRIORITY_CRITICAL_LABEL]
+
+	await writeFile(body_file, body_of(child, output))
+	const filing = await execa(
+		'pnpm',
+		['josh', 'issue:file', TITLE, '--body-file', body_file, ...labels, ...answers, '--over-cap'],
+		{ reject: false, all: true, stdin: 'ignore' },
+	)
+
+	if (filing.exitCode !== 0) {
+		console.error(`run:merge: the run:solo Issue was not filed:\n${filing.all}`)
+	}
+}
+
+// The red check's output, or `undefined` when it passed.
+async function red_output(health_check: HealthCheck): Promise<string | undefined> {
+	const result = await execa('pnpm', health_check.args, {
+		reject: false,
+		all: true,
+		stdin: 'ignore',
+		env: health_check.env,
+	})
+
+	return result.exitCode === 0 ? undefined : result.all
+}
+
+async function verification_red(): Promise<string | undefined> {
+	return (await red_output(STATIC_CHECK)) ?? (await red_output(UNIT_CHECK))
+}
+
+// Runs the whole-tree verification on the checkout `run:merge` stands in — `main`, after the parent's
+// sync — and files the solo Issue when it is red twice. Answers whether `main` was green.
+async function check(child: string): Promise<boolean> {
+	if ((await verification_red()) === undefined) return true
+
+	const output = await verification_red()
+
+	if (output === undefined) return true
+
+	if (!is_filed(await run_event_stream_emit.current_events())) await file_solo(child, output)
+
+	return false
+}
+
+const run_merge_health = { TITLE, check }
+
+export { run_merge_health }

package/scripts/run/merge/run-merge-human-review.ts

@@ -0,0 +1,26 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { lane_state } from '#scripts/lane/lane-state'
+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 child may exit before its stop marker: retain its lane before settling its dispatch.
+async function retain(issue: string): Promise<boolean> {
+	const retained = await lane_state.record_change({
+		issue,
+		state: 'human-review',
+		command: 'run:merge',
+	})
+
+	if (retained.kind !== 'written') return false
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.HUMAN_REVIEW,
+		`${issue_cite.plain_for('program', issue)} waiting for human review`,
+	)
+
+	return true
+}
+
+const run_merge_human_review = { retain }
+
+export { run_merge_human_review }

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

@@ -12,8 +12,13 @@ import { run_ending } from '#scripts/run/run-ending'
 const MS_PER_SECOND = 1000
 
 // When the host last booted, in epoch milliseconds.
-function booted_ms(): number {
-	return Date.now() - uptime() * MS_PER_SECOND
+function booted_ms(): number | undefined {
+	try {
+		return Date.now() - uptime() * MS_PER_SECOND
+	} catch {
+		// A denied host reading is no evidence of a restart (joshuafolkken/kit#5431).
+		return undefined
+	}
 }
 
 // Whether the newest launch ended on its own exit record. The log is appended across launches, and where
@@ -30,8 +35,10 @@ async function is_host_restart(child: string, output: string | undefined): Promi
 
 	const lane = await lane_registry.find_open_lane(child)
 	const dispatched_ms = lane?.dispatched_ms
+	if (dispatched_ms === undefined) return false
+	const boot_ms = booted_ms()
 
-	return dispatched_ms !== undefined && dispatched_ms < booted_ms()
+	return boot_ms !== undefined && dispatched_ms < boot_ms
 }
 
 const run_merge_restart = { is_host_restart }

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

@@ -10,6 +10,7 @@ import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
 import { run_merge_cap } from './run-merge-cap'
+import { run_merge_github_limit } from './run-merge-github-limit'
 import { run_merge_restart } from './run-merge-restart'
 import { run_merge_ship } from './run-merge-ship'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
@@ -21,12 +22,23 @@ import { run_merge_steps, type MergeContext } from './run-merge-steps'
 type IssueRead = Awaited<ReturnType<typeof issue_state_cli.read_issue>>
 
 // Whether the child's session ended through its environment — read only when `--output` named the
-// transcript, off otherwise: its exit record shows it could not reach the API, or the session was
-// killed inside a turn. The path is validated inside `run_ending`, so a missing output is "no".
+// transcript, off otherwise: its exit record shows it could not reach the API, the session was
+// killed inside a turn, or `gh` lost its login (`run-merge-github-limit.ts`). The path is validated
+// inside `run_ending`, so a missing output is "no".
 function read_is_outage(output: string | undefined): boolean {
 	if (output === undefined) return false
 
-	return api_outage.is_outage(run_ending.read_exit(output)) || run_ending.ended_mid_turn(output)
+	if (api_outage.is_outage(run_ending.read_exit(output))) return true
+
+	return run_ending.ended_mid_turn(output) || run_merge_github_limit.read_stop(output) === 'auth'
+}
+
+// A ship stop no relaunch answered, a host restart, or a GitHub rate limit — whose wait for its reset is
+// held apart from the streak, as a usage limit's is (`run-merge-usage-limit.ts`).
+async function is_exempt_stop(child: string, output: string | undefined): Promise<boolean> {
+	if (await run_merge_restart.is_host_restart(child, output)) return true
+
+	return run_merge_github_limit.read_stop(output) === 'rate-limit'
 }
 
 // Whether the child's session ended because it could not authenticate — off without `--output`, as the
@@ -40,12 +52,13 @@ function read_is_auth_failure(output: string | undefined): boolean {
 
 // Why an unfinished child is re-dispatchable, or `undefined` when it is not. **Only an API outage adds
 // to the run-wide streak**: a host restart is over by the time the child is read (joshuafolkken/kit#4540),
-// and an unanswered ship stop reached the API (joshuafolkken/kit#3974).
+// an unanswered ship stop reached the API (joshuafolkken/kit#3974), and a GitHub rate limit holds
+// launches until it resets (joshuafolkken/kit#6502).
 async function retry_cause(
 	child: string,
 	output: string | undefined,
 ): Promise<'api' | 'exempt' | undefined> {
-	if (await run_merge_restart.is_host_restart(child, output)) return 'exempt'
+	if (await is_exempt_stop(child, output)) return 'exempt'
 
 	if (read_is_outage(output)) return 'api'
 
@@ -54,7 +67,19 @@ async function retry_cause(
 
 // An outage child is re-dispatched only so many times: one that ends the same way on every dispatch is
 // parked, since merges in other lanes reset the run-wide outage streak and would never stop it. Its park
-// says so (`run-merge-cap.ts`).
+// says so (`run-merge-cap.ts`). While that streak holds launches, an API outage is the environment's,
+// not the child's: the cap waits, so the hold keeps growing rather than a park resetting it (#7078).
+async function is_capped(child: string, cause: 'api' | 'exempt'): Promise<boolean> {
+	const events = await run_event_stream_emit.current_events()
+
+	if (run_merge_cap.outages(events, child) < run_merge.CONSECUTIVE_OUTAGE_LIMIT) return false
+
+	if (cause !== 'api') return true
+	const record = await run_merge_steps.read_record()
+
+	return !run_merge.is_outage_guard_tripped(record?.carry.outages ?? 0)
+}
+
 async function read_retryable(
 	child: string,
 	output: string | undefined,
@@ -63,10 +88,10 @@ async function read_retryable(
 
 	if (cause === undefined) return { is_outage: false, is_streak_exempt: false }
 
-	const events = await run_event_stream_emit.current_events()
-	const limit = run_merge.CONSECUTIVE_OUTAGE_LIMIT
+	if (await is_capped(child, cause)) {
+		const events = await run_event_stream_emit.current_events()
+		const limit = run_merge.CONSECUTIVE_OUTAGE_LIMIT
 
-	if (run_merge_cap.outages(events, child) >= limit) {
 		return { is_outage: false, capped_note: run_merge_cap.note_of(events, child, limit) }
 	}
 

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

@@ -1,21 +1,17 @@
-import { existsSync } from 'node:fs'
-import path from 'node:path'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
-import { git_stash } from '#scripts/git/stash/git-stash'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { has_label_name, NOT_BEFORE_LABEL, RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+import { has_label_name, NOT_BEFORE_LABEL } from '#scripts/issue/issue-labels'
 import { issue_not_before } from '#scripts/issue/issue-not-before'
 import { issue_park } from '#scripts/issue/issue-park'
 import { issue_sample_prime } from '#scripts/issue/issue-sample-prime'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { session_cite } from '#scripts/issue/session-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
-import { lane_close } from '#scripts/lane/lane-close'
 import { lane_preserve } from '#scripts/lane/lane-preserve'
-import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
+import { lane_seat_stop } from '#scripts/lane/lane-seat-stop'
 import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { poll } from '#scripts/lib/poll'
 import { settled_together } from '#scripts/lib/settled-together'
@@ -27,11 +23,14 @@ import {
 } from '#scripts/run/carry/run-carry'
 import { run_carry_conversation } from '#scripts/run/carry/run-carry-conversation'
 import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
+import { run_cut_adoption } from '#scripts/run/cut/run-cut-adoption'
 import type { StallCause } from '#scripts/run/park/run-stalled'
 import { run_label } from '#scripts/run/run-label'
 import { run_merge, type EndingSignals } from './run-merge'
 import { run_merge_cap } from './run-merge-cap'
 import { run_merge_close } from './run-merge-close'
+import { run_merge_decision } from './run-merge-decision'
+import { run_merge_github_limit } from './run-merge-github-limit'
 
 // The result of attempting to apply a carry change. Distinguishing `refused` from `applied` lets
 // callers surface the refusal as a hard failure rather than silently continuing on a carry that was
@@ -52,8 +51,8 @@ type ApplyCarryResult =
 const OVER = 'over'
 const LANES = '--lanes'
 const REPO_FLAG = '--repo'
-const LANE_CLOSE_OCCASION = 'lane close'
-const GIT_ENTRY = '.git'
+const CLOSE_CAUSE = '`run:merge` closed it'
+const STOPPED_CAUSE = 'the unit stopped and `run:merge --stash` classified it'
 const OPEN_STATE = 'OPEN'
 const SYNC_RETRY = { attempts: 3, interval_ms: 5000 }
 
@@ -75,6 +74,8 @@ interface MergeContext extends Pick<
 	// ending apart from a genuine child failure; absent leaves outage detection off, so the child is
 	// classified from its GitHub state alone.
 	output?: string | undefined
+	// `true` where the caller passed `--stash`: a stopped unit's lane work is kept before classifying.
+	stash?: boolean | undefined
 }
 
 interface FailedResult {
@@ -127,12 +128,12 @@ async function apply_carry(
 
 	if (record === undefined) return { kind: 'none' }
 
-	if (change === undefined) return { kind: 'applied', carry: record.carry }
-
 	if (run_carry.is_count_refused(record.carry, ctx.owner)) {
 		return { kind: 'refused', carry: record.carry }
 	}
 
+	if (change === undefined) return { kind: 'applied', carry: record.carry }
+
 	const owned = run_carry_conversation.reclaim_owner(record.carry, ctx.owner)
 
 	return { kind: 'applied', carry: run_carry.apply_change(record.target, owned, change) }
@@ -184,37 +185,9 @@ async function close_lane(child: string): Promise<void> {
 	if (result.code !== 0) console.error(`${session_cite.issue(child)}: lane:close is incomplete`)
 }
 
-async function stash_work(child: string, directory: string): Promise<void> {
-	await lane_preserve.stash_work(child, directory, LANE_CLOSE_OCCASION, '`run:merge` closed it')
-}
-
-// Stash whatever the lane still holds uncommitted before its tree is removed: `lane:close` deletes by
-// force, and a merged child's uncommitted work may exist nowhere else. The stash stack outlives the
-// tree, so the push is the copy. Returns whether closing is safe — `false` when the tree could not be
-// read or pushed, so it is left rather than lost. A directory with no `.git` is no work tree — the
-// remnant of an interrupted close — and holds nothing git could keep, so it is closed rather than
-// stranded behind a status that fails.
-async function preserve_uncommitted(child: string): Promise<boolean> {
-	const lane = await lane_close.resolve_lane(child)
-	const { directory } = lane.targets
-
-	if (!existsSync(path.join(directory, GIT_ENTRY))) return true
-
-	try {
-		if (await git_stash.has_changes(directory)) await stash_work(child, directory)
-
-		return true
-	} catch {
-		console.error(
-			`${session_cite.issue(child)}: uncommitted work could not be stashed — lane left at ${directory}`,
-		)
-
-		return false
-	}
-}
-
+// `lane:close` deletes by force, and a merged child's uncommitted work may exist nowhere else.
 async function close_preserved_lane(child: string): Promise<void> {
-	if (await preserve_uncommitted(child)) await close_lane(child)
+	if (await lane_preserve.preserve_lane(child, 'lane close', CLOSE_CAUSE)) await close_lane(child)
 }
 
 function kept_lane_comment(directory: string): string {
@@ -297,11 +270,21 @@ async function do_merged(
 	return undefined
 }
 
-// A child that ended without a merge: end whatever of its process still runs, drop its stale
+async function release_cut(child: string): Promise<void> {
+	const lane = await lane_registry.find_open_lane(child)
+	if (lane === undefined) return
+	const carried = run_cut.lane_cut_sync(lane.directory)
+	if (carried === undefined) return
+
+	run_cut_adoption.release(carried.target, carried.cut, child)
+}
+
+// A child that ended without a merge: end whatever of its process still runs, release its adoption, drop its stale
 // `in-progress`, and close its lane if the child left nothing in it. The reap comes first, so the lane
 // reads with no live process.
 async function release_child(child: string): Promise<void> {
-	lane_reap.reap_child(await lane_registry.lane_location(child))
+	await lane_seat_stop.stop(child)
+	await release_cut(child)
 	await run_label.unmark(child)
 	await close_vacant_lane(child)
 }
@@ -318,7 +301,7 @@ async function open_blockers(child: string): Promise<ReadonlyArray<string>> {
 
 		return references
 			.filter((blocker) => blocker.state === OPEN_STATE)
-			.map((blocker) => issue_cite.plain(blocker.number, blocker.repo))
+			.map((blocker) => issue_cite.plain_for('github', blocker.number, blocker.repo))
 	} catch {
 		return NO_WAITS
 	}
@@ -363,16 +346,17 @@ async function do_waiting(ctx: MergeContext, waits: ReadonlyArray<string>): Prom
 	return { carry: undefined, is_parked: false, is_refused: false, waits }
 }
 
-// A failed child: count the failure, end whatever of its process is still running (a child judged
+// An unfinished child: count mechanical failures only, end whatever of its process is still running (a child judged
 // abandoned that hung on a wait loop would otherwise answer the pgrep liveness check `alive` for its
 // issue number forever), drop the stale `in-progress`, and park it with `run:stalled` so the next
-// offer does not hand the same child straight back. Not `needs-decision`: the failure is mechanical,
-// and nothing is asked of a person but to fix its cause (joshuafolkken/kit#4102). Returns the record
+// offer does not hand the same child straight back. A question parks with `needs-decision` without
+// increasing failures; mechanical failures use `run:stalled` (joshuafolkken/kit#6268). Returns the record
 // so the caller can read the streak against the guard. Returns `is_refused: true` without touching labels when the carry record
 // rejected the count. A park is always explained on the issue — `cause` says what was judged, and the
 // comment what was read and what a person does next.
 async function park_failed(ctx: MergeContext, cause: StallCause): Promise<FailedResult> {
-	const result = await apply_carry(ctx, run_merge.change_of('failed'))
+	const is_decision = run_merge_decision.is_decision(cause.short)
+	const result = await apply_carry(ctx, run_merge.change_of(is_decision ? 'parked' : 'failed'))
 
 	if (result.kind === 'refused') return refused_result(result.carry)
 
@@ -380,7 +364,8 @@ async function park_failed(ctx: MergeContext, cause: StallCause): Promise<Failed
 
 	await release_child(ctx.child)
 	const reason = { child: ctx.child, cause: cause.why, carry, output: ctx.output }
-	const park = await issue_park.apply(ctx.child, RUN_STALLED_LABEL, run_merge.park_comment(reason))
+	const { label, comment } = run_merge_decision.park_options(cause, reason)
+	const park = await issue_park.apply(ctx.child, label, comment)
 
 	return {
 		carry,
@@ -400,7 +385,10 @@ async function do_failed(ctx: MergeContext, cause?: StallCause): Promise<FailedR
 
 	if (waits.length > 0) return await do_waiting(ctx, waits)
 
-	return await park_failed(ctx, run_merge_cap.park_cause(ctx.child, cause, ctx.capped_note))
+	return await park_failed(
+		ctx,
+		run_merge_cap.park_cause(ctx.child, cause, ctx.capped_note, ctx.output),
+	)
 }
 
 // The outcome of counting an outage: the record to read the streak against, and whether the count was
@@ -430,6 +418,7 @@ async function do_outage(ctx: MergeContext): Promise<OutageResult> {
 	if (result.kind === 'refused') return { carry: result.carry, is_refused: true }
 
 	await release_child(ctx.child)
+	await run_merge_github_limit.hold(ctx.child, ctx.output)
 
 	return { carry: result.kind === 'applied' ? result.carry : undefined, is_refused: false }
 }
@@ -464,6 +453,14 @@ async function has_resumable_cut(child: string): Promise<boolean> {
 	return (await relaunchable_cut(child)) !== undefined
 }
 
+// `run:merge --stash`: a stopped unit's half-finished work is kept before the child is classified —
+// unless the lane holds a cut `resume_cut` may relaunch, whose successor resumes from that very tree.
+async function stash_stopped(child: string): Promise<void> {
+	if (await has_resumable_cut(child)) return
+
+	await lane_preserve.preserve_lane(child, 'stopped unit', STOPPED_CAUSE)
+}
+
 // **The cutting child launches its own successor; this is only the fallback**.
 // `lane:await` wakes the parent once every process of the lane has gone, so a cut still unadopted then
 // means the successor never took it over. It is relaunched through the same `lane_relaunch` the cut uses,
@@ -474,7 +471,7 @@ async function resume_cut(child: string): Promise<boolean> {
 
 	if (found === undefined || !run_cut.mark_merge_relaunched(found.target, found.cut)) return false
 
-	const result = lane_relaunch.resume(found.lane, found.cut.phase, (note) => {
+	const result = await lane_relaunch.resume(found.lane, found.cut.phase, (note) => {
 		console.error(note)
 	})
 
@@ -515,8 +512,10 @@ const run_merge_steps = {
 	do_outage,
 	has_resumable_cut,
 	is_over_budget,
+	read_record,
 	refused_carry,
 	resume_cut,
+	stash_stopped,
 }
 
 export type { FailedResult, MergeContext, OutageResult }

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

@@ -9,11 +9,10 @@ const MERGE_TOKEN = {
 	HUMAN_REVIEW: 'human-review',
 	// Matches the `busy` verdict `run:carry` emits for a refused count, so callers see one vocabulary.
 	BUSY: 'busy',
-	// The consecutive-failure guard tripped, or a failed child could not be parked.
+	// A failed child could not be parked.
 	STOP: 'stop',
-	// The consecutive-outage guard tripped: the environment is down, so the run stops rather than
-	// re-dispatching into a dead API. Distinct from `stop` so the parent's report can say the environment
-	// failed rather than the children.
+	// The environment is down. `run:merge` no longer emits it — an outage or an authentication failure
+	// holds launches instead (joshuafolkken/kit#7078) — so it is only ever read, ending the loop.
 	ENVIRONMENT: 'environment',
 	// The child's state could not be read; re-read before deciding.
 	RETRY: 'retry',

package/scripts/run/merge/run-merge-usage-limit.ts

@@ -12,12 +12,14 @@ import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 const KIND = run_event_stream.EVENT_KIND.USAGE_LIMIT
 const RESUMES_AT = /resumes at (\S+)$/u
 
-function stop_text(child: string, reset_ms: number): string {
-	return `${issue_cite.plain(child)} usage limit — resumes at ${new Date(reset_ms).toISOString()}`
+function stop_text(child: string, reset_ms: number, limit: string): string {
+	return `${issue_cite.plain_for('program', child)} ${limit} — resumes at ${new Date(reset_ms).toISOString()}`
 }
 
-async function record(child: string, reset_ms: number): Promise<void> {
-	await run_event_stream_emit.emit(KIND, stop_text(child, reset_ms))
+// `limit` names what stopped the child — a GitHub rate limit holds launches the same way
+// (`run-merge-github-limit.ts`).
+async function record(child: string, reset_ms: number, limit = 'usage limit'): Promise<void> {
+	await run_event_stream_emit.emit(KIND, stop_text(child, reset_ms, limit))
 }
 
 // The time a stop's text names, or `undefined` when it does not parse.
@@ -28,7 +30,7 @@ function time_of(text: string): number | undefined {
 }
 
 // The reset the newest usage-limit stop names, in epoch milliseconds, or `undefined` when the stream
-// holds none — every lane shares the one account, so the newest stop is the limit in force.
+// holds none. A hold reads `held_until`, which also weighs a GitHub rate limit's stops.
 function resume_ms(events: ReadonlyArray<RunEvent>): number | undefined {
 	const newest = events.findLast((event) => event.kind === KIND)
 
@@ -36,11 +38,22 @@ function resume_ms(events: ReadonlyArray<RunEvent>): number | undefined {
 }
 
 // The reset a usage limit still holds launches until at `now_ms`, or `undefined` once it has passed —
-// what `run:board` names a waiting row's hold by (joshuafolkken/kit#4796).
+// what `run:board` names a waiting row's hold by (joshuafolkken/kit#4796). The latest reset still ahead
+// wins, not the newest stop: a GitHub rate limit's reset is another account's, and an earlier one
+// recorded after a Claude limit must not end that limit's hold (joshuafolkken/kit#6502).
 function held_until(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
-	const reset_ms = resume_ms(events)
+	const ahead = events
+		.filter((event) => event.kind === KIND)
+		.map((event) => time_of(event.text) ?? 0)
+		.filter((reset_ms) => reset_ms > now_ms)
 
-	return reset_ms !== undefined && reset_ms > now_ms ? reset_ms : undefined
+	return ahead.length === 0 ? undefined : Math.max(...ahead)
+}
+
+// How many children a usage limit stopped whose reset is still ahead at `now_ms` — the children the
+// `⛽ usage` section counts as parked behind it (joshuafolkken/kit#5395).
+function held_count(events: ReadonlyArray<RunEvent>, now_ms: number): number {
+	return events.filter((event) => event.kind === KIND && (time_of(event.text) ?? 0) > now_ms).length
 }
 
 // Whether a usage limit still holds launches at `now_ms` — the production `usage_limited` port.
@@ -48,6 +61,6 @@ async function is_held(now_ms: number): Promise<boolean> {
 	return held_until(await run_event_stream_emit.current_events(), now_ms) !== undefined
 }
 
-const run_merge_usage_limit = { held_until, is_held, record, resume_ms }
+const run_merge_usage_limit = { held_count, held_until, is_held, record, resume_ms }
 
 export { run_merge_usage_limit }

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

@@ -42,9 +42,10 @@ async function collect(child: string): Promise<Collected> {
 async function collect_yield(child: string): Promise<Collected> {
 	const lane = await lane_registry.find_open_lane(child)
 
-	return lane === undefined
-		? NOTHING_LEFT
-		: await lane_withdraw_closed.withdraw_lane(lane, lane_yield.YIELD_REASON, 'yield')
+	if (lane === undefined) return NOTHING_LEFT
+	const reason = lane_yield.withdraw_reason(await run_event_stream_emit.current_events(), child)
+
+	return await lane_withdraw_closed.withdraw_lane(lane, reason, 'yield')
 }
 
 const run_merge_withdrawn = { UNMERGED_REASON, collect, collect_yield }