@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,3 +1,4 @@
+import { api_auth } from '#scripts/agent/api-auth'
 import { api_outage } from '#scripts/agent/api-outage'
 import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_merged } from '#scripts/issue/issue-merged'
@@ -7,6 +8,7 @@ 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_restart } from './run-merge-restart'
 import { run_merge_ship } from './run-merge-ship'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
 
@@ -25,6 +27,15 @@ function read_is_outage(output: string | undefined): boolean {
 	return api_outage.is_outage(run_ending.read_exit(output)) || run_ending.ended_mid_turn(output)
 }
 
+// Whether the child's session ended because it could not authenticate — off without `--output`, as the
+// outage read is. The lane's log is appended across launches, so it is read as the reviewer's is
+// (`api_auth.is_auth_failed_transcript`).
+function read_is_auth_failure(output: string | undefined): boolean {
+	if (output === undefined) return false
+
+	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()
 
@@ -35,22 +46,33 @@ async function child_outages(child: string): Promise<number> {
 	).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).
+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 (read_is_outage(output)) return 'api'
+
+	return (await run_merge_ship.is_unanswered(child, output)) ? 'exempt' : undefined
+}
+
 // 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. **An
-// unanswered ship stop is told apart from an API outage**: the child reached the API, so it is
-// re-dispatched without adding to the run-wide streak (joshuafolkken/kit#3974).
+// parked, since merges in other lanes reset the run-wide outage streak and would never stop it.
 async function read_retryable(
 	child: string,
 	output: string | undefined,
-): Promise<{ is_outage: boolean; is_unanswered: boolean }> {
-	const is_api_outage = read_is_outage(output)
-	const is_unanswered = !is_api_outage && (await run_merge_ship.is_unanswered(child, output))
+): Promise<{ is_outage: boolean; is_streak_exempt: boolean }> {
+	const cause = await retry_cause(child, output)
 
-	if (!is_api_outage && !is_unanswered) return { is_outage: false, is_unanswered: false }
+	if (cause === undefined) return { is_outage: false, is_streak_exempt: false }
 
 	const is_outage = (await child_outages(child)) < run_merge.CONSECUTIVE_OUTAGE_LIMIT
 
-	return { is_outage, is_unanswered: is_outage && is_unanswered }
+	return { is_outage, is_streak_exempt: is_outage && cause === 'exempt' }
 }
 
 // The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
@@ -83,7 +105,9 @@ async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingS
 		read_is_withdrawn(ctx.child, read),
 	])
 
-	return { ...retryable, is_cut, merged_pr, is_withdrawn }
+	const is_auth_failure = read_is_auth_failure(ctx.output)
+
+	return { ...retryable, is_cut, merged_pr, is_withdrawn, is_auth_failure }
 }
 
 // An unread state is `unresolved` unless a withdrawal already settled the child, which is read locally;

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

@@ -1,11 +1,14 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { git_followup_issue_close } from '#scripts/followup/git-followup-issue-close'
 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 { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+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_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'
@@ -23,8 +26,10 @@ 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 { run_label } from '#scripts/run/run-label'
 import { run_merge } from './run-merge'
+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
@@ -48,14 +53,8 @@ const LANES = '--lanes'
 const REPO_FLAG = '--repo'
 const LANE_CLOSE_OCCASION = 'lane close'
 const GIT_ENTRY = '.git'
-const MERGE_CLOSER = 'pnpm josh run:merge'
-const SINGLE_READ = { attempts: 1, interval_ms: 0 }
 const OPEN_STATE = 'OPEN'
 const SYNC_RETRY = { attempts: 3, interval_ms: 5000 }
-// What the driver judged when it parks a child, stated on the issue.
-const FAILED_CAUSE = 'the child’s session ended with its issue still open and unfinished.'
-const CUT_RELAUNCH_CAUSE =
-	'its lane held a declared cut, but no successor could be relaunched from it (or it already was once).'
 
 // One returned child's context, gathered from the command line by the CLI.
 interface MergeContext {
@@ -73,8 +72,9 @@ interface MergeContext {
 	// 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 a ship stop no relaunch answered: re-dispatched, but not added to the streak.
-	is_unanswered?: boolean | 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 {
@@ -83,12 +83,16 @@ interface FailedResult {
 	// Set when the carry record refused the count because this session is not its owner. The caller
 	// surfaces this as a hard failure rather than continuing.
 	is_refused: boolean
-	// The open `blocked-by` blockers the child was released to wait on, cited — empty for a child that
-	// was parked (or refused) instead.
-	blockers: ReadonlyArray<string>
+	// What the child was released to wait on — its open `blocked-by` blockers, cited, and a start date
+	// still ahead — empty for a child that was parked (or refused) instead.
+	waits: ReadonlyArray<string>
+	// The short name of why a parked child was parked, which its park event carries.
+	cause?: string | undefined
 }
 
-const NO_BLOCKERS: ReadonlyArray<string> = []
+const NO_WAITS: ReadonlyArray<string> = []
+// The wait a `not-before` label alone records: the label carries no date, only that one is ahead.
+const NOT_BEFORE_WAIT = 'a start date still ahead (`not-before`)'
 
 // A captured `pnpm josh` subprocess: its output is read back rather than inherited, and a non-zero
 // exit is a value to branch on rather than a throw. The step's stderr stays piped here — `run:merge`
@@ -167,8 +171,17 @@ async function sync_main(): Promise<void> {
 	if (!is_synced) throw new Error(`main:sync failed: ${error_output}`)
 }
 
+// `lane:close` says on stderr what it terminated — the child and whatever else ran from the checkout
+// (joshuafolkken/kit#4304) — so that stderr is passed on rather than dropped with the capture. An
+// `incomplete` close — a process that outlived even a SIGKILL — is logged and the run carries on: the
+// merge cannot be undone, and the supervisor closes the lane again each pass until it ends
+// (joshuafolkken/kit#4300).
 async function close_lane(child: string): Promise<void> {
-	await josh(['lane:close', child])
+	const result = await josh(['lane:close', child])
+	const said = result.err?.trimEnd() ?? ''
+
+	if (said !== '') console.error(said)
+	if (result.code !== 0) console.error(`${session_cite.issue(child)}: lane:close is incomplete`)
 }
 
 async function stash_work(child: string, directory: string): Promise<void> {
@@ -204,22 +217,30 @@ 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}`
 }
 
-// A child promoted to an epic by a split leaves its lane holding a seat: the epic root is never
-// dispatched again, so nothing else would ever close it. The lane is closed only when it holds
-// nothing — no commit, no change, no live process (`lane_vacant`); any other lane is kept, and why is
-// stated on the issue.
-async function close_split_lane(child: string): Promise<void> {
+// A child that ended without a merge closes its lane only when the lane holds nothing — no commit, no
+// change, no live process (`lane_vacant`); any other lane is kept for whoever resumes the issue.
+// Returns the kept lane, `undefined` where there was none or it was closed. joshuafolkken/kit#4028:
+// three children that ended doing nothing left lanes that filled the limit.
+async function close_vacant_lane(child: string): Promise<LaneInfo | undefined> {
 	const lane = await lane_registry.find_open_lane(child)
 
-	if (lane === undefined) return
+	if (lane === undefined) return undefined
 
-	if (await lane_vacant.is_vacant(lane)) {
-		await close_lane(child)
+	if (!(await lane_vacant.is_vacant(lane))) return lane
 
-		return
-	}
+	await close_lane(child)
+
+	return undefined
+}
+
+// A child promoted to an epic by a split leaves its lane holding a seat: the epic root is never
+// dispatched again, so nothing else would ever close it. A lane it keeps is stated on the issue.
+async function close_split_lane(child: string): Promise<void> {
+	const kept = await close_vacant_lane(child)
 
-	await git_gh_issue_write.issue_try_comment(child, kept_lane_comment(lane.directory))
+	if (kept !== undefined) {
+		await git_gh_issue_write.issue_try_comment(child, kept_lane_comment(kept.directory))
+	}
 }
 
 // The progress comment is a human-readable mirror of the carry record, so it is best-effort and only
@@ -230,25 +251,8 @@ 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 child merged while GitHub left it OPEN is closed here, through the one close `followup` uses
-// The state was just read OPEN, so it is read once rather than waited on. A
-// close that fails is reported with its recovery and does not undo the merge being counted.
-async function close_merged_open(ctx: MergeContext): Promise<void> {
-	if (ctx.merged_pr === undefined) return
-
-	try {
-		await git_followup_issue_close.ensure_issue_closed(
-			{ issue_number: ctx.child, pr_url: ctx.merged_pr, closer: MERGE_CLOSER },
-			SINGLE_READ,
-		)
-	} catch {
-		console.error(
-			`${session_cite.issue(ctx.child)}: could not be closed — ${git_followup_issue_close.CLOSE_RECOVERY}`,
-		)
-	}
-}
-
-// A merged child: count the merge (which resets the failure streak), return to the default branch,
+// 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.
@@ -257,7 +261,7 @@ async function do_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
 
 	if (refused !== undefined) return refused
 
-	await close_merged_open(ctx)
+	await run_merge_close.close_merged(ctx)
 	await sync_main()
 	const result = await apply_carry(ctx, {
 		...run_merge.change_of('merged'),
@@ -272,8 +276,17 @@ async function do_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
 	return undefined
 }
 
+// A child that ended without a merge: end whatever of its process still runs, 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 run_label.unmark(child)
+	await close_vacant_lane(child)
+}
+
 function refused_result(carry: RunCarry): FailedResult {
-	return { carry, is_parked: false, is_refused: true, blockers: NO_BLOCKERS }
+	return { carry, is_parked: false, is_refused: true, waits: NO_WAITS }
 }
 
 // The child's open `blocked-by` blockers, cited. A read that fails answers none, so the child is
@@ -286,66 +299,89 @@ async function open_blockers(child: string): Promise<ReadonlyArray<string>> {
 			.filter((blocker) => blocker.state === OPEN_STATE)
 			.map((blocker) => issue_cite.plain(blocker.number, blocker.repo))
 	} catch {
-		return NO_BLOCKERS
+		return NO_WAITS
 	}
 }
 
-// A child that ended unfinished while an open blocker it records still has to land first is waiting,
-// not failed: nothing is counted and `needs-decision` is not applied — the
-// order is already recorded, so there is nothing for a person to decide — and its stale `in-progress`
-// is dropped so the offer hands it back on its own once the blockers merge. The ownership guard is
-// still asked, so a session that does not own the run cannot release a child it never dispatched.
-async function do_waiting(
-	ctx: MergeContext,
-	blockers: ReadonlyArray<string>,
-): Promise<FailedResult> {
+// Whether the child carries `not-before` — the body's start date copied to a label. Read only where the
+// body could not be: the body is the source, so a label it no longer backs is never a wait.
+async function has_not_before_label(ctx: MergeContext): Promise<boolean> {
+	const read = await issue_state_cli.read_issue(ctx.child, ctx.repo)
+
+	return read.kind === 'state' && has_label_name(read.state.labels, NOT_BEFORE_LABEL)
+}
+
+// The child's declared start date while it is still ahead (joshuafolkken/kit#4076), or its `not-before`
+// label when the body could not be read (joshuafolkken/kit#4102), or the samples it still waits on. A
+// due date or none answers none, so the child is parked as before.
+async function start_date_wait(ctx: MergeContext): Promise<ReadonlyArray<string>> {
+	const body = await git_gh_command.issue_get_body(ctx.child, ctx.repo)
+
+	if (body === undefined) return (await has_not_before_label(ctx)) ? [NOT_BEFORE_WAIT] : NO_WAITS
+
+	await issue_sample_gate.prime([body])
+	const reason = issue_not_before.waiting_reason(body)
+
+	return reason === undefined ? NO_WAITS : [reason]
+}
+
+// A child that ended unfinished while an open blocker it records still has to land first, or while
+// its declared start date is still ahead, is waiting, not failed: nothing is counted and
+// `needs-decision` is not applied — when it runs is already recorded, so there is nothing for a person
+// to decide — and its stale `in-progress` is dropped so the offer hands it back on its own once the
+// blockers merge and the date arrives. The ownership guard is still asked, so a session that does not
+// own the run cannot release a child it never dispatched.
+async function do_waiting(ctx: MergeContext, waits: ReadonlyArray<string>): Promise<FailedResult> {
 	const refused = await refused_carry(ctx)
 
 	if (refused !== undefined) return refused_result(refused)
 
-	lane_reap.reap_child(ctx.child)
-	await run_label.unmark(ctx.child)
-	await git_gh_issue_write.issue_try_comment(ctx.child, run_merge.waiting_comment(blockers))
+	await release_child(ctx.child)
+	await git_gh_issue_write.issue_try_comment(ctx.child, run_merge.waiting_comment(waits))
 
-	return { carry: undefined, is_parked: false, is_refused: false, blockers }
+	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
 // 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 `needs-decision` so the next
-// offer does not hand the same child straight back. Returns the record so the caller can read the
-// streak against the guard. Returns `is_refused: true` without touching labels when the carry record
+// 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
+// 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: string): Promise<FailedResult> {
+async function park_failed(ctx: MergeContext, cause: StallCause): Promise<FailedResult> {
 	const result = await apply_carry(ctx, run_merge.change_of('failed'))
 
 	if (result.kind === 'refused') return refused_result(result.carry)
 
 	const carry = result.kind === 'applied' ? result.carry : undefined
 
-	lane_reap.reap_child(ctx.child)
-	await run_label.unmark(ctx.child)
-	const is_parked = await git_gh_issue_write.issue_add_label(ctx.child, NEEDS_DECISION_LABEL)
-
-	if (is_parked) {
-		const reason = { child: ctx.child, cause, carry, output: ctx.output }
+	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))
 
-		await git_gh_issue_write.issue_try_comment(ctx.child, run_merge.park_comment(reason))
+	return {
+		carry,
+		is_parked: park.is_labelled,
+		is_refused: false,
+		waits: NO_WAITS,
+		cause: cause.short,
 	}
-
-	return { carry, is_parked, is_refused: false, blockers: NO_BLOCKERS }
 }
 
-// A child that ended unfinished: waiting when it records an open blocker (`do_waiting`), parked
-// otherwise (`park_failed`) — an order already recorded is never a decision for a person. Without a
-// cause of the caller's, a child whose detached ship ended is parked for the ship's stop.
-async function do_failed(ctx: MergeContext, cause?: string): Promise<FailedResult> {
-	const blockers = await open_blockers(ctx.child)
+// A child that ended unfinished: waiting when it records an open blocker or a start date still ahead
+// (`do_waiting`), parked otherwise (`park_failed`) — a recorded order or date is never a decision for a
+// person. Without a cause of the caller's, a child whose detached ship ended is parked for the ship's
+// stop.
+async function do_failed(ctx: MergeContext, cause?: StallCause): Promise<FailedResult> {
+	const waits = [...(await open_blockers(ctx.child)), ...(await start_date_wait(ctx))]
+
+	if (waits.length > 0) return await do_waiting(ctx, waits)
 
-	if (blockers.length > 0) return await do_waiting(ctx, blockers)
+	const judged = cause ?? run_merge_ship.cause(ctx.child) ?? run_stalled.SESSION_UNFINISHED
 
-	return await park_failed(ctx, cause ?? run_merge_ship.cause(ctx.child) ?? FAILED_CAUSE)
+	return await park_failed(ctx, judged)
 }
 
 // The outcome of counting an outage: the record to read the streak against, and whether the count was
@@ -362,7 +398,7 @@ interface OutageResult {
 // outage streak against its guard. Returns `is_refused: true` without touching labels when the carry
 // record rejected the count.
 async function count_outage(ctx: MergeContext): Promise<ApplyCarryResult> {
-	if (ctx.is_unanswered !== true) return await apply_carry(ctx, run_merge.change_of('outage'))
+	if (ctx.is_streak_exempt !== true) return await apply_carry(ctx, run_merge.change_of('outage'))
 
 	const refused = await refused_carry(ctx)
 
@@ -374,8 +410,7 @@ async function do_outage(ctx: MergeContext): Promise<OutageResult> {
 
 	if (result.kind === 'refused') return { carry: result.carry, is_refused: true }
 
-	lane_reap.reap_child(ctx.child)
-	await run_label.unmark(ctx.child)
+	await release_child(ctx.child)
 
 	return { carry: result.kind === 'applied' ? result.carry : undefined, is_refused: false }
 }
@@ -452,9 +487,9 @@ async function ask_next(ctx: MergeContext): Promise<string> {
 }
 
 const run_merge_steps = {
-	CUT_RELAUNCH_CAUSE,
 	ask_next,
 	close_split_lane,
+	release_child,
 	do_failed,
 	do_merged,
 	do_outage,

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

@@ -1,12 +1,13 @@
-import { issue_cite } from '#scripts/issue/issue-cite'
 import {
-	ALREADY_DONE_LABEL,
 	EPIC_LABEL,
 	has_label_name,
-	NEEDS_DECISION_LABEL,
+	has_parked_label,
+	RUN_STALLED_LABEL,
 } from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import type { CarryChange, RunCarry } from '#scripts/run/carry/run-carry'
+import { run_stalled } from '#scripts/run/park/run-stalled'
+import type { ChildOutcome } from './run-merge-outcome'
 
 // The pure core of `run:merge`, the one composite command for a `backlogrun` merge event: the parent —
 // the session whose context is largest and per-turn cost highest — calls `run:merge <N>` once at a
@@ -38,28 +39,22 @@ const ONE = 1
 //                   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).
-// - `parked`      — OPEN and carrying `needs-decision` or `already-done`; a person still owns it.
+// - `parked`      — OPEN and carrying a park label (`PARKED_LABELS`); a person still owns it.
 // - `split`       — OPEN and carrying `epic`; its work was divided into new children.
-// - `outage`      — OPEN and carrying neither, but the exit record shows it could not reach the API; not
-//                   the child's failure, so it is re-dispatchable and uncounted against the failure guard.
+// - `outage`      — OPEN and carrying neither, but the exit record shows it could not reach the API, a
+//                   host restart killed it, or its ship stop went unanswered; not the child's failure, so
+//                   it is re-dispatchable and uncounted against the failure guard.
 // - `cut`         — OPEN and carrying neither, but its lane holds a declared cut no successor adopted;
 //                   the child ended its session on purpose, so it is resumed rather than parked and
 //                   counts nothing.
+// - `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).
 // - `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: closed as not planned, or about to be, it is neither merged nor failed.
+//                   GitHub state: left OPEN for the next run, it is neither merged nor failed.
 // - `unresolved`  — the state could not be read; re-read before deciding.
-type ChildOutcome =
-	| 'merged'
-	| 'withdrawn'
-	| 'human-review'
-	| 'parked'
-	| 'split'
-	| 'cut'
-	| 'outage'
-	| 'failed'
-	| 'unresolved'
-	| 'shipping'
+// The names themselves are `run-merge-outcome.ts`'s.
 
 // What the CLI read beside the GitHub state: whether the exit record is an API outage, and whether the
 // lane holds a cut its successor never adopted.
@@ -71,8 +66,11 @@ interface EndingSignals {
 	merged_pr?: string | undefined
 	// The newest launch of the child was withdrawn by a person (`run_event_scope.is_withdrawn`).
 	is_withdrawn?: boolean | undefined
-	// The outage is a ship stop no relaunch answered, not an API the child could not reach.
-	is_unanswered?: 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
 }
 
 const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
@@ -81,12 +79,10 @@ function is_closed(state: IssueState): boolean {
 	return state.state.toUpperCase() === CLOSED_STATE
 }
 
-// A parked child is one a person still owns: it stopped for a decision (`needs-decision`) or it was
-// found already merged (`already-done`). Either way it is left alone and not counted as a failure.
-const PARK_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
-
+// A parked child is one a person still owns (`PARKED_LABELS`): it is left alone and not counted as a
+// failure again.
 function is_parked(state: IssueState): boolean {
-	return PARK_LABELS.some((label) => has_label_name(state.labels, label))
+	return has_parked_label(state.labels)
 }
 
 // **CLOSED means merged, whatever labels it carries** — a child that finished and merged keeps the
@@ -102,6 +98,8 @@ 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'
 }
 
@@ -117,8 +115,8 @@ function open_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
 
 // 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`
-// records it before stopping the child, so the parent may collect it while the issue is still OPEN, and
-// once it is CLOSED as not planned the closed state would otherwise read as a merge.
+// 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,
@@ -173,7 +171,7 @@ function counters_comment(carry: RunCarry): string {
 }
 
 // Why the run parked a child it judged failed. A child that stops itself leaves its own comment; one
-// the driver stops leaves none, so this tells a person why it carries `needs-decision`.
+// the driver stops leaves none, so this tells a person why it carries `run:stalled`.
 // Script-emitted, so English.
 interface ParkReason {
 	child: string
@@ -192,21 +190,22 @@ function park_comment(reason: ParkReason): string {
 	const transcript = reason.output === undefined ? '' : ` (\`${reason.output}\`)`
 
 	return [
-		'Parked with `needs-decision` by `pnpm josh run:merge`, the `backlogrun` driver — not by the child itself.',
+		`Parked with \`${RUN_STALLED_LABEL}\` by \`pnpm josh run:merge\`, the \`backlogrun\` driver — a mechanical failure, with no decision to make.`,
 		`- Why: ${reason.cause}`,
-		'- Read: the issue is OPEN, carries none of `needs-decision`, `already-done`, `needs-human-review` or `epic`, and no merged pull request’s `closes #N` names it.',
+		'- Read: the issue is OPEN, carries no park label, `needs-human-review` or `epic`, no merged pull request’s `closes #N` names it, and it declares no open blocker, start date still ahead or sample condition not yet met.',
 		streak_line(reason.carry),
-		`- Next: read the child’s transcript${transcript}, then either resume it with \`fullrun ${issue_cite.plain(reason.child)}\`, or record the decision here and remove \`needs-decision\`.`,
+		`- Next: read the child’s transcript${transcript}, ${run_stalled.next_step(reason.child)}.`,
 	].join('\n')
 }
 
-// Why the run released a child it would otherwise have parked: the child records open blockers, so
-// its order is already decided and it waits rather than asking a person. Script-emitted, so English.
-function waiting_comment(blockers: ReadonlyArray<string>): string {
+// Why the run released a child it would otherwise have parked: the child records open blockers or a
+// start date still ahead or samples still short, so when it runs is already decided and it waits rather than asking a person.
+// Script-emitted, so English.
+function waiting_comment(waits: ReadonlyArray<string>): string {
 	return [
 		'Released to wait by `pnpm josh run:merge`, the `backlogrun` driver — not parked, and not counted as a failure.',
-		`- Why: the child’s session ended unfinished while it records open blockers: ${blockers.join(', ')}.`,
-		'- Next: its order is already recorded — it becomes runnable again once its blockers merge; a blocker outside the backlog still needs a person to land it.',
+		`- Why: the child’s session ended unfinished while it waits on: ${waits.join(', ')}.`,
+		'- Next: when it runs is already recorded — it becomes runnable again once its blockers merge, its start date arrives and its sample condition is met; a blocker outside the backlog still needs a person to land it.',
 	].join('\n')
 }
 
@@ -222,5 +221,7 @@ const run_merge = {
 	is_outage_guard_tripped,
 }
 
-export type { ChildOutcome, EndingSignals, ParkReason }
+export type { EndingSignals, ParkReason }
 export { run_merge }
+
+export { type ChildOutcome } from './run-merge-outcome'