@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,13 +1,15 @@
 import { api_auth } from '#scripts/agent/api-auth'
 import { api_outage } from '#scripts/agent/api-outage'
+import { api_usage_limit } from '#scripts/agent/api-usage-limit'
 import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_merged } from '#scripts/issue/issue-merged'
 import type { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_yield } from '#scripts/lane/lane-yield'
 import { run_event_scope } from '#scripts/run/event/run-event-scope'
-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_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_restart } from './run-merge-restart'
 import { run_merge_ship } from './run-merge-ship'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
@@ -36,16 +38,6 @@ function read_is_auth_failure(output: string | undefined): boolean {
 	return api_auth.is_auth_failed_transcript(run_ending.read_transcript(output))
 }
 
-async function child_outages(child: string): Promise<number> {
-	const events = await run_event_stream_emit.current_events()
-
-	return events.filter(
-		(event) =>
-			event.kind === run_event_stream.EVENT_KIND.OUTAGE &&
-			run_event_scope.issue_named(event) === child,
-	).length
-}
-
 // 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).
@@ -61,18 +53,24 @@ 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.
+// 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`).
 async function read_retryable(
 	child: string,
 	output: string | undefined,
-): Promise<{ is_outage: boolean; is_streak_exempt: boolean }> {
+): Promise<Pick<EndingSignals, 'is_outage' | 'is_streak_exempt' | 'capped_note'>> {
 	const cause = await retry_cause(child, output)
 
 	if (cause === undefined) return { is_outage: false, is_streak_exempt: false }
 
-	const is_outage = (await child_outages(child)) < run_merge.CONSECUTIVE_OUTAGE_LIMIT
+	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) }
+	}
 
-	return { is_outage, is_streak_exempt: is_outage && cause === 'exempt' }
+	return { is_outage: true, is_streak_exempt: cause === 'exempt' }
 }
 
 // The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
@@ -84,30 +82,49 @@ async function read_merged_pr(child: string, read: IssueRead): Promise<string |
 	return await issue_closing_pr.read_closing_pr(child)
 }
 
-// A child that merged before `lane:withdraw` stopped it is merged, not withdrawn: the withdrawal's
-// event is already written, so only the timeline tells its merged close from the not-planned one. An
-// unread timeline answers `undefined`, and `outcome_of` asks again rather than guessing.
+// **A CLOSED child is withdrawn unless a merge closed it**, whether or not `lane:withdraw` ran: an issue
+// closed as not planned, or closed with no merged pull request, never merged, so it must not be booked
+// as a merge (joshuafolkken/kit#4916). Only the timeline tells a merged close from the rest, so it
+// decides — and a child that merged before `lane:withdraw` stopped it is merged. Any other child is
+// withdrawn only by its event. An unread timeline answers `undefined`, and `outcome_of` asks again
+// rather than guessing.
 async function read_is_withdrawn(child: string, read: IssueRead): Promise<boolean | undefined> {
-	const events = await run_event_stream_emit.current_events()
+	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'merged') {
+		return run_event_scope.is_withdrawn(await run_event_stream_emit.current_events(), child)
+	}
 
-	if (!run_event_scope.is_withdrawn(events, child)) return false
-	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'merged') return true
 	const is_merged = await issue_merged.read_merge_state(child)
 
 	return is_merged === undefined ? undefined : !is_merged
 }
 
+// The child's own yield is on the stream, read locally, as a person's withdrawal is.
+async function read_is_yielded(child: string): Promise<boolean> {
+	return lane_yield.is_yielded(await run_event_stream_emit.current_events(), child)
+}
+
+// When a usage limit that stopped the child resets — off without `--output`, as the outage read is. The
+// reset is read from the transcript's last write, not from this late collection of it.
+function read_resume_ms(output: string | undefined): number | undefined {
+	if (output === undefined) return undefined
+	const transcript = run_ending.read_transcript(output)
+
+	return api_usage_limit.transcript_resume_ms(transcript, Date.now(), run_ending.written_at(output))
+}
+
 async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
-	const [is_cut, merged_pr, retryable, is_withdrawn] = await Promise.all([
+	const [is_cut, merged_pr, retryable, is_withdrawn, is_yielded] = await Promise.all([
 		run_merge_steps.has_resumable_cut(ctx.child),
 		read_merged_pr(ctx.child, read),
 		read_retryable(ctx.child, ctx.output),
 		read_is_withdrawn(ctx.child, read),
+		read_is_yielded(ctx.child),
 	])
 
 	const is_auth_failure = read_is_auth_failure(ctx.output)
+	const resume_ms = read_resume_ms(ctx.output)
 
-	return { ...retryable, is_cut, merged_pr, is_withdrawn, is_auth_failure }
+	return { ...retryable, is_cut, merged_pr, is_withdrawn, is_yielded, is_auth_failure, resume_ms }
 }
 
 // An unread state is `unresolved` unless a withdrawal already settled the child, which is read locally;

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

@@ -7,7 +7,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, NOT_BEFORE_LABEL, RUN_STALLED_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_gate } from '#scripts/issue/issue-sample-gate'
+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'
@@ -18,6 +18,7 @@ import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { poll } from '#scripts/lib/poll'
+import { settled_together } from '#scripts/lib/settled-together'
 import {
 	run_carry,
 	type CarryChange,
@@ -26,11 +27,11 @@ 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_stalled, type StallCause } from '#scripts/run/park/run-stalled'
+import type { StallCause } from '#scripts/run/park/run-stalled'
 import { run_label } from '#scripts/run/run-label'
-import { run_merge } from './run-merge'
+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_ship } from './run-merge-ship'
 
 // 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
@@ -56,25 +57,24 @@ const GIT_ENTRY = '.git'
 const OPEN_STATE = 'OPEN'
 const SYNC_RETRY = { attempts: 3, interval_ms: 5000 }
 
-// One returned child's context, gathered from the command line by the CLI.
-interface MergeContext {
+// One returned child's context, gathered from the command line by the CLI, and the ending signals its
+// handlers act on — each one's meaning is `EndingSignals`'s.
+interface MergeContext extends Pick<
+	EndingSignals,
+	'merged_pr' | 'is_streak_exempt' | 'capped_note' | 'resume_ms'
+> {
 	child: string
 	epic: string | undefined
 	repo: string | undefined
-	// The hand-off threshold, or `undefined` where no AI session owns the loop — the supervisor's
-	// `backlog:drive` has no context to cut, so a merge there is never handed back as `over`.
-	over: number | undefined
+	// `true` where the merge asks the session's `pnpm josh cost --cut` verdict, or `undefined` where no
+	// AI session owns the loop — the supervisor's `backlog:drive` has no context to cut, so a merge
+	// there is never handed back as `over`.
+	over: true | undefined
 	owner: CarryOwner
 	// The child's transcript output path, when the caller passed `--output`. Read to tell an API-outage
 	// 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
-	// The merged pull request that closes the child, when GitHub left the child OPEN after the merge —
-	// the one `merged` child whose issue this command still has to close.
-	merged_pr?: string | undefined
-	// The outage is not an API outage (`EndingSignals.is_streak_exempt`): re-dispatched, but not added
-	// to the streak.
-	is_streak_exempt?: boolean | undefined
 }
 
 interface FailedResult {
@@ -213,6 +213,10 @@ async function preserve_uncommitted(child: string): Promise<boolean> {
 	}
 }
 
+async function close_preserved_lane(child: string): Promise<void> {
+	if (await preserve_uncommitted(child)) await close_lane(child)
+}
+
 function kept_lane_comment(directory: string): string {
 	return `The split left this issue's lane open: it still holds a commit, an uncommitted change or a live process — ${directory}`
 }
@@ -251,27 +255,44 @@ async function post_counters(ctx: MergeContext, carry: RunCarry | undefined): Pr
 	await git_gh_issue_write.issue_try_comment(ctx.epic, run_merge.counters_comment(carry))
 }
 
-// A merged child: close it if GitHub left it OPEN and close the epics it completed
-// (`run-merge-close.ts`), count the merge (which resets the failure streak), return to the default branch,
-// stash any uncommitted work the lane still holds and close it, and mirror the counters onto the epic. Returns the carry when the ownership check
-// fails — the caller treats a non-undefined return as a hard refusal and must not offer a next child.
-// Returns `undefined` on success.
-async function do_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
+// Count the merge, which resets the failure streak.
+async function count_merged(ctx: MergeContext): Promise<ApplyCarryResult> {
+	return await apply_carry(ctx, {
+		...run_merge.change_of('merged'),
+		merged_issue: Number(ctx.child),
+	})
+}
+
+// A merged child: closed if GitHub left it OPEN, with the epics it completed (`run-merge-close.ts`),
+// while the primary checkout returns to the default branch; then counted and put on record by `record`,
+// dated to the moment the ownership check passed (joshuafolkken/kit#4734); then the lane — stashed of
+// any uncommitted work — is closed while the counters are mirrored onto the epic. **A failed sync
+// leaves neither the count nor the record**, so the run's next pass (a restored drive, `run:carry
+// --end`) still reads the child as unsettled and collects it again. **What the next offer reads ends
+// before this returns**: the closed issue and epics, the count, the lane's freed seat, and the default
+// branch whose code the next `josh` runs. Returns the carry when the ownership check fails — the caller
+// treats a non-undefined return as a hard refusal and must not offer a next child. Returns `undefined`
+// on success.
+async function do_merged(
+	ctx: MergeContext,
+	record: (child: string, at: Date) => Promise<void>,
+): Promise<RunCarry | undefined> {
 	const refused = await refused_carry(ctx)
 
 	if (refused !== undefined) return refused
 
-	await run_merge_close.close_merged(ctx)
-	await sync_main()
-	const result = await apply_carry(ctx, {
-		...run_merge.change_of('merged'),
-		merged_issue: Number(ctx.child),
-	})
+	const confirmed_at = new Date()
+
+	await settled_together(run_merge_close.close_merged(ctx), sync_main())
+	const result = await count_merged(ctx)
 
 	if (result.kind === 'refused') return result.carry
 
-	if (await preserve_uncommitted(ctx.child)) await close_lane(ctx.child)
-	await post_counters(ctx, result.kind === 'applied' ? result.carry : undefined)
+	await record(ctx.child, confirmed_at)
+
+	const carry = result.kind === 'applied' ? result.carry : undefined
+
+	await Promise.all([close_preserved_lane(ctx.child), post_counters(ctx, carry)])
 
 	return undefined
 }
@@ -319,7 +340,7 @@ async function start_date_wait(ctx: MergeContext): Promise<ReadonlyArray<string>
 
 	if (body === undefined) return (await has_not_before_label(ctx)) ? [NOT_BEFORE_WAIT] : NO_WAITS
 
-	await issue_sample_gate.prime([body])
+	await issue_sample_prime.prime([body])
 	const reason = issue_not_before.waiting_reason(body)
 
 	return reason === undefined ? NO_WAITS : [reason]
@@ -379,9 +400,7 @@ async function do_failed(ctx: MergeContext, cause?: StallCause): Promise<FailedR
 
 	if (waits.length > 0) return await do_waiting(ctx, waits)
 
-	const judged = cause ?? run_merge_ship.cause(ctx.child) ?? run_stalled.SESSION_UNFINISHED
-
-	return await park_failed(ctx, judged)
+	return await park_failed(ctx, run_merge_cap.park_cause(ctx.child, cause, ctx.capped_note))
 }
 
 // The outcome of counting an outage: the record to read the streak against, and whether the count was
@@ -463,11 +482,12 @@ async function resume_cut(child: string): Promise<boolean> {
 }
 
 // The hand-off check, asked at a merge alone. A subprocess that cannot measure exits non-zero, which
-// is read as `over` — "could not measure" is never "still cheap". No threshold is no session to measure.
-async function is_over_budget(over: number | undefined): Promise<boolean> {
+// is read as `over` — "could not measure" is never "still cheap". No check is no session to measure.
+// `--cut`, not a number: the threshold is priced at the session's own model.
+async function is_over_budget(over: true | undefined): Promise<boolean> {
 	if (over === undefined) return false
 
-	const result = await josh(['cost', '--over', String(over)])
+	const result = await josh(['cost', '--cut'])
 
 	return result.code !== 0 || result.out === OVER
 }

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

@@ -0,0 +1,53 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+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'
+
+// A returned child a Claude usage limit stopped (joshuafolkken/kit#4745). Nothing is counted and no park
+// label is put on it — the limit is the account's, not the child's — so it is released for the backlog
+// to offer again, and the stop is written to the event stream with the time the limit resets.
+// `backlog:drive` reads that time back and launches nothing before it. **It is no `OUTAGE`**: the
+// per-child cap counts those (`run-merge-cap.ts`), and a wait for a known reset is no outage streak.
+// Script-emitted, so English.
+
+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()}`
+}
+
+async function record(child: string, reset_ms: number): Promise<void> {
+	await run_event_stream_emit.emit(KIND, stop_text(child, reset_ms))
+}
+
+// The time a stop's text names, or `undefined` when it does not parse.
+function time_of(text: string): number | undefined {
+	const parsed = Date.parse(RESUMES_AT.exec(text)?.[1] ?? '')
+
+	return Number.isNaN(parsed) ? undefined : parsed
+}
+
+// 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.
+function resume_ms(events: ReadonlyArray<RunEvent>): number | undefined {
+	const newest = events.findLast((event) => event.kind === KIND)
+
+	return newest === undefined ? undefined : time_of(newest.text)
+}
+
+// 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).
+function held_until(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
+	const reset_ms = resume_ms(events)
+
+	return reset_ms !== undefined && reset_ms > now_ms ? reset_ms : undefined
+}
+
+// Whether a usage limit still holds launches at `now_ms` — the production `usage_limited` port.
+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 }
+
+export { run_merge_usage_limit }

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

@@ -0,0 +1,53 @@
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_withdraw_closed } from '#scripts/lane/lane-withdraw-closed'
+import { lane_yield } from '#scripts/lane/lane-yield'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+
+// The lane of a child `run:merge` booked `withdrawn` (joshuafolkken/kit#4916). A person's
+// `lane:withdraw` already stopped the child, closed its lane and put itself on the stream, so nothing is
+// left to do. A child whose issue closed without a merge had no such withdrawal: its lane is still open,
+// so it is withdrawn here through the `run:wake` sweep's guarded path — kept where its branch has
+// commits on no remote, else stopped, its work stashed, the lane closed and the withdrawal put on the
+// stream — and never booked as a merge. A withdrawal that could not read the child stopped and closed
+// nothing, so it asks for a retry rather than leak the lane.
+
+const UNMERGED_REASON = 'its issue was closed without a merged pull request'
+
+interface Collected {
+	// The withdrawal's note, or `undefined` where a withdrawal is on the stream or no lane is open.
+	note: string | undefined
+	is_retry: boolean
+}
+
+const NOTHING_LEFT: Collected = { note: undefined, is_retry: false }
+
+/** Withdraw `#<child>`'s open lane unless a withdrawal that closed it is already on the stream. */
+async function collect(child: string): Promise<Collected> {
+	const events = await run_event_stream_emit.current_events()
+
+	if (run_event_scope.is_withdrawn(events, child)) return NOTHING_LEFT
+	const lane = await lane_registry.find_open_lane(child)
+
+	return lane === undefined
+		? NOTHING_LEFT
+		: await lane_withdraw_closed.withdraw_lane(lane, UNMERGED_REASON, 'merge')
+}
+
+/**
+ * Close the open lane of `#<child>`, which gave it back (`lane-yield.ts`): the child noted its yield
+ * from inside the lane, which it could not close, so the lane is closed here, named as the yield. A
+ * lane already closed — a second `run:merge` — leaves nothing to do.
+ */
+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')
+}
+
+const run_merge_withdrawn = { UNMERGED_REASON, collect, collect_yield }
+
+export type { Collected }
+export { run_merge_withdrawn }

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

@@ -35,7 +35,7 @@ const ONE = 1
 
 // What a returned child turned out to be, decided from its GitHub state and — for the failed case
 // alone — the exit record.
-// - `merged`      — CLOSED; the child finished and its pull request merged. Also an OPEN, unparked
+// - `merged`      — CLOSED by a merge; the child finished and its pull request merged. Also an OPEN, unparked
 //                   child a merged pull request's `closes #N` names — GitHub merged it without closing
 //                   the issue.
 // - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (needs-human-review.md).
@@ -50,9 +50,14 @@ const ONE = 1
 // - `unauthenticated` — OPEN and carrying neither, but the exit record shows the session could not
 //                   authenticate; no child can run until a person runs `/login`, so the run stops with
 //                   the child left `in-progress` and nothing counted (joshuafolkken/kit#4216).
+// - `usage-limit` — OPEN and carrying neither, but the exit record shows a Claude usage limit stopped
+//                   it; nothing is counted or parked, and the run dispatches again once the limit
+//                   resets (joshuafolkken/kit#4745).
 // - `failed`      — OPEN and carrying neither, and not an outage; the child did not finish.
 // - `withdrawn`   — a person withdrew it with `lane:withdraw`, read from the event stream before the
-//                   GitHub state: left OPEN for the next run, it is neither merged nor failed.
+//                   GitHub state: left OPEN for the next run, it is neither merged nor failed. Also a
+//                   CLOSED child no merge closed — closed as not planned, or with no merged pull
+//                   request (joshuafolkken/kit#4916).
 // - `unresolved`  — the state could not be read; re-read before deciding.
 // The names themselves are `run-merge-outcome.ts`'s.
 
@@ -64,13 +69,22 @@ interface EndingSignals {
 	// The merged pull request whose `closes #N` names the child, when GitHub left the child OPEN after
 	// merging it.
 	merged_pr?: string | undefined
-	// The newest launch of the child was withdrawn by a person (`run_event_scope.is_withdrawn`).
+	// The newest launch of the child was withdrawn by a person (`run_event_scope.is_withdrawn`), or its
+	// issue was closed without a merge (`run-merge-signals.ts` → `read_is_withdrawn`).
 	is_withdrawn?: boolean | undefined
+	// The newest launch of the child gave its lane back on its `lane:plan` (`lane-yield.ts`).
+	is_yielded?: boolean | undefined
 	// The outage is not an API the child could not reach — a ship stop no relaunch answered, or a host
 	// restart that killed it — so it is left out of the run-wide streak.
 	is_streak_exempt?: boolean | undefined
 	// The exit record shows the session could not authenticate (`api-auth.ts`).
 	is_auth_failure?: boolean | undefined
+	// When a usage limit that stopped the session lets the run dispatch again, in epoch milliseconds
+	// (`api-usage-limit.ts`); absent when no usage limit stopped it.
+	resume_ms?: number | undefined
+	// A re-dispatchable ending the per-child cap turned into `failed`: the line its park leads with
+	// (`run-merge-cap.ts`).
+	capped_note?: string | undefined
 }
 
 const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
@@ -85,7 +99,18 @@ function is_parked(state: IssueState): boolean {
 	return has_parked_label(state.labels)
 }
 
-// **CLOSED means merged, whatever labels it carries** — a child that finished and merged keeps the
+// An unfinished child its environment ended: it could not authenticate, a usage limit stopped it, or it
+// could not reach the API — read in that order, each more specific than the next.
+function environment_outcome(signals: EndingSignals): ChildOutcome {
+	if (signals.is_auth_failure === true) return 'unauthenticated'
+
+	if (signals.resume_ms !== undefined) return 'usage-limit'
+
+	return signals.is_outage ? 'outage' : 'failed'
+}
+
+// **CLOSED means merged, whatever labels it carries**, once the withdrawal signal has ruled out a close
+// no merge made (`classify_child`) — a child that finished and merged keeps the
 // `needs-human-review` a person put on it, so that label is read only on an OPEN child
 // (`backlogrun-progress.md` → "Running a named epic's children").
 // An OPEN, unparked child that is not waiting on a person: a declared cut is resumed, and it is read
@@ -98,9 +123,7 @@ function unfinished_outcome(signals: EndingSignals): ChildOutcome {
 
 	if (signals.is_cut) return 'cut'
 
-	if (signals.is_auth_failure === true) return 'unauthenticated'
-
-	return signals.is_outage ? 'outage' : 'failed'
+	return environment_outcome(signals)
 }
 
 function open_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
@@ -113,25 +136,29 @@ function open_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
 	return unfinished_outcome(signals)
 }
 
+function state_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
+	return is_closed(state) ? 'merged' : open_outcome(state, signals)
+}
+
 // The signals are read by the CLI and, but for a withdrawal, matter only for an OPEN child — a CLOSED
-// child is merged regardless of how the process exited. **A withdrawal is read first**: `lane:withdraw`
+// child arrives already filtered by `is_withdrawn` (its timeline), so one that reaches here is merged
+// regardless of how the process exited. **A yield, then a withdrawal, is read first**: a yield leaves
+// its issue OPEN and its lane open for `run:merge` to close (`lane-yield.ts`), and `lane:withdraw`
 // records it before stopping the child and leaves the issue OPEN, which would otherwise read as a child
 // to resume or park.
 function classify_child(
 	state: IssueState | undefined,
 	signals: EndingSignals = NO_SIGNALS,
 ): ChildOutcome {
-	if (signals.is_withdrawn === true) return 'withdrawn'
-
-	if (state === undefined) return 'unresolved'
+	if (signals.is_yielded === true) return 'yielded'
 
-	if (is_closed(state)) return 'merged'
+	if (signals.is_withdrawn === true) return 'withdrawn'
 
-	return open_outcome(state, signals)
+	return state === undefined ? 'unresolved' : state_outcome(state, signals)
 }
 
 // The counter change a child's outcome implies. A merge counts a merge (which resets the failure
-// streak); a failure counts a failure; a split, parked, withdrawn or human-review child counts nothing —
+// streak); a failure counts a failure; a split, parked, withdrawn, yielded or human-review child counts nothing —
 // a decision a person made or still owes is not the environment failing — and `undefined` says the
 // carry record is left untouched.
 function change_of(outcome: ChildOutcome): CarryChange | undefined {