@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,7 +1,10 @@
 import { gate_skip } from '#scripts/gate/gate-skip'
-import { gate_tree } from '#scripts/gate/gate-tree'
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { metrics_totals } from '#scripts/gate/metrics-totals'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { run_ship_lap } from './run-ship-lap'
+import { run_ship_synced_scope } from './run-ship-synced-scope'
 
 // The scoped pair `josh ship` meets itself rather than stops on, shared by every stage that needs a
 // green record for this tree: the preflight stage at the start, the review rounds, and the gate
@@ -25,13 +28,30 @@ async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
 	return last
 }
 
+// The tree after the branch's metrics approval is re-recorded (`metrics-totals.ts`): every review fix
+// and the gate stage meet the pair here, so a rewrite lands before any record is written for the tree.
+async function rerecorded_tree(): Promise<GateTree> {
+	const tree = await gate_tree.read_gate_tree()
+	const is_rerecorded = await metrics_totals.rerecord(process.cwd(), tree.files)
+
+	return is_rerecorded ? await gate_tree.read_gate_tree() : tree
+}
+
 // Only the checks with no green record for this tree run — the same question `review:brief` and the
 // local gate refuse on — so a fresh record costs nothing and a stale or absent one costs a scoped run
 // instead of a stop and a relaunched session. A check that genuinely fails still stops the ship, its
-// output forwarded to the ship log.
-async function scoped_pair(): Promise<JoshResult> {
-	const tree = await gate_tree.read_gate_tree()
+// output forwarded to the ship log. A pair stale only because a merge with the default branch moved the
+// base runs nothing when the merge shares nothing with the branch (`run-ship-synced-scope.ts`).
+async function settled_pair(): Promise<JoshResult> {
+	const tree = await rerecorded_tree()
 	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
+	const settled = await run_ship_synced_scope.settle(tree, scripts)
+
+	if (settled !== undefined) {
+		process.stdout.write(`${settled}\n`)
+
+		return { code: SUCCESS_EXIT_CODE, out: settled }
+	}
 
 	return await run_phases(
 		scripts.map(
@@ -40,13 +60,22 @@ async function scoped_pair(): Promise<JoshResult> {
 	)
 }
 
-// The scoped pair and then `josh gate` — the gate stage, and the followup's gate over a merged tree
-// before its push, so both leave the record the pre-push hook reuses.
-async function scoped_gate(): Promise<JoshResult> {
-	return await run_phases([
-		scoped_pair,
+// Timed as one lap in whichever ship stage asked for it (`run-ship-lap.ts`).
+async function scoped_pair(): Promise<JoshResult> {
+	return await run_ship_lap.timed(run_ship_lap.STEP.SCOPED_PAIR, settled_pair)
+}
+
+async function gate(): Promise<JoshResult> {
+	return await run_ship_lap.timed(
+		run_ship_lap.STEP.GATE,
 		async () => await josh_command.josh_run(['gate'], should_forward_stderr),
-	])
+	)
+}
+
+// The scoped pair and then `josh gate` — the gate stage, and the commit stage's and the followup's gate
+// over a merged tree before their push, so each leaves the record the pre-push hook reuses.
+async function scoped_gate(): Promise<JoshResult> {
+	return await run_phases([scoped_pair, gate])
 }
 
 // Whether `josh gate` would only reuse this tree's green record: the gate's own reuse test rather than

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

@@ -14,7 +14,7 @@ import { z } from 'zod'
 // the state, and a stale one is overruled by it. Neither can produce a second commit, push or merge.
 //
 // **The gate is never skipped on the record's word.** It is passed over only once its output — a
-// commit — exists; otherwise it runs, and `josh gate`'s own tree-keyed green record is what makes a
+// pushed commit — exists; otherwise it runs, and `josh gate`'s own tree-keyed green record is what makes a
 // re-run on an unchanged tree a reuse rather than a second execution. No quality gate is folded away.
 
 const STAGE = {
@@ -44,6 +44,11 @@ interface ShipState {
 	is_committed: boolean
 	is_pushed: boolean
 	is_merged: boolean
+	// The issue changed after the recorded review's brief (`issue-watch-gate.ts`), so the review re-runs
+	// even on a committed tree (joshuafolkken/kit#4221).
+	is_review_stale?: boolean
+	// The tree holds uncommitted work, which the sync stage commits locally before it merges.
+	is_dirty?: boolean
 }
 
 const RECORD_PREFIX = 'josh-ship-stages-'
@@ -54,17 +59,29 @@ const WORD_SEPARATOR = ' '
 const STARTED_SEPARATOR = ','
 const STARTED_INDEX = 3
 const WORD_COUNT = STARTED_INDEX + 1
+// The reason a stage ran or was skipped follows the words, behind a separator no word holds, so the
+// word readers below read the line as before.
+const REASON_SEPARATOR = ' | '
 
 // `started` lists the stages the current attempt started, kept across a supervisor that ended without a
-// stop so its successor's lines still carry them.
+// stop so its successor's lines still carry them. `is_merge_waiting` is set only while `josh followup`
+// itself runs, `is_place_waiting` only while a followup stop waits for a lane place
+// (`run-ship-place.ts`) (joshuafolkken/kit#4466).
 const record_schema = z.object({
 	done: z.array(z.string()),
 	started: z.array(z.string()).default([]),
+	is_merge_waiting: z.boolean().default(false),
+	is_place_waiting: z.boolean().default(false),
 })
 
 type ShipRecord = z.infer<typeof record_schema>
 
-const EMPTY_RECORD: ShipRecord = { done: [], started: [] }
+const EMPTY_RECORD: ShipRecord = {
+	done: [],
+	started: [],
+	is_merge_waiting: false,
+	is_place_waiting: false,
+}
 
 // Keyed on the repository and the issue: every lane of one repository shares the common git directory,
 // and two issues shipping from two lanes keep two records.
@@ -109,7 +126,36 @@ function mark_started(target: string, stage: Stage): void {
 // A `ship-stop` ends the attempt on the board (`run-board-phase.ts`), so the next attempt lists afresh
 // while the completed stages stay recorded.
 function end_attempt(target: string): void {
-	stamp_file.replace_stamp(target, { ...read_record(target), started: [] })
+	stamp_file.replace_stamp(target, { ...read_record(target), started: [], is_merge_waiting: false })
+}
+
+// Whether the ship waits on CI, CodeRabbit and the merge alone: its lane then holds no place under the
+// lane limit (`backlog-occupied.ts`). Cleared before any gate the followup stage runs, at a stop, and
+// when a successor supervisor opens the record, so a dead supervisor's flag frees nothing.
+function read_merge_waiting(target: string): boolean {
+	return read_record(target).is_merge_waiting
+}
+
+function mark_merge_waiting(target: string, is_merge_waiting: boolean): void {
+	stamp_file.replace_stamp(target, { ...read_record(target), is_merge_waiting })
+}
+
+// Whether a followup stop waits for a place before it relaunches its child (`run-ship-place.ts`).
+function read_place_waiting(target: string): boolean {
+	return read_record(target).is_place_waiting
+}
+
+function mark_place_waiting(target: string, is_place_waiting: boolean): void {
+	stamp_file.replace_stamp(target, { ...read_record(target), is_place_waiting })
+}
+
+// A supervisor that died mid-wait left its wait marked; its successor waits on nothing yet.
+function clear_waits(target: string): void {
+	stamp_file.replace_stamp(target, {
+		...read_record(target),
+		is_merge_waiting: false,
+		is_place_waiting: false,
+	})
 }
 
 // Removed once the report stage completes, so a later ship of the same issue starts from the preflight.
@@ -123,18 +169,23 @@ function is_shipped(state: ShipState): boolean {
 	return state.is_committed && state.is_pushed
 }
 
+// A lane child's `run:review` commits and pushes before the ship runs (joshuafolkken/kit#4907), so a
+// commit or a push is a stage's output only beside the ship's own record of that stage.
 const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => boolean> = {
 	// The preflight asks what the commit stage would refuse on, so a commit is
-	// its output as it is the gate's; a resumed commit stage still asks `git -y`'s own preflight.
-	[STAGE.PREFLIGHT]: (_done, state) => state.is_merged || state.is_committed,
-	// The `--review` round precedes the commit, so a commit is its output as it
-	// is the gate's. A record alone is not honored: before a commit the tree may have been edited since
-	// the recorded round, and only a commit pins the tree that round read.
-	[STAGE.REVIEW]: (_done, state) => state.is_merged || state.is_committed,
-	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
-	// The merge of the default branch before the commit: once committed, a
-	// conflicting pull request is the followup's to merge again.
-	[STAGE.SYNC]: (_done, state) => state.is_merged || state.is_committed,
+	// its output; a resumed commit stage still asks `git -y`'s own preflight.
+	[STAGE.PREFLIGHT]: (done, state) =>
+		state.is_merged || (done.has(STAGE.PREFLIGHT) && state.is_committed),
+	// The sync stage commits locally before the review round and the gate, without pushing
+	// (`run-ship-sync.ts`), so a commit is neither's output: a pushed one on a clean tree is, as only the
+	// commit stage after the gate pushes — unless the issue changed since.
+	[STAGE.REVIEW]: (done, state) =>
+		state.is_merged ||
+		(done.has(STAGE.REVIEW) && is_shipped(state) && state.is_review_stale !== true),
+	[STAGE.GATE]: (done, state) => state.is_merged || (done.has(STAGE.GATE) && is_shipped(state)),
+	// The merge of the default branch before the gate: once pushed, a default branch that
+	// moved is the followup's to merge again.
+	[STAGE.SYNC]: (done, state) => state.is_merged || (done.has(STAGE.SYNC) && is_shipped(state)),
 	[STAGE.COMMIT]: (done, state) => state.is_merged || (done.has(STAGE.COMMIT) && is_shipped(state)),
 	// The round-2 pass reads the pushed fix delta, so its record is honored only
 	// while that push still stands — new work pushed on top reruns it.
@@ -173,9 +224,11 @@ function commit_flags(state: ShipState): ReadonlyArray<string> {
 // **The newest line carries the attempt's history**: a fourth word lists every
 // stage the attempt has started, so the one line per issue a stream full of positions keeps still
 // draws the whole track. A line with no started stage keeps the three-word form.
+// The stage is a word rather than a `Stage`: the pre-detach checks, which are not one, are written in
+// the same form (`run-ship-pre-detach-timed.ts`).
 function event_text(
 	issue: string,
-	stage: Stage,
+	stage: string,
 	phase: Phase,
 	started: ReadonlyArray<string> = [],
 ): string {
@@ -187,9 +240,32 @@ function event_text(
 	return full.join(WORD_SEPARATOR)
 }
 
+// A line `event_text` wrote, with why its stage ran or was skipped after it (joshuafolkken/kit#5296).
+function with_reason(text: string, reason: string | undefined): string {
+	return reason === undefined ? text : `${text}${REASON_SEPARATOR}${reason}`
+}
+
+function words_part(text: string): string {
+	return text.split(REASON_SEPARATOR, 1)[0] ?? ''
+}
+
 // The stages a line says its attempt has started, `undefined` for a three-word line.
 function started_of(text: string): ReadonlyArray<string> | undefined {
-	return text.split(WORD_SEPARATOR, WORD_COUNT)[STARTED_INDEX]?.split(STARTED_SEPARATOR)
+	return words_part(text).split(WORD_SEPARATOR, WORD_COUNT)[STARTED_INDEX]?.split(STARTED_SEPARATOR)
+}
+
+// The stage word and the phase word of a line `event_text` wrote, `''` where the line has none.
+function words_of(text: string): { stage: string; phase: string } {
+	const [, stage = '', phase = ''] = words_part(text).split(WORD_SEPARATOR, WORD_COUNT)
+
+	return { stage, phase }
+}
+
+// Why the stage ran or was skipped, `undefined` for a line that carries no reason.
+function reason_of(text: string): string | undefined {
+	const at = text.indexOf(REASON_SEPARATOR)
+
+	return at === -1 ? undefined : text.slice(at + REASON_SEPARATOR.length)
 }
 
 // A stop on a merge git could not finish is named `conflict` rather than by the stage it happened in,
@@ -205,16 +281,25 @@ const run_ship_stage = {
 	PHASE,
 	STAGE,
 	clear,
+	clear_waits,
 	commit_flags,
 	end_attempt,
 	event_text,
 	is_done,
+	is_shipped,
 	mark_done,
+	mark_merge_waiting,
+	mark_place_waiting,
 	mark_started,
 	read_done,
+	read_merge_waiting,
+	read_place_waiting,
 	read_started,
+	reason_of,
 	record_path,
 	started_of,
+	with_reason,
+	words_of,
 	stop_reason,
 }
 

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

@@ -1,15 +1,19 @@
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { run_ship } from './run-ship'
+import { run_ship_body_draft } from './run-ship-body-draft'
+import { run_ship_lap } from './run-ship-lap'
 import { run_ship_preflight } from './run-ship-preflight'
+import { run_ship_probe } from './run-ship-probe'
 import { run_ship_review_steps } from './run-ship-review-steps'
 import { run_ship_scoped } from './run-ship-scoped'
 import { run_ship_stage, type ShipState, type Stage } from './run-ship-stage'
-import { run_ship_sync, type StepResult } from './run-ship-sync'
+import { run_ship_sync, type StepResult, type WaitMark } from './run-ship-sync'
 
 // The stages `josh ship` runs, in the order a change ships, kept apart from the chaining
 // CLI so the order is read in one place.
 
 const should_forward_stderr = true
+const SUCCESS_EXIT_CODE = 0
 
 interface ShipArguments {
 	title: string
@@ -20,6 +24,8 @@ interface ShipArguments {
 	cites: ReadonlyArray<string>
 	is_review: boolean
 	is_detach: boolean
+	// `--unpinned-ok "<reason>"` as given, forwarded to round 1's `run:review` alone; empty when absent.
+	unpinned_ok: ReadonlyArray<string>
 }
 
 interface Step {
@@ -54,19 +60,36 @@ async function gate_stage(): Promise<StepResult> {
 	return { ...result, is_skipped }
 }
 
+// The default branch is merged before the gate, so the pull request opens on a branch that is current;
+// a clean merge goes on without waking anyone. A merge after the gate would move the merge base the
+// gate's record pins, so the pre-push hook could not reuse that record. **With `--review` it runs before
+// round 1 too**: the gate round 1 launches then reads the base the commit carries, so a clean round
+// leaves the gate stage a reuse rather than a whole second gate over a moved base (joshuafolkken/kit#4442).
+const SYNC_STEP: Step = {
+	stage: STAGE.SYNC,
+	header: run_ship.SYNC_HEADER,
+	run: async (args, state) =>
+		await run_ship_sync.sync_stage(args.number, args.title, state.is_dirty === true),
+}
+
+// A default branch that moved since the sync stage is merged and gated again before the push
+// (`run_ship_sync.catch_up`, joshuafolkken/kit#4825). A resumed ship with nothing left to push leaves
+// that to the followup, which pushes what it merges; a pushed branch with new work still catches up.
+async function commit_stage(args: ShipArguments, state: ShipState): Promise<StepResult> {
+	const stop = run_ship_stage.is_shipped(state) ? undefined : await run_ship_sync.catch_up()
+
+	if (stop !== undefined) return stop
+
+	const argv = ['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]
+
+	return await run_ship_lap.timed(run_ship_lap.STEP.COMMIT, async () => await josh(argv))
+}
+
 // The gate before the commit, the commit/push/PR before the merge. The gate meets the scoped pair
 // first: a round-1 reviewer may have edited the tree since the preflight, and `josh gate` refuses a tree
 // with no green record. The commit step carries the `--skip-*` flags a resumed ship needs, so an
 // existing commit or push is never made twice.
 const COMMIT_STEPS: ReadonlyArray<Step> = [
-	// The default branch is merged again before the commit, so the pull request opens on a branch that
-	// is current; a clean merge goes on without waking anyone. It runs before the gate: a merge after it
-	// would move the merge base the gate's record pins, so the pre-push hook could not reuse that record.
-	{
-		stage: STAGE.SYNC,
-		header: run_ship.SYNC_HEADER,
-		run: async (args) => await run_ship_sync.sync_stage(args.number),
-	},
 	{
 		stage: STAGE.GATE,
 		header: run_ship.GATE_HEADER,
@@ -75,17 +98,40 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.COMMIT,
 		header: run_ship.COMMIT_HEADER,
-		run: async (args, state) =>
-			await josh(['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]),
+		run: async (args, state) => await commit_stage(args, state),
 	},
 ]
 
+// The followup's merge wait on the stage record, written best-effort as the stages are
+// (`run-ship-cli.ts`): a lost mark only keeps the lane counted (joshuafolkken/kit#4466).
+function wait_mark(target: string | undefined): WaitMark {
+	return function mark(is_merge_waiting: boolean): void {
+		if (target === undefined) return
+
+		try {
+			run_ship_stage.mark_merge_waiting(target, is_merge_waiting)
+		} catch {
+			// Best-effort: an unmarked wait holds the lane's place, the safe direction.
+		}
+	}
+}
+
+// The merge, then the ship body draft goes with it (`run-ship-body-draft.ts`).
+async function followup_stage(args: ShipArguments): Promise<StepResult> {
+	const mark = wait_mark(await run_ship_probe.record_target(args.number))
+	const result = await run_ship_sync.followup_stage(args.title, args.notify, mark)
+
+	if (result.code === SUCCESS_EXIT_CODE) await run_ship_body_draft.remove(args.number)
+
+	return result
+}
+
 // The merge before the report bookkeeping.
 const MERGE_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.FOLLOWUP,
 		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await run_ship_sync.followup_stage(args.title, args.notify),
+		run: async (args) => await followup_stage(args),
 	},
 	{
 		stage: STAGE.REPORT,
@@ -95,14 +141,19 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 ]
 
 // `--review` puts the supervised round-1 review in front of the gate: it launches the gate itself, so
-// the gate stage that follows reuses that tree's green record unless the sync stage between them
-// merged the default branch and changed the tree. It also puts the round-2 pass between the commit
+// the gate stage that follows reuses that tree's green record unless the round changed the tree. It
+// also puts the round-2 pass between the commit
 // and the followup, so the PR opens between the rounds and round 2 runs beside CI — a no-op when
 // round 1 left no fix delta.
 const REVIEW_STEP: Step = {
 	stage: STAGE.REVIEW,
 	header: run_ship.REVIEW_HEADER,
-	run: async (args) => await run_ship_review_steps.review_stage(args.number),
+	run: async (args, state) =>
+		await run_ship_review_steps.review_stage(
+			args.number,
+			state.is_review_stale === true,
+			args.unpinned_ok,
+		),
 }
 const ROUND_TWO_STEP: Step = {
 	stage: STAGE.ROUND_TWO,
@@ -111,9 +162,9 @@ const ROUND_TWO_STEP: Step = {
 }
 
 function steps(args: ShipArguments): ReadonlyArray<Step> {
-	if (!args.is_review) return [PREFLIGHT_STEP, ...COMMIT_STEPS, ...MERGE_STEPS]
+	if (!args.is_review) return [PREFLIGHT_STEP, SYNC_STEP, ...COMMIT_STEPS, ...MERGE_STEPS]
 
-	return [PREFLIGHT_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
+	return [PREFLIGHT_STEP, SYNC_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
 }
 
 const run_ship_steps = { PREFLIGHT_STEP, steps }

package/scripts/run/ship/run-ship-stop-cause.ts

@@ -0,0 +1,176 @@
+import { api_auth } from '#scripts/agent/api-auth'
+import { UNREADABLE_COMMENTS_STOP } from '#scripts/gh/git-gh-comments-unreadable'
+import { gh_retry } from '#scripts/gh/git-gh-retry'
+import { NO_CHECKS_MESSAGE } from '#scripts/gh/git-pr-checks-watch'
+import { git_error } from '#scripts/git/git-error'
+import type { StopRecord } from '#scripts/lane/lane-ledger-schema'
+import { run_ship_review, type StopFinding } from './run-ship-review'
+import { run_ship_stage, type Stage } from './run-ship-stage'
+
+// Why a `josh ship` stage stopped, beside the stage it stopped at: a review that found something, a
+// merge git could not finish, a check that went red, or the infrastructure — a rate limit, a check list
+// GitHub did not return, a network blip — that a re-run clears (joshuafolkken/kit#3998).
+//
+// **Only a stage whose output is the tooling's own is read for infrastructure**: a gate's or a review's
+// output carries test titles and findings, which may name a rate limit without being one, and their
+// stops are the quality gate's own verdict — never retried, never relabelled.
+//
+// **A review round names its own cause**: the step of the round that stopped tags its result — a red
+// join or scoped pair `check`, a reviewer that did not finish `infra`, a refused attestation `attest` —
+// so only a stop on a recorded finding counts as one (joshuafolkken/kit#4431). An untagged review stop
+// stays a finding.
+
+const CAUSE = {
+	FINDING: 'finding',
+	INFRA: 'infra',
+	CONFLICT: 'conflict',
+	CHECK: 'check',
+	AUTH: 'auth',
+	ATTEST: 'attest',
+} as const
+
+type Cause = (typeof CAUSE)[keyof typeof CAUSE]
+
+const { STAGE } = run_ship_stage
+const REVIEW_STAGES: ReadonlySet<Stage> = new Set([STAGE.REVIEW, STAGE.ROUND_TWO])
+const INFRA_STAGES: ReadonlySet<Stage> = new Set([
+	STAGE.SYNC,
+	STAGE.COMMIT,
+	STAGE.FOLLOWUP,
+	STAGE.REPORT,
+])
+const INFRA_PATTERNS: ReadonlyArray<RegExp> = [
+	/rate limit/iu,
+	new RegExp(NO_CHECKS_MESSAGE, 'u'),
+	new RegExp(UNREADABLE_COMMENTS_STOP, 'u'),
+	/\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND)\b/u,
+	/socket hang up/iu,
+	/could not resolve host/iu,
+	/\bHTTP 50[234]\b/u,
+]
+
+function is_infra(output: string): boolean {
+	return INFRA_PATTERNS.some((pattern) => pattern.test(output))
+}
+
+// A reviewer that could not authenticate is no finding: the review steps put `AUTH_FAILURE_NOTE` at the
+// head of a stop line (`isolated reviewer failed: <note>` or `<note>`), and only there is it read — a
+// finding that quotes the note mid-line stays a finding (joshuafolkken/kit#4216).
+const AUTH_LINE = new RegExp(
+	`^(?:isolated reviewer failed: (?:the broker answered a failure: )?)?${api_auth.AUTH_FAILURE_NOTE}`,
+	'mu',
+)
+
+function is_review(stage: Stage): boolean {
+	return REVIEW_STAGES.has(stage)
+}
+
+function review_cause(output: string, tagged: Cause = CAUSE.FINDING): Cause {
+	return AUTH_LINE.test(output) ? CAUSE.AUTH : tagged
+}
+
+// What a stopped stage handed back: its output, the paths a stopped merge left unmerged, the kinds
+// of the preconditions a stopped preflight found unmet, and the cause a review round tagged its stop with.
+interface StoppedOutput {
+	body: string
+	// The standard output alone, read for the infrastructure in place of the body when present.
+	out?: string
+	conflicts?: ReadonlyArray<string>
+	preconditions?: ReadonlyArray<string>
+	cause?: Cause
+}
+
+const NO_OUTPUT: StoppedOutput = { body: '' }
+
+// A failed stage's body also carries its stderr, where a poll warns of a transient rate limit it then
+// recovered from — so the infrastructure is read on the standard output alone wherever the stage kept it.
+function infra_text({ body, out = body }: StoppedOutput): string {
+	return out
+}
+
+const FAILURE_LINE = new RegExp(`^${git_error.FAILURE_PREFIX} `, 'gmu')
+const REPORTED_LINE = new RegExp(
+	`^(?:${git_error.FAILURE_PREFIX}|${git_error.DETAILS_PREFIX}) (?<message>.*)$`,
+	'gmu',
+)
+
+// The failure the stage ended on — the last `❌ Error:` line — and the cause logged under it: a caller
+// that wraps a spent request (a merge whose read-back failed too, a timed-out exec) ends on its own
+// message, with the request's beneath.
+function final_failures(body: string): ReadonlyArray<string> {
+	const last = [...body.matchAll(FAILURE_LINE)].at(-1)
+	if (last === undefined) return []
+
+	return [...body.slice(last.index).matchAll(REPORTED_LINE)].map(
+		({ groups }) => groups?.['message'] ?? '',
+	)
+}
+
+// A gh request transient to its last attempt notes so on stderr — gh's own transient verdict, never a
+// second list of its errors (joshuafolkken/kit#5052). A caller may catch it and stop later on a red
+// check, so the note counts only when it names the failure the stage ended on, or that failure's cause.
+function is_spent_stop(body: string): boolean {
+	return final_failures(body).some((message) => body.includes(gh_retry.spent_note(message)))
+}
+
+function is_infra_stop(failed: StoppedOutput): boolean {
+	return is_infra(infra_text(failed)) || is_spent_stop(failed.body)
+}
+
+// A gate an infrastructure stage ran itself tags its red as a check: its output is test output, where
+// a title naming a rate limit is no outage (joshuafolkken/kit#4825).
+function stage_cause(stage: Stage, failed: StoppedOutput): Cause {
+	if (failed.cause === CAUSE.CHECK || !INFRA_STAGES.has(stage)) return CAUSE.CHECK
+
+	return is_infra_stop(failed) ? CAUSE.INFRA : CAUSE.CHECK
+}
+
+function cause_of(stage: Stage, failed: StoppedOutput): Cause {
+	const { body, conflicts, cause } = failed
+	const reason = run_ship_stage.stop_reason(stage, conflicts)
+
+	if (reason === run_ship_stage.CONFLICT) return CAUSE.CONFLICT
+	if (is_review(stage)) return review_cause(body, cause)
+
+	return stage_cause(stage, failed)
+}
+
+// Whether a finding decided the stop — false on any other stop, and on a review stop no finding decided
+// (a red gate at the join, a reviewer that never answered).
+function is_finding_stop(stage: Stage, cause: Cause): boolean {
+	return is_review(stage) && cause === CAUSE.FINDING
+}
+
+// The kind of every blocking finding a review stop's output lists.
+function findings_of(stage: Stage, cause: Cause, body: string): ReadonlyArray<string> {
+	return is_finding_stop(stage, cause) ? run_ship_review.blocking_kinds(body) : []
+}
+
+// Each finding that decided a review stop, whole, for the durable stop log (joshuafolkken/kit#4519).
+function details_of(stage: Stage, failed: StoppedOutput = NO_OUTPUT): ReadonlyArray<StopFinding> {
+	if (!is_finding_stop(stage, cause_of(stage, failed))) return []
+
+	return run_ship_review.blocking_details(failed.body)
+}
+
+// The lane ledger's record of one stop — the stage, its cause and, for a preflight, which
+// preconditions were unmet, so `lane:stats` counts the one worth meeting before a ship
+// (joshuafolkken/kit#4166); for a review, which kinds of finding stopped it (joshuafolkken/kit#4426).
+function record_of(issue: number, stage: Stage, failed: StoppedOutput = NO_OUTPUT): StopRecord {
+	const { body, conflicts, preconditions } = failed
+	const cause = cause_of(stage, failed)
+	const findings = findings_of(stage, cause, body)
+
+	return {
+		issue,
+		reason: run_ship_stage.stop_reason(stage, conflicts),
+		cause,
+		...(preconditions !== undefined && { preconditions: [...preconditions] }),
+		...(findings.length > 0 && { findings: [...findings] }),
+	}
+}
+
+const run_ship_stop_cause = { CAUSE, cause_of, details_of, is_review, record_of }
+
+export type { Cause }
+export { run_ship_stop_cause }