@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/run/ship/run-ship-body-draft.ts

@@ -0,0 +1,110 @@
+import { access, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { git_command } from '#scripts/git/git-command'
+import { acceptance_map } from '#scripts/review/acceptance-map'
+import { live_evidence } from '#scripts/review/live-evidence'
+import { removed_tests } from '#scripts/review/removed-tests'
+import type { ShipArguments } from './run-ship-steps'
+
+// **The pull-request body a run fills in before `josh ship`, written where ship reads it.** The
+// acceptance-map and live-evidence refusals stopped about one ship per merge: their rows were printed
+// at `run:prep`, long before the ship, and the lane child's ship carried no `--body-file` at all
+// (joshuafolkken/kit#4168). The rows now land in a file in the work tree's own git directory — outside
+// the tree, so no check sees it as a change — and `josh ship` reads it when `--body-file` is omitted,
+// handing it to the preflight, `git -y` and a detached supervisor alike (`with_draft`).
+// Nothing is satisfied for the run: each row still carries its pending ending and the evidence section is empty, so
+// the same refusals stand until the run writes them.
+
+// The PR body carrying the live-execution evidence `followup` gates the merge
+// on, forwarded to `git -y` as a path because it holds commands and their output.
+const BODY_FILE_OPTION = 'body-file' as const
+const DRAFT_PREFIX = 'josh-ship-body-'
+const DRAFT_SUFFIX = '.md'
+const EXISTS_CODE = 'EEXIST'
+const NO_GIT_DIRECTORY = 'no git directory to hold the ship body draft'
+
+async function path_of(issue_number: string): Promise<string> {
+	const [git_directory] = await git_command.git_directories()
+
+	if (git_directory === undefined) throw new Error(NO_GIT_DIRECTORY)
+
+	return path.join(git_directory, `${DRAFT_PREFIX}${issue_number}${DRAFT_SUFFIX}`)
+}
+
+function is_exists_error(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === EXISTS_CODE
+}
+
+// The formats the preflight refuses on, as comments a rendered body hides: lanes that wrote the rows and
+// the evidence in shapes of their own met them only at the refusal (joshuafolkken/kit#4478). They sit
+// above the evidence heading, so their backticks are never read as that section's command.
+const FORMAT_HINTS: ReadonlyArray<string> = [
+	acceptance_map.ROW_FORMAT,
+	live_evidence.EVIDENCE_FORMAT,
+	`when the change removes or renames a test, ${removed_tests.ROW_FORMAT}`,
+]
+
+function hint_line(format: string): string {
+	return `<!-- ${format} -->`
+}
+
+function draft_text(acceptance_rows: string): string {
+	const hints = FORMAT_HINTS.map((format) => hint_line(format)).join('\n')
+
+	return `${acceptance_rows}\n\n${hints}\n\n${live_evidence.EVIDENCE_HEADING}\n`
+}
+
+// Written once: a draft the run has already filled in is never replaced by pending rows.
+async function prepare(issue_number: string, acceptance_rows: string): Promise<string> {
+	const target = await path_of(issue_number)
+
+	try {
+		await writeFile(target, draft_text(acceptance_rows), { flag: 'wx' })
+	} catch (error) {
+		if (!is_exists_error(error)) throw error
+	}
+
+	return target
+}
+
+async function existing(issue_number: string): Promise<string | undefined> {
+	const target = await path_of(issue_number)
+
+	try {
+		await access(target)
+
+		return target
+	} catch {
+		return undefined
+	}
+}
+
+// Removed once the pull request merged: keyed by issue number alone, a draft left in a git directory
+// no lane close prunes (the main checkout's `.git`) would hand a reopened issue's ship the old body.
+async function remove(issue_number: string): Promise<void> {
+	await rm(await path_of(issue_number), { force: true })
+}
+
+function body_arguments(body_path: string | undefined): ReadonlyArray<string> {
+	return body_path === undefined ? [] : [`--${BODY_FILE_OPTION}`, body_path]
+}
+
+// The ship's `--body-file`, or the draft when it was omitted and one exists.
+async function with_draft(args: ShipArguments): Promise<ShipArguments> {
+	if (args.body_path !== undefined) return args
+	const draft = await existing(args.number)
+
+	return draft === undefined ? args : { ...args, body: body_arguments(draft), body_path: draft }
+}
+
+const run_ship_body_draft = {
+	BODY_FILE_OPTION,
+	body_arguments,
+	existing,
+	path_of,
+	prepare,
+	remove,
+	with_draft,
+}
+
+export { run_ship_body_draft }

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

@@ -1,19 +1,21 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_ledger } from '#scripts/lane/lane-ledger'
-import { cli_flags } from '#scripts/lib/cli-flags'
+import { review_stop_log } from '#scripts/review/review-stop-log'
 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_ship, type ShipSection } from './run-ship'
+import { run_ship_args } from './run-ship-args'
+import { run_ship_body_draft } from './run-ship-body-draft'
 import { run_ship_detach } from './run-ship-detach'
-import { run_ship_next } from './run-ship-next'
-import { run_ship_pre_detach } from './run-ship-pre-detach'
+import { run_ship_infra_retry } from './run-ship-infra-retry'
+import { run_ship_pre_detach_timed } from './run-ship-pre-detach-timed'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
 import { run_ship_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
 import { run_ship_steps, type ShipArguments, type Step } from './run-ship-steps'
+import { run_ship_stop_cause } from './run-ship-stop-cause'
 
 // `josh ship "<title> #<N>"` — one call for the fixed commit-to-report region a run ships a change on.
 // It runs `gate`, `git -y`, `followup` and `run:tail` internally, so no round trip re-bills a lane's
@@ -39,51 +41,17 @@ import { run_ship_steps, type ShipArguments, type Step } from './run-ship-steps'
 // the agent ends at the hand-off instead of relaunching itself for the gate, a supervised ship that stops
 // hands the stage back (`run-ship-return.ts`), and `--log <N>` prints the report it stopped on.
 //
-// The first positional is the `"<title> #<N>"` string `git -y` and `followup` already take; the issue
-// number is read off its tail for `run:tail`. Any further positionals are follow-up citations filed
-// this run (`fullrun-steps.md` routes branch-2 filing before `ship`), forwarded to `run:tail` after the
-// closed issue so `issue:cite` reports them too. A notify body — `--notify-message` or the
-// shell-body-safe `--notify-message-file` — is forwarded to `followup` alone; the completion prose is
-// composed before this command and passed straight through.
+// The command line it takes is read in `run-ship-args.ts`.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const FIRST = 0
-const NUMBER_GROUP = 1
-const EXTRA_CITE_START = 1
-// The issue reference at the tail of the title — `git -y` and `followup` read the whole string, and
-// `run:tail` needs the number alone.
-const TRAILING_ISSUE_PATTERN = /#([1-9]\d*)\s*$/u
-// Both body forms `followup` documents, forwarded verbatim: the inline `--notify-message` and the
-// shell-body-safe `--notify-message-file` a body naming a command or path must use (`followup.md`).
-const NOTIFY_OPTIONS = ['notify-message', 'notify-message-file'] as const
-// The PR body carrying the live-execution evidence `followup` gates the merge
-// on, forwarded to `git -y` as a path because it holds commands and their output.
-const BODY_FILE_OPTION = 'body-file'
 const USAGE =
 	'Usage: josh ship "<title> #<N>" [<follow-up-N> ...] [--cite <N> ...] [--review] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | josh ship --log <N>'
 const NO_LOG_NOTE = 'no detached ship supervisor log for this issue'
 const LANE_CHILD_DETACH_NOTE =
 	'lane child: shipping through the detached supervisor (--detach implied), so the end of this turn cannot kill it'
 
-type NotifyValues = Partial<Record<(typeof NOTIFY_OPTIONS)[number], string>>
-
-const OPTIONS = {
-	[NOTIFY_OPTIONS[0]]: { type: 'string' },
-	[NOTIFY_OPTIONS[1]]: { type: 'string' },
-	[BODY_FILE_OPTION]: { type: 'string' },
-	review: { type: 'boolean' },
-	// Hand the region to a detached supervisor (`run-ship-detach.ts`), print the
-	// report a stopped supervisor left, and carry follow-up citations as options so the supervisor's
-	// command line still ends with its title.
-	detach: { type: 'boolean' },
-	log: { type: 'string' },
-	cite: { type: 'string', multiple: true },
-} as const
-
-type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number: string }
-
 // What a resumed ship knows before its first stage: the record's path (absent outside a repository),
 // the stages it says completed, and the repository's actual state (`run-ship-stage.ts` decides from it).
 // `started` opens with the stages the record says this attempt started — a supervisor that ended
@@ -95,87 +63,7 @@ interface ShipContext {
 	started: Array<string>
 }
 
-// The notify tail `followup` takes — whichever body form the caller composed, forwarded unchanged so a
-// path-based body reaches `followup` exactly as passed.
-function notify_arguments(values: NotifyValues): ReadonlyArray<string> {
-	return NOTIFY_OPTIONS.flatMap((option) => {
-		const value = values[option]
-
-		return value === undefined ? [] : [`--${option}`, value]
-	})
-}
-
-function body_arguments(path: string | undefined): ReadonlyArray<string> {
-	return path === undefined ? [] : [`--${BODY_FILE_OPTION}`, path]
-}
-
-const { PHASE } = run_ship_stage
-
-function issue_number(title: string): string | undefined {
-	return TRAILING_ISSUE_PATTERN.exec(title)?.[NUMBER_GROUP]
-}
-
-interface ParsedValues extends NotifyValues {
-	[BODY_FILE_OPTION]?: string
-	review?: boolean
-	detach?: boolean
-	log?: string
-	cite?: Array<string>
-}
-
-// A follow-up citation passed as a trailing positional is a bare issue number, so a stray flag is
-// refused rather than forwarded to the wrong step.
-function ship_args(
-	title: string,
-	rest: ReadonlyArray<string>,
-	values: ParsedValues,
-): ShipArguments | undefined {
-	const number = issue_number(title)
-	const cites = [...rest, ...(values.cite ?? [])]
-
-	if (number === undefined || cites.some((token) => !issue_number_shape.is_issue_number(token))) {
-		return undefined
-	}
-
-	return {
-		title,
-		number,
-		notify: notify_arguments(values),
-		body: body_arguments(values[BODY_FILE_OPTION]),
-		body_path: values[BODY_FILE_OPTION],
-		cites,
-		is_review: values.review === true,
-		is_detach: values.detach === true,
-	}
-}
-
-// `--log <N>` stands alone: a bare issue number and nothing to ship.
-function log_command(number: string, positionals: ReadonlyArray<string>): ShipCommand | undefined {
-	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(number) && positionals.length === 0
-		? { kind: 'log', number }
-		: undefined
-}
-
-function command_of(
-	values: ParsedValues,
-	positionals: ReadonlyArray<string>,
-): ShipCommand | undefined {
-	if (values.log !== undefined) return log_command(values.log, positionals)
-
-	const title = positionals[FIRST]
-	const args =
-		title === undefined ? undefined : ship_args(title, positionals.slice(EXTRA_CITE_START), values)
-
-	return args === undefined ? undefined : { kind: 'ship', args }
-}
-
-// Numbers-only tail and a strict parse, so a title with no `#<N>` or a stray flag is refused rather
-// than shipped past the wrong step.
-function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
-	const parsed = cli_flags.arguments_of(argv, OPTIONS)
-
-	return parsed === undefined ? undefined : command_of(parsed.values, parsed.positionals)
-}
+const { PHASE, STAGE } = run_ship_stage
 
 // Every stage that ran is timed into the lane ledger, failed ones included — a stage that stopped the
 // ship cost the lane its time as well. The append is local and best-effort, so it adds no wait.
@@ -187,15 +75,26 @@ async function record_timed(step: Step, issue: string, elapsed_ms: number): Prom
 	await lane_ledger.record_stage({ stage: step.stage, elapsed_ms, issue: Number(issue) })
 }
 
-async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
+async function run_once(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
 	const started_ms = performance.now()
 	const result = await step.run(args, state)
 	const elapsed_ms = performance.now() - started_ms
 
 	if (result.is_skipped !== true) await record_timed(step, args.number, elapsed_ms)
-	const section = { header: step.header, body: result.out, code: result.code }
 
-	return result.conflicts === undefined ? section : { ...section, conflicts: result.conflicts }
+	return run_ship.section_of(step.header, result)
+}
+
+// A stage that stopped on the infrastructure runs again in place before it stops the ship. A retry
+// re-reads the state, as a resumed ship does: a commit whose push failed is not made a second time.
+async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
+	const first = [state]
+
+	return await run_ship_infra_retry.retried(step.stage, async () => {
+		const current = first.pop() ?? (await run_ship_probe.read_state())
+
+		return await run_once(step, args, current)
+	})
 }
 
 async function emit_phase(
@@ -238,6 +137,12 @@ async function settle(
 	})
 }
 
+// A function of its own so the write does not sit after an `await`, where `require-atomic-updates`
+// reads it as a possible race — the reason `held-mark.ts` gives `set_held_mark`.
+function set_state(context: ShipContext, state: ShipState): void {
+	context.state = state
+}
+
 // One stage: passed over when the record and the state say it is done, run and recorded otherwise.
 async function run_stage(
 	step: Step,
@@ -258,6 +163,8 @@ async function run_stage(
 	const section = await run_step(step, args, context.state)
 
 	await settle(step, args, context, section.code)
+	// A review may fix the tree and refreshes the brief, so the stages after it read the state anew.
+	if (step.stage === STAGE.REVIEW) set_state(context, await run_ship_probe.read_state())
 
 	return section
 }
@@ -271,19 +178,22 @@ async function open_context(args: ShipArguments): Promise<ShipContext> {
 	const done = target === undefined ? new Set<string>() : run_ship_stage.read_done(target)
 	const started = target === undefined ? [] : [...run_ship_stage.read_started(target)]
 
+	// A supervisor that died mid-followup left its wait marked; this one waits on nothing yet.
+	record(target, (path) => {
+		run_ship_stage.clear_waits(path)
+	})
+
 	return { target, done, state, started }
 }
 
 // Every stop goes to the lane ledger — supervised, in an agent's own turn, or a lane child's preflight
-// before the hand-off — so `lane:stats` can say how long a ship stayed stopped for each reason.
-async function record_stop(
-	args: ShipArguments,
-	stage: Stage,
-	conflicts?: ReadonlyArray<string>,
-): Promise<void> {
-	const reason = run_ship_stage.stop_reason(stage, conflicts)
+// before the hand-off — so `lane:stats` can say how long a ship stayed stopped for each reason. A review
+// stop's deciding findings also go, whole, to the durable stop log `review:stops` reads.
+async function record_stop(args: ShipArguments, stage: Stage, failed?: ShipSection): Promise<void> {
+	const issue = Number(args.number)
 
-	await lane_ledger.record_stop({ issue: Number(args.number), reason })
+	await lane_ledger.record_stop(run_ship_stop_cause.record_of(issue, stage, failed))
+	review_stop_log.record({ issue, stage, findings: run_ship_stop_cause.details_of(stage, failed) })
 }
 
 // A detached supervisor hands the stopped stage back (`run-ship-return.ts`); a
@@ -295,19 +205,13 @@ async function stopped(
 	step: Step,
 	context: ShipContext,
 ): Promise<ReadonlyArray<ShipSection>> {
-	const conflicts = sections.at(-1)?.conflicts
+	const failed = sections.at(-1)
 
-	await record_stop(args, step.stage, conflicts)
+	await record_stop(args, step.stage, failed)
 
 	if (run_ship_detach.is_supervised()) {
-		const resume = run_ship_next.resume_of(args)
-
 		record(context.target, run_ship_stage.end_attempt)
-		await run_ship_return.return_control(
-			args.number,
-			step.stage,
-			conflicts === undefined ? resume : { ...resume, conflicts },
-		)
+		await run_ship_return.hand_back(args, step.stage, failed)
 	}
 
 	return sections
@@ -379,23 +283,35 @@ function should_detach(args: ShipArguments): boolean {
 	return !run_ship_detach.is_supervised() && lane_child_marker.is_child_of(process.cwd())
 }
 
+// The preflight stop's unmet kinds, with `pre-detach` added when those checks went red beside it.
+function with_checks(stop: ShipSection, checks: ShipSection): ShipSection {
+	if (checks.code === SUCCESS_EXIT_CODE) return stop
+
+	return { ...stop, preconditions: [...(stop.preconditions ?? []), lane_ledger.PRE_DETACH_STAGE] }
+}
+
 // The preflight is deterministic and fast, so it runs here, in the agent's own turn, before the
 // hand-off — a stop it finds is fixed by the same session instead of relaunching one from the
-// supervisor. Only the slow stages go to the supervisor, which re-asks the preflight itself. The type
-// check and the document tests follow it here for the same reason; they are not a stage, so the
-// supervisor's gate runs them again rather than passing over them.
+// supervisor. Only the slow stages go to the supervisor, which re-asks the preflight itself. The fast
+// checks (`run-ship-pre-detach.ts`) follow it here for the same reason; they are not a stage, so the
+// supervisor's gate runs them again rather than passing over them. They run even when the preflight
+// refused, so one ship reports every failure there is to fix (joshuafolkken/kit#4305); the preflight's
+// refusal still comes before its own scoped pair, the one heavy check here.
+//
+// **The refusal is printed last**: a lane child reading the report through `tail` saw only the red
+// metrics or type check after it, fixed those, and shipped into the same refusal again — every repeated
+// preflight stop of joshuafolkken/kit#4478. The stop records the pre-detach checks' red beside the
+// unmet kinds, so the ledger shows which refusals came with one.
 async function pre_detach_sections(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const preflight = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
+	const result = await run_ship_pre_detach_timed.checks(args.number)
+	const checks = { header: run_ship.PRE_DETACH_HEADER, body: result.out, code: result.code }
 
 	if (preflight.code !== SUCCESS_EXIT_CODE) {
-		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage)
-
-		return [preflight]
+		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage, with_checks(preflight, checks))
 	}
 
-	const result = await run_ship_pre_detach.checks()
-
-	return [preflight, { header: run_ship.PRE_DETACH_HEADER, body: result.out, code: result.code }]
+	return [checks, preflight]
 }
 
 async function detach_after_preflight(args: ShipArguments): Promise<number> {
@@ -444,7 +360,7 @@ async function run_ship_command(args: ShipArguments): Promise<number> {
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const command = parse(argv)
+	const command = run_ship_args.parse(argv)
 
 	if (command === undefined) {
 		console.error(USAGE)
@@ -454,7 +370,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	return command.kind === 'log'
 		? await print_log(command.number)
-		: await run_ship_command(command.args)
+		: await run_ship_command(await run_ship_body_draft.with_draft(command.args))
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

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

@@ -58,6 +58,7 @@ const RECORD_WAIT_ATTEMPTS = 200
 // a `pnpm josh ship` start-up, far below the lifetime a reused pid could otherwise be believed for.
 const CLAIM_WINDOW_MS = 120_000
 type ShipResult = 'running' | 'success' | 'failed' | 'abnormal'
+type StartRead = (pid: number) => string | undefined
 
 interface ShipRecord {
 	pid?: number | undefined
@@ -146,35 +147,43 @@ function is_within_claim_window(record: ShipRecord): boolean {
 	return record.launched_at !== undefined && Date.now() - record.launched_at < CLAIM_WINDOW_MS
 }
 
-function has_live_identity(pid: number, record: ShipRecord): boolean {
+function has_live_identity(pid: number, record: ShipRecord, read: StartRead): boolean {
 	if (record.process_start === undefined) {
 		return is_within_claim_window(record) && process_identity.is_live_pid(pid)
 	}
 
-	return process_identity.is_same_process(pid, record.process_start) !== false
+	return process_identity.is_same_process(pid, record.process_start, read) !== false
 }
 
-function result_of(record: ShipRecord): ShipResult {
+function result_of(record: ShipRecord, read: StartRead): ShipResult {
 	if (record.pid === undefined) {
-		const is_launcher = process_identity.is_same_process(record.launcher_pid, record.launcher_start)
+		const { launcher_pid, launcher_start } = record
+		const is_launcher = process_identity.is_same_process(launcher_pid, launcher_start, read)
 
 		return is_launcher === false ? 'abnormal' : 'running'
 	}
 
-	if (has_live_identity(record.pid, record)) return 'running'
+	if (has_live_identity(record.pid, record, read)) return 'running'
 
 	return record.result ?? 'abnormal'
 }
 
+// `read` answers each recorded process's start time: a reader holding one process snapshot passes its
+// own, so the reading starts no `ps` (joshuafolkken/kit#4245).
 function read_result(
 	repository: string,
 	number: string,
-): { launch_id: string; result: ShipResult } | undefined {
+	read: StartRead = process_identity.read_start,
+): { launch_id: string; launched_at?: number | undefined; result: ShipResult } | undefined {
 	const record = read_record(repository, number)
 
 	return record === undefined
 		? undefined
-		: { launch_id: record.launch_id, result: result_of(record) }
+		: {
+				launch_id: record.launch_id,
+				launched_at: record.launched_at,
+				result: result_of(record, read),
+			}
 }
 
 function current_record(repository: string, number: string): ShipRecord | undefined {
@@ -183,6 +192,16 @@ function current_record(repository: string, number: string): ShipRecord | undefi
 	return record?.launch_id === process.env[LAUNCH_ID_KEY] ? record : undefined
 }
 
+// When the ship for `number` that is still running was launched — `undefined` where none is running or
+// its record carries no launch time. `run-ship-overlap.ts` orders two running ships by it.
+function running_since(repository: string, number: string): number | undefined {
+	const record = read_record(repository, number)
+
+	return record !== undefined && result_of(record, process_identity.read_start) === 'running'
+		? record.launched_at
+		: undefined
+}
+
 function is_pending(record: ShipRecord | undefined): boolean {
 	return record !== undefined && record.pid === undefined
 }
@@ -362,6 +381,7 @@ const run_ship_detach = {
 	last_launch,
 	log_path,
 	read_log,
+	running_since,
 	supervisor_argv,
 }
 

package/scripts/run/ship/run-ship-infra-retry.ts

@@ -0,0 +1,59 @@
+import { setTimeout as delay } from 'node:timers/promises'
+import type { ShipSection } from './run-ship'
+import type { Stage } from './run-ship-stage'
+import { run_ship_stop_cause } from './run-ship-stop-cause'
+
+// A stage that stopped on the infrastructure is run again in place, a bounded number of times, before
+// the ship stops (joshuafolkken/kit#3998). Re-running a stage is what a resumed ship does already, so
+// a retry repeats nothing a relaunched lane would not; it only skips the stop, the relaunch and the
+// wait in between. Any other stop — a finding, a red check, a conflict — returns at once, and so does a
+// review round's, a reviewer that did not finish included: a review is never re-run in place.
+
+const MAX_INFRA_RETRIES = 2
+const RETRY_DELAY_MS = 60_000
+const RETRY_CAP = String(MAX_INFRA_RETRIES)
+
+type Attempt = () => Promise<ShipSection>
+
+interface RetryHooks {
+	wait: (milliseconds: number) => Promise<void>
+	note: (text: string) => void
+}
+
+const DEFAULT_HOOKS: RetryHooks = {
+	wait: async (milliseconds) => {
+		await delay(milliseconds)
+	},
+	note: (text) => {
+		process.stderr.write(`${text}\n`)
+	},
+}
+
+function is_retryable(stage: Stage, section: ShipSection): boolean {
+	if (section.code === 0 || run_ship_stop_cause.is_review(stage)) return false
+
+	return run_ship_stop_cause.cause_of(stage, section) === run_ship_stop_cause.CAUSE.INFRA
+}
+
+async function retried(
+	stage: Stage,
+	attempt: Attempt,
+	hooks: RetryHooks = DEFAULT_HOOKS,
+	retries_left = MAX_INFRA_RETRIES,
+): Promise<ShipSection> {
+	const section = await attempt()
+
+	if (retries_left === 0 || !is_retryable(stage, section)) return section
+
+	const ordinal = String(MAX_INFRA_RETRIES - retries_left + 1)
+
+	hooks.note(`josh ship: ${stage} stopped on the infrastructure — retry ${ordinal}/${RETRY_CAP}`)
+	await hooks.wait(RETRY_DELAY_MS)
+
+	return await retried(stage, attempt, hooks, retries_left - 1)
+}
+
+const run_ship_infra_retry = { MAX_INFRA_RETRIES, RETRY_DELAY_MS, retried }
+
+export type { RetryHooks }
+export { run_ship_infra_retry }

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

@@ -1,5 +1,6 @@
 import { run_ship_stage, type Stage } from './run-ship-stage'
 import type { ShipArguments } from './run-ship-steps'
+import type { Cause } from './run-ship-stop-cause'
 
 // The command a relaunched lane child runs once it has fixed what stopped its detached ship.
 // The stopped stage decides the command mechanically, so it is decided here, once, and the prompt
@@ -43,6 +44,10 @@ interface ShipResume {
 	is_review: boolean
 	// The paths a merge of the default branch left unmerged.
 	conflicts?: ReadonlyArray<string>
+	// The cause a stopped review round tagged its stop with (`run-ship-stop-cause.ts`).
+	cause?: Cause
+	// The issue changed after the recorded review's brief (`run-ship-probe.ts`).
+	is_review_stale?: boolean
 }
 
 // Single quotes, so a `$` or a backtick in a title is never expanded by the shell that runs it.
@@ -98,19 +103,38 @@ const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
 	[STAGE.REPORT]: detach_again,
 }
 
+// Whatever stage stopped, a review that read the issue before its update is round 1's to redo: the
+// supervisor reviews it again even on a committed tree (`run-ship-stage.ts`), and `josh followup`
+// refuses the merge until it has (joshuafolkken/kit#4221).
+function detach_review_again(resume: ShipResume): string {
+	return `leave the fix uncommitted and run \`${ship_command(COMMAND.DETACH_REVIEW, resume)}\` — the review read the issue before its update, so the supervisor reviews round 1 again.`
+}
+
+function after_fix(stage: Stage, resume: ShipResume): string {
+	return resume.is_review_stale === true ? detach_review_again(resume) : AFTER_FIX[stage](resume)
+}
+
 // A conflict names its paths, so the resumed session resolves them without
 // reading the report or asking git which files are unmerged.
 function conflict_step(conflicts: ReadonlyArray<string>): string {
 	return `Resolve the conflict with origin/main in ${conflicts.join(', ')} (the merge is left in progress: remove the conflict markers in those files), then`
 }
 
+// A prompt that already carries the failed output points at it; only one without has the
+// session read the stopped report first.
+function fix_step(issue: string, stage: Stage, is_excerpted: boolean): string {
+	if (is_excerpted) return `Fix the ${stage} failure shown in the output below`
+
+	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure`
+}
+
 // Two lines' worth: read the stopped report, then the one command that resumes after the fix.
-function next_step(issue: string, stage: Stage, resume: ShipResume): string {
+function next_step(issue: string, stage: Stage, resume: ShipResume, is_excerpted = false): string {
 	const conflicts = resume.conflicts ?? []
 
-	if (conflicts.length > 0) return `${conflict_step(conflicts)} ${AFTER_FIX[stage](resume)}`
+	if (conflicts.length > 0) return `${conflict_step(conflicts)} ${after_fix(stage, resume)}`
 
-	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure, then ${AFTER_FIX[stage](resume)}`
+	return `${fix_step(issue, stage, is_excerpted)}, then ${after_fix(stage, resume)}`
 }
 
 const run_ship_next = { COMMAND, next_step, quoted, resume_of }