@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/run/ship/run-ship-relaunch-cap.ts

@@ -0,0 +1,106 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_park } from '#scripts/issue/issue-park'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_stalled } from '#scripts/run/park/run-stalled'
+import { run_ship_stage } from './run-ship-stage'
+import { run_ship_stop_text } from './run-ship-stop-text'
+
+// How many times a stopped ship relaunches its lane child before the issue goes to a person. A child
+// that keeps stopping — the same red check, a finding it cannot close — would otherwise relaunch
+// without end, one ship's cost each time, with nobody told (joshuafolkken/kit#3999).
+//
+// **The count is the issue's `ship-stop` events since its last fresh dispatch**: a relaunch into the
+// lane emits no `child-launch`, a dispatch does, so a re-dispatched issue starts a new budget. The
+// current stop is emitted before the count is read, so it is part of it. Past the cap the issue is
+// parked with `run:stalled`, which every offer and the lane broker already refuse to start.
+// The whole stream is read, not the run's carry scope: the count scopes itself by issue and dispatch,
+// and a lane child shipping with no carry record (`lane:dispatch` outside a run, or a run already
+// ended) would otherwise read no events and relaunch without a cap.
+//
+// **Each kind of stop has its own cap** (joshuafolkken/kit#4707): a review stop (round 1 or round 2)
+// and a mechanical one (gate, sync, commit, followup, conflict) are counted apart, so the review's
+// back-and-forth never spends the relaunches a red CI run needs. The kind is read off the stop's text
+// (`run-ship-stop-text.ts`); a text with no stage reads as mechanical.
+
+// One dispatch's own stops in the measured week reached five once and four or fewer otherwise, so four
+// relaunches leave a ship that converges alone and stop the one that does not.
+const MAX_SHIP_STOP_RELAUNCHES = 4
+const PARK_CAUSE = 'ship-stop cap'
+const { CHILD_LAUNCH, PARK, SHIP_STOP } = run_event_stream.EVENT_KIND
+const STOP_KIND = { REVIEW: 'review', MECHANICAL: 'mechanical' } as const
+const REVIEW_REASONS: ReadonlySet<string> = new Set([
+	run_ship_stage.STAGE.REVIEW,
+	run_ship_stage.STAGE.ROUND_TWO,
+])
+
+type StopKind = (typeof STOP_KIND)[keyof typeof STOP_KIND]
+
+function kind_of(reason: string | undefined): StopKind {
+	return reason !== undefined && REVIEW_REASONS.has(reason)
+		? STOP_KIND.REVIEW
+		: STOP_KIND.MECHANICAL
+}
+
+function is_stop_of(event: RunEvent, kind: StopKind): boolean {
+	return event.kind === SHIP_STOP && kind_of(run_ship_stop_text.reason_of(event.text)) === kind
+}
+
+function stops_since_dispatch(
+	events: ReadonlyArray<RunEvent>,
+	issue: string,
+	kind: StopKind,
+): number {
+	const own = events.filter((event) => run_event_scope.issue_named(event) === issue)
+	const dispatched = own.findLastIndex((event) => event.kind === CHILD_LAUNCH)
+
+	return own.slice(dispatched + 1).filter((event) => is_stop_of(event, kind)).length
+}
+
+// `reason` is the current stop's; only the stops of its kind are counted.
+async function is_over(issue: string, reason: string): Promise<boolean> {
+	const events = await run_event_stream_emit.all_events()
+
+	return stops_since_dispatch(events, issue, kind_of(reason)) > MAX_SHIP_STOP_RELAUNCHES
+}
+
+function park_comment(issue: string, reason: string): string {
+	return [
+		`Parked by the \`josh ship\` supervisor: the ship stopped at \`${reason}\` after ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches of the lane child for ${kind_of(reason)} stops since its dispatch — the ${kind_of(reason)} stop cap was exceeded.`,
+		'',
+		`Read the stop with \`pnpm josh ship --log ${issue}\`, then ${run_stalled.next_step(issue)}.`,
+	].join('\n')
+}
+
+// The label is what keeps the issue from being re-dispatched; without it the stop stays a plain stop,
+// which `run:merge` books as an unanswered ship stop under its own outage cap.
+async function park(issue: string, reason: string): Promise<boolean> {
+	const park_write = await issue_park.apply(issue, RUN_STALLED_LABEL, park_comment(issue, reason))
+
+	if (!park_write.is_labelled) return false
+
+	const cite = issue_cite.plain(issue)
+
+	await run_event_stream_emit.emit(PARK, run_stalled.park_event(issue, PARK_CAUSE))
+	await telegram_notify.warn({
+		issue_title: `Ship stop cap reached ${cite}`,
+		body: `The lane child's ${kind_of(reason)} stops passed their cap of ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches since its dispatch, the last at ${reason}, so it was not relaunched and the issue is parked.`,
+		recovery: `Read pnpm josh ship --log ${issue}, then fix the cause and remove ${RUN_STALLED_LABEL} to offer it again.`,
+	})
+
+	return true
+}
+
+const run_ship_relaunch_cap = {
+	MAX_SHIP_STOP_RELAUNCHES,
+	STOP_KIND,
+	is_over,
+	kind_of,
+	park,
+	stops_since_dispatch,
+}
+
+export { run_ship_relaunch_cap }

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

@@ -0,0 +1,51 @@
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
+import { run_ship_detach } from './run-ship-detach'
+
+// A supervisor's successor on new code (`run-ship-handover.ts`) is the same launch: it keeps the launch
+// id, so every reader of the record — `ship:wait`, a lane's liveness, the overlap order by launch time —
+// sees one ship throughout, and the successor's claim and result land on that record.
+//
+// **The record keeps naming this supervisor until the successor claims it**
+// (`run_ship_detach.claim_identity`), so it is believed live throughout, and the successor's pid on it
+// is the take-over's proof.
+//
+// **The successor is this very process's command line, re-invoked under the same runner**, as the wake
+// supervisor re-invokes itself (`run-wake-session.ts`). Launched through `pnpm josh ship`, the spawned
+// pid would be pnpm's while the claim names the node process under it, so no claim would ever match.
+
+interface RelaunchRequest {
+	repository: string
+	number: string
+	cwd: string
+}
+
+// The pid the ship record names.
+function holder_pid(repository: string, number: string): number | undefined {
+	return run_ship_detach.read_record(repository, number)?.pid
+}
+
+// The supervisor's own argv ends with its `"<title> #<N>"` title, which a lane's liveness pattern needs.
+function successor_argv(): LaunchArgv {
+	return { command: process.execPath, args: [...process.execArgv, ...process.argv.slice(1)] }
+}
+
+// The successor's pid, `undefined` where this process is no supervisor or none started.
+function relaunch(request: RelaunchRequest): number | undefined {
+	const launch_id = process.env[run_ship_detach.LAUNCH_ID_KEY]
+	if (launch_id === undefined) return undefined
+	const result = detached_launch.launch(
+		{
+			argv: successor_argv(),
+			cwd: request.cwd,
+			log_path: run_ship_detach.log_path(request.repository, request.number),
+			env: run_ship_detach.supervisor_environment(launch_id),
+		},
+		console.error,
+	)
+
+	return result.kind === 'launched' ? result.pid : undefined
+}
+
+const run_ship_relaunch = { holder_pid, relaunch }
+
+export { run_ship_relaunch }

package/scripts/run/ship/run-ship-removed-rows.ts

@@ -0,0 +1,61 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { removed_tests } from '#scripts/review/removed-tests'
+import { removed_tests_check } from '#scripts/review/removed-tests-check'
+import { run_ship_body_draft } from './run-ship-body-draft'
+
+// **The tests a change removed, shown where a run passes before `josh ship`** — the end of a green
+// `josh test:related`. Their disposition rows were first asked at the ship's preflight, after the
+// pre-detach checks had run, and every lane that renamed a test stopped there and shipped again
+// (joshuafolkken/kit#4563). The removed titles are `removed_tests_check.read()`'s, and the pending
+// rows go into the branch's ship body draft, so the run only replaces each ending; the preflight still
+// refuses a row left pending.
+
+async function draft_of_branch(): Promise<string | undefined> {
+	const issue_number = git_branch.issue_from_branch(await git_command.branch())
+
+	if (issue_number === undefined) return undefined
+
+	return await run_ship_body_draft.existing(String(issue_number))
+}
+
+async function body_of(draft: string | undefined): Promise<string> {
+	return draft === undefined ? '' : await readFile(draft, 'utf8')
+}
+
+// An unreadable base lists nothing here — the preflight refuses on it — and outside a repository it
+// keeps the branch, which git could not answer, from being asked at all.
+async function removed_titles(): Promise<ReadonlyArray<string>> {
+	return (await removed_tests_check.read()) ?? []
+}
+
+function where(draft: string | undefined): string {
+	return draft === undefined
+		? 'Put these rows into the pull request body'
+		: `Pending rows for them are in the ship body draft ${draft}`
+}
+
+function notice(titles: ReadonlyArray<string>, draft: string | undefined): string {
+	return [
+		`Removed tests — this change removes ${String(titles.length)} test(s) the ship body does not dispose of yet. ${where(draft)}; replace each ending, ${removed_tests.ROW_FORMAT}, or the \`josh ship\` preflight refuses:`,
+		...titles.map((title) => `  - ${title}`),
+	].join('\n')
+}
+
+async function surface(): Promise<void> {
+	const removed = await removed_titles()
+
+	if (removed.length === 0) return
+	const draft = await draft_of_branch()
+	const body = await body_of(draft)
+	const titles = removed_tests.undisposed(removed, body)
+
+	if (titles.length === 0) return
+	if (draft !== undefined) await writeFile(draft, removed_tests.with_pending_rows(body, titles))
+	console.info(notice(titles, draft))
+}
+
+const run_ship_removed_rows = { surface }
+
+export { run_ship_removed_rows }

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

@@ -1,4 +1,7 @@
+import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { lane_child_invocation, type ShipStop } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
@@ -6,12 +9,18 @@ import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { lane_session_broker } from '#scripts/lane/lane-session-broker'
 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_wake_driver } from '#scripts/run/wake/run-wake-driver'
 import type { ShipSection } from './run-ship'
 import { run_ship_next, type ShipResume } from './run-ship-next'
+import { run_ship_place } from './run-ship-place'
+import { run_ship_probe } from './run-ship-probe'
+import { run_ship_relaunch_cap } from './run-ship-relaunch-cap'
 import { run_ship_stage, type Stage } from './run-ship-stage'
 import type { ShipArguments } from './run-ship-steps'
+import { run_ship_stop_cause } from './run-ship-stop-cause'
 import { run_ship_stop_context } from './run-ship-stop-context'
 import { run_ship_stop_text } from './run-ship-stop-text'
+import { run_ship_waiter } from './run-ship-waiter'
 
 // How a detached `josh ship` supervisor hands a stopped stage back. The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
@@ -25,16 +34,46 @@ import { run_ship_stop_text } from './run-ship-stop-text'
 //    effort because a fix is judgement. It is started before the supervisor exits, so the parent's
 //    liveness poll never sees the lane empty. An OpenAI lane is left to its own supervisor, which starts
 //    no successor without a cut, so its parent books the stop exactly as it books any ended child.
+//    The relaunches are capped: past the cap the issue is parked and a person told instead. A child
+//    still waiting on the ship (`josh ship:wait`) takes the stop itself, and nothing is relaunched.
 //
 // A ship run in an agent's own turn is not supervised and hands nothing back: its report is already in
 // front of the agent that ran it.
 
 const OPENAI_PROVIDER = 'openai'
+// A minute of polling, long enough for the supervisor's 5-second lane scan to reopen a server.
+const SERVING_POLL_MS = 1000
+const SERVING_POLLS = 60
+// The wait for a broker on older code to be replaced: its refusal makes its supervisor reload onto the
+// current code at its next pass boundary (`run-wake-code.ts`, joshuafolkken/kit#4714), which a pass reaches
+// after a driver window and the pause between passes; a minute more covers the takeover and the
+// successor's first lane scan. A driver that reruns a busy merge holds the pass longer still, and a ship
+// past the wait is re-dispatched with the version mismatch named.
+const RELOAD_POLLS =
+	(run_wake_driver.WINDOW_MS + backlog_budget.OFFER_INTERVAL_MS) / SERVING_POLL_MS + SERVING_POLLS
+const VERSION_MISMATCH_NOTE =
+	'the lane broker runs older code than this ship (a version mismatch), and no broker on the current code read the request within the wait'
 
-type ReturnOutcome = 'relaunched' | 'recorded'
+type ReturnOutcome = 'relaunched' | 'returned' | 'recorded' | 'parked' | 'redispatch'
 
-function stop_text(issue: string, stage: Stage, resume: ShipResume): string {
-	return run_ship_stop_text.format(issue, run_ship_stage.stop_reason(stage, resume.conflicts))
+// `unreadable`: the broker's code predates the request's shape, so it refused the request unread and
+// started nothing.
+type BrokerReply = 'started' | 'unreadable' | 'failed'
+
+// The broker's reply and, where it started nothing, the reason it gave.
+interface BrokerResult {
+	reply: BrokerReply
+	reason: string
+}
+
+// The failed stage's output, and its standard output alone where the stage kept it apart.
+type StageOutput = Pick<ShipSection, 'body' | 'out'>
+
+function stop_text(issue: string, stage: Stage, resume: ShipResume, output: StageOutput): string {
+	const reason = run_ship_stage.stop_reason(stage, resume.conflicts)
+	const cause = run_ship_stop_cause.cause_of(stage, { ...resume, ...output })
+
+	return run_ship_stop_text.format(issue, reason, cause)
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
@@ -53,14 +92,25 @@ function note(text: string): void {
 	process.stderr.write(`${text}\n`)
 }
 
-function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
+// **A relaunch that started nothing is recorded where `run:merge` reads it** (joshuafolkken/kit#4765): the
+// transcript's mtime cannot tell it from an answered stop, since the dispatch log's header is written
+// before the spawn. The reason is kept for the park a re-dispatch cap may end in.
+async function record_failed_relaunch(issue: string, reason: string): Promise<void> {
+	note(`the lane child could not be relaunched: ${reason}`)
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.RELAUNCH_FAILED,
+		`${issue_cite.plain(issue)} could not be relaunched: ${reason}`,
+	)
+}
+
+async function relaunched(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
 	const invocation = lane_child_invocation.ship_stop_invocation(lane.issue, stop)
 	const phase = agent_role_profile.IMPLEMENTATION_PHASE
 	const result = lane_relaunch.relaunch(lane, invocation, phase, note)
 
 	if (result.kind === 'launched') return 'relaunched'
 
-	note(`the lane child could not be relaunched: ${result.note}`)
+	await record_failed_relaunch(lane.issue, result.note)
 
 	return 'recorded'
 }
@@ -68,56 +118,164 @@ function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
 // **A served lane's child is relaunched by its broker, not from here**: this supervisor descends from the
 // child's Bash tool, which Claude Code starts without the token, so a child started here could not sign
 // in where the token is the only credential (joshuafolkken/kit#3817).
-async function brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
+async function ask_broker(lane: LaneInfo, stop: ShipStop): Promise<BrokerResult> {
 	const answer = await lane_session_broker.request(lane.directory, lane.issue, {
 		kind: 'relaunch',
 		stop,
 	})
 
-	if (answer.is_success) return 'relaunched'
+	if (answer.is_success) return { reply: 'started', reason: '' }
 
-	note(
-		`the lane child could not be relaunched: the lane broker did not start it — ${answer.reason}`,
-	)
+	note(`the lane broker did not start the lane child — ${answer.reason}`)
+
+	const reply = lane_session_broker.is_unreadable(answer) ? 'unreadable' : 'failed'
+
+	return { reply, reason: answer.reason }
+}
+
+// The session of a broker serving the lane within `polls` seconds, other than `previous` — one that stopped
+// serving is reopened by the supervisor's next lane scan (`claude-lane-broker.ts`).
+async function await_server(
+	lane: LaneInfo,
+	previous?: string,
+	polls = SERVING_POLLS,
+): Promise<string | undefined> {
+	for (let polled = 0; polled < polls; polled += 1) {
+		const session = lane_session_broker.serving_session(lane.directory, lane.issue)
+		if (session !== undefined && session !== previous) return session
+
+		// eslint-disable-next-line no-await-in-loop -- polling: each check waits on the scan the previous one missed
+		await sleep(SERVING_POLL_MS)
+	}
+
+	return undefined
+}
+
+function polls_after(reply: BrokerReply): number {
+	return reply === 'unreadable' ? RELOAD_POLLS : SERVING_POLLS
+}
+
+function redispatch_reason(last: BrokerResult): string {
+	const cause = last.reply === 'unreadable' ? `${VERSION_MISMATCH_NOTE}: ` : ''
+
+	return `${cause}the driver re-dispatches the issue — ${last.reason}`
+}
+
+// **A relaunch the broker failed is asked once more, of a new broker only, then handed to the driver**: a
+// stop left recorded waited hours for the stall detector (joshuafolkken/kit#4344). The broker that failed
+// may still be starting the first relaunch, so asking it again could start a second child beside it.
+// Once this supervisor exits, the driver's next poll reads the stop as unanswered and re-dispatches the
+// issue (`run-merge-ship.ts`). A broker that could not read the request runs older code than this ship
+// (joshuafolkken/kit#4733): its successor on the current code is waited for over a whole supervisor pass, and a
+// re-dispatch past that wait names the version mismatch.
+async function brokered(lane: LaneInfo, stop: ShipStop, server: string): Promise<ReturnOutcome> {
+	const first = await ask_broker(lane, stop)
+	if (first.reply === 'started') return 'relaunched'
+
+	const next = await await_server(lane, server, polls_after(first.reply))
+	// The reply the issue is handed to the driver on: the new broker's where one served the lane.
+	const last = next === undefined ? first : await ask_broker(lane, stop)
+	if (last.reply === 'started') return 'relaunched'
+
+	await record_failed_relaunch(lane.issue, redispatch_reason(last))
+
+	return 'redispatch'
+}
+
+// **The session that launched the ship takes the stop where it still waits on it** (`run-ship-waiter.ts`),
+// so no fresh session re-reads the run; one that ended is relaunched as below (joshuafolkken/kit#4711).
+async function is_returned(issue: string, stop: ShipStop): Promise<boolean> {
+	const repository = await run_ship_probe.repository_directory()
+	if (repository === undefined) return false
+
+	const stop_note = lane_child_invocation.ship_stop_note(issue, stop)
+
+	return await run_ship_waiter.offer(repository, issue, stop_note)
+}
+
+async function relaunched_or_brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
+	// A followup stop waits for a lane place, keeping the ship-stop prompt and the relaunch cap a driver
+	// re-dispatch would lose (`run-ship-place.ts`).
+	await run_ship_place.await_place(lane, stop.stage)
+	// **A broker that stopped serving before the stop is waited for**: one that died during the review left
+	// the lane unserved at the stop, and a child started here cannot sign in on a token (joshuafolkken/kit#4344).
+	const server = await await_server(lane)
+
+	return server === undefined ? await relaunched(lane, stop) : await brokered(lane, stop, server)
+}
+
+// A child that stopped more often than the cap allows is parked instead of relaunched
+// (`run-ship-relaunch-cap.ts`); a park the label refused leaves the stop recorded, as before.
+async function parked(issue: string, reason: string): Promise<ReturnOutcome> {
+	if (await run_ship_relaunch_cap.park(issue, reason)) return 'parked'
+
+	note('the lane child was not relaunched past the ship-stop cap, and the park label was refused')
 
 	return 'recorded'
 }
 
-// `output` is the failed stage's own output: the relaunched child's prompt carries its tail.
-async function return_control(
+// `output` is the failed stage's own output: the relaunched child's prompt carries the body's tail, and
+// the stop is classified on its standard output (`run-ship-stop-cause.ts`).
+async function stopped(
 	issue: string,
 	stage: Stage,
 	resume: ShipResume,
-	output: string,
+	output: StageOutput,
 ): Promise<ReturnOutcome> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.SHIP_STOP,
-		stop_text(issue, stage, resume),
+		stop_text(issue, stage, resume, output),
 	)
 
 	const lane = await lane_to_relaunch(issue)
 
 	if (lane === undefined) return 'recorded'
 
-	const stop = { stage, ...resume, context: await run_ship_stop_context.build(issue, output) }
+	const reason = run_ship_stage.stop_reason(stage, resume.conflicts)
+
+	if (await run_ship_relaunch_cap.is_over(issue, reason)) return await parked(issue, reason)
+
+	const findings = run_ship_stop_cause.details_of(stage, { ...resume, ...output })
+	const context = await run_ship_stop_context.build(issue, output.body, findings)
+	const stop = { stage, ...resume, context }
+
+	return (await is_returned(issue, stop)) ? 'returned' : await relaunched_or_brokered(lane, stop)
+}
+
+async function return_control(
+	issue: string,
+	stage: Stage,
+	resume: ShipResume,
+	output: string,
+): Promise<ReturnOutcome> {
+	return await stopped(issue, stage, resume, { body: output })
+}
+
+type FailedSection = Pick<ShipSection, 'body' | 'out' | 'conflicts' | 'cause'>
+
+// The section's conflicts and the cause its review round tagged, only where it has them.
+function stopped_resume(resume: ShipResume, failed: FailedSection | undefined): ShipResume {
+	const { conflicts, cause } = failed ?? {}
 
-	return lane_session_broker.is_serving(lane.directory, issue)
-		? await brokered(lane, stop)
-		: relaunched(lane, stop)
+	return {
+		...resume,
+		...(conflicts !== undefined && { conflicts }),
+		...(cause !== undefined && { cause }),
+	}
 }
 
-// The stopped ship's arguments and its failed section, as `return_control` takes them: the section's
-// conflicts ride on the resume, its body is the output the prompt carries.
+// The stopped ship's arguments and its failed section, as `stopped` takes them: the section's conflicts
+// and tagged cause ride on the resume, its body and standard output are the stage's output. A stale
+// review rides on it too, so the relaunched child re-detaches with `--review` (joshuafolkken/kit#4221).
 async function hand_back(
 	args: ShipArguments,
 	stage: Stage,
-	failed: Pick<ShipSection, 'body' | 'conflicts'> | undefined,
+	failed: FailedSection | undefined,
 ): Promise<ReturnOutcome> {
-	const resume = run_ship_next.resume_of(args)
-	const conflicts = failed?.conflicts
-	const stopped = conflicts === undefined ? resume : { ...resume, conflicts }
+	const is_review_stale = await run_ship_probe.read_review_stale()
+	const resume = { ...run_ship_next.resume_of(args), is_review_stale }
 
-	return await return_control(args.number, stage, stopped, failed?.body ?? '')
+	return await stopped(args.number, stage, stopped_resume(resume, failed), failed ?? { body: '' })
 }
 
 const run_ship_return = { hand_back, return_control }

package/scripts/run/ship/run-ship-review-reason.ts

@@ -0,0 +1,24 @@
+import { review_round_reuse, type ReuseAnswer } from '#scripts/review/review-round-reuse'
+
+// Why the ship's review stage ran or was skipped, written on its event line so `josh lane:breakdown`
+// shows it beside the stage's minutes (joshuafolkken/kit#5296). The stage runs only under `--review`;
+// within it, a recorded round 1 attested on this branch whose tree held, or moved only where round 2
+// reads, is reused (`review-round-reuse.ts`) — anything else is reviewed again, for the cause the reuse
+// answer names.
+
+const HELD_REASON = 'reused: round 1 attested on this branch, its tree held'
+const DELTA_REASON = "reused: round 1 attested on this branch, what moved since is round 2's delta"
+const RAN_PREFIX = 'ran: --review with no reusable round 1 — '
+const UNNAMED_CAUSE = 'the recorded round does not cover this tree'
+
+function reused(answer: ReuseAnswer): string {
+	return answer.reuse === review_round_reuse.REUSE.HELD ? HELD_REASON : DELTA_REASON
+}
+
+function ran(answer: ReuseAnswer): string {
+	return `${RAN_PREFIX}${answer.cause ?? UNNAMED_CAUSE}`
+}
+
+const run_ship_review_reason = { ran, reused }
+
+export { run_ship_review_reason }