@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,18 +1,27 @@
 #!/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 { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+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_conflict_probe } from './run-ship-conflict-probe'
 import { run_ship_detach } from './run-ship-detach'
-import { run_ship_pre_detach } from './run-ship-pre-detach'
+import { run_ship_handover, type CodeCheck } from './run-ship-handover'
+import { run_ship_infra_retry } from './run-ship-infra-retry'
+import { run_ship_lap } from './run-ship-lap'
+import type { PreDetachResult } from './run-ship-pre-detach'
+import { run_ship_pre_detach_pinned } from './run-ship-pre-detach-pinned'
+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'
+import type { StepResult } from './run-ship-sync'
 
 // `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
@@ -38,51 +47,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>'
+	'Usage: josh ship "<title> #<N>" [<follow-up-N> ...] [--cite <N> ...] [--review [--unpinned-ok "<reason>"]] [--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
@@ -92,89 +67,17 @@ interface ShipContext {
 	done: ReadonlySet<string>
 	state: ShipState
 	started: Array<string>
+	// Whether the code this process loaded has changed since it started (`run-ship-handover.ts`).
+	is_stale: CodeCheck
 }
 
-// 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 ShipOutcome {
+	sections: ReadonlyArray<ShipSection>
+	is_handed_over: boolean
 }
 
-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
+const REREAD_AFTER: ReadonlySet<Stage> = new Set([STAGE.SYNC, STAGE.REVIEW])
 
 // 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.
@@ -183,29 +86,60 @@ function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
 // recorded, or a gate that reused its tree's green record would otherwise read as a run that took a
 // second and pull the stage's median to zero.
 async function record_timed(step: Step, issue: string, elapsed_ms: number): Promise<void> {
-	await lane_ledger.record_stage({ stage: step.stage, elapsed_ms, issue: Number(issue) })
+	await lane_ledger_write.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 result = await run_ship_lap.within(
+		args.number,
+		step.stage,
+		async () => 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)
+	})
+}
+
+// One stage's line on the event stream, with why it ran or was skipped where the stage said.
+interface StageMark {
+	stage: Stage
+	phase: Phase
+	reason?: string | undefined
 }
 
 async function emit_phase(
 	args: ShipArguments,
 	context: ShipContext,
-	stage: Stage,
-	phase: Phase,
+	mark: StageMark,
 ): Promise<void> {
-	const text = run_ship_stage.event_text(args.number, stage, phase, context.started)
+	const text = run_ship_stage.event_text(args.number, mark.stage, mark.phase, context.started)
 
-	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STAGE, text)
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.SHIP_STAGE,
+		run_ship_stage.with_reason(text, mark.reason),
+	)
+}
+
+// A green stage that found nothing to do ends `skipped` rather than `done` (joshuafolkken/kit#5296).
+function settled_phase(section: ShipSection): Phase {
+	if (section.code !== SUCCESS_EXIT_CODE) return PHASE.FAILED
+
+	return section.is_skipped === true ? PHASE.SKIPPED : PHASE.DONE
 }
 
 // The record is written best-effort, as the event stream is: a record that could not be written costs
@@ -224,19 +158,25 @@ async function settle(
 	step: Step,
 	args: ShipArguments,
 	context: ShipContext,
-	code: number,
+	section: ShipSection,
 ): Promise<void> {
-	const is_green = code === SUCCESS_EXIT_CODE
+	const phase = settled_phase(section)
 
-	await emit_phase(args, context, step.stage, is_green ? PHASE.DONE : PHASE.FAILED)
+	await emit_phase(args, context, { stage: step.stage, phase, reason: section.reason })
 
-	if (!is_green) return
+	if (phase === PHASE.FAILED) return
 
 	record(context.target, (path) => {
 		run_ship_stage.mark_done(path, step.stage)
 	})
 }
 
+// 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,
@@ -244,7 +184,7 @@ async function run_stage(
 	context: ShipContext,
 ): Promise<ShipSection> {
 	if (run_ship_stage.is_done(step.stage, context.done, context.state, args.body.length > 0)) {
-		await emit_phase(args, context, step.stage, PHASE.SKIPPED)
+		await emit_phase(args, context, { stage: step.stage, phase: PHASE.SKIPPED })
 
 		return { header: step.header, body: run_ship.SKIPPED_BODY, code: SUCCESS_EXIT_CODE }
 	}
@@ -253,36 +193,43 @@ async function run_stage(
 	record(context.target, (path) => {
 		run_ship_stage.mark_started(path, step.stage)
 	})
-	await emit_phase(args, context, step.stage, PHASE.START)
+	await emit_phase(args, context, { stage: step.stage, phase: PHASE.START })
 	const section = await run_step(step, args, context.state)
 
-	await settle(step, args, context, section.code)
+	await settle(step, args, context, section)
+	// The sync commits locally and a review may fix the tree, so the stages after either read the state
+	// anew — the commit stage then pushes the sync's commit rather than making it again.
+	if (REREAD_AFTER.has(step.stage)) set_state(context, await run_ship_probe.read_state())
 
 	return section
 }
 
 async function open_context(args: ShipArguments): Promise<ShipContext> {
-	const [target, state] = await Promise.all([
+	const [target, state, is_stale] = await Promise.all([
 		run_ship_probe.record_target(args.number),
 		run_ship_probe.read_state(),
+		run_ship_handover.watch(),
 	])
 
 	const done = target === undefined ? new Set<string>() : run_ship_stage.read_done(target)
 	const started = target === undefined ? [] : [...run_ship_stage.read_started(target)]
 
-	return { target, done, state, started }
+	// 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, is_stale }
 }
 
 // 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_write.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
@@ -296,7 +243,7 @@ async function stopped(
 ): Promise<ReadonlyArray<ShipSection>> {
 	const failed = sections.at(-1)
 
-	await record_stop(args, step.stage, failed?.conflicts)
+	await record_stop(args, step.stage, failed)
 
 	if (run_ship_detach.is_supervised()) {
 		record(context.target, run_ship_stage.end_attempt)
@@ -306,28 +253,50 @@ async function stopped(
 	return sections
 }
 
+// One stage, and the outcome where the ship ends at it: a failure, or a sync after which a successor on
+// the code it merged took the rest over (`run-ship-handover.ts`).
+async function ship_stage(
+	step: Step,
+	args: ShipArguments,
+	context: ShipContext,
+	sections: Array<ShipSection>,
+): Promise<ShipOutcome | undefined> {
+	const section = await run_stage(step, args, context)
+
+	sections.push(section)
+
+	if (section.code !== SUCCESS_EXIT_CODE) {
+		return { sections: await stopped(sections, args, step, context), is_handed_over: false }
+	}
+
+	if (step.stage !== STAGE.SYNC) return undefined
+	const handover = await run_ship_handover.hand_over(args, context.is_stale)
+
+	return handover === undefined
+		? undefined
+		: { sections: [...sections, handover], is_handed_over: true }
+}
+
 // Run the stages in order, stopping at the first that failed: a red gate never reaches the commit, so
 // the returned sections end at the failure the report names. A ship that reached the end clears its
-// record, so the next ship of the same issue starts from the preflight.
-async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
+// record, so the next ship of the same issue starts from the preflight; one handed over leaves it to
+// the successor, which passes over what this one finished.
+async function ship(args: ShipArguments): Promise<ShipOutcome> {
 	const context = await open_context(args)
 	const sections: Array<ShipSection> = []
 
 	for (const step of run_ship_steps.steps(args)) {
 		// eslint-disable-next-line no-await-in-loop -- stages run in order and the first failure stops the ship
-		const section = await run_stage(step, args, context)
-
-		sections.push(section)
+		const outcome = await ship_stage(step, args, context, sections)
 
-		// eslint-disable-next-line no-await-in-loop -- stages run in order and the first failure stops the ship
-		if (section.code !== SUCCESS_EXIT_CODE) return await stopped(sections, args, step, context)
+		if (outcome !== undefined) return outcome
 	}
 
 	record(context.target, (path) => {
 		run_ship_stage.clear(path)
 	})
 
-	return sections
+	return { sections, is_handed_over: false }
 }
 
 async function print_log(number: string): Promise<number> {
@@ -372,23 +341,66 @@ 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 the red pre-detach checks' own kinds added beside them
+// (`run-ship-pre-detach.ts`).
+function with_checks(stop: ShipSection, checks: PreDetachResult): ShipSection {
+	if (checks.code === SUCCESS_EXIT_CODE) return stop
+
+	return {
+		...stop,
+		preconditions: [...(stop.preconditions ?? []), ...(checks.preconditions ?? [])],
+	}
+}
+
+// The stop is the sync stage's, so it is recorded and resumed as that stage's `conflict` is; the
+// preflight's refusal, if any, still prints last.
+async function conflict_sections(
+	args: ShipArguments,
+	conflict: StepResult,
+	preflight: ShipSection,
+): Promise<ReadonlyArray<ShipSection>> {
+	const section = run_ship.section_of(run_ship.SYNC_HEADER, conflict)
+
+	await record_stop(args, STAGE.SYNC, section)
+
+	return [section, preflight]
+}
+
 // 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 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.
+// 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 beside a `--review` ship's
+// `test:pinned`.
+//
+// **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. **Red checks behind a passed preflight
+// are a stop too** (joshuafolkken/kit#5228): recorded under the preflight with their kinds, an
+// `unpinned` place among them.
+//
+// **A conflict with origin/main stops before the checks** (joshuafolkken/kit#5018): the supervisor's
+// sync would stop on it after them, so they would only be run again once it is resolved.
 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 conflict = await run_ship_conflict_probe.probe()
 
-	if (preflight.code !== SUCCESS_EXIT_CODE) {
-		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage)
+	if (conflict !== undefined) return await conflict_sections(args, conflict, preflight)
 
-		return [preflight]
-	}
+	const result = await run_ship_pre_detach_timed.checks(
+		args.number,
+		run_ship_pre_detach_pinned.checks_for(args),
+	)
+	const checks = { header: run_ship.PRE_DETACH_HEADER, body: result.out, code: result.code }
 
-	const result = await run_ship_pre_detach.checks()
+	if (run_ship.exit_code([checks, preflight]) !== SUCCESS_EXIT_CODE) {
+		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage, with_checks(preflight, result))
+	}
 
-	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> {
@@ -420,7 +432,9 @@ async function record_supervised_result(
 	await run_ship_detach.mark_result(repository, args.number, run_ship.exit_code(sections))
 }
 
-async function run_ship_command(args: ShipArguments): Promise<number> {
+async function run_ship_command(given: ShipArguments): Promise<number> {
+	const args = await run_ship_pre_detach_pinned.with_recorded_reason(given)
+
 	if (should_detach(args)) {
 		if (!args.is_detach) console.error(LANE_CHILD_DETACH_NOTE)
 
@@ -428,16 +442,17 @@ async function run_ship_command(args: ShipArguments): Promise<number> {
 	}
 
 	await claim_supervised_identity(args)
-	const sections = await ship(args)
+	const { sections, is_handed_over } = await ship(args)
 
-	await record_supervised_result(args, sections)
+	// The successor carries the same launch record, so its result is the one written there.
+	if (!is_handed_over) await record_supervised_result(args, sections)
 	console.info(run_ship.format_report(sections))
 
 	return run_ship.exit_code(sections)
 }
 
 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)
@@ -447,7 +462,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-conflict-probe.ts

@@ -0,0 +1,59 @@
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_command } from '#scripts/git/git-command'
+import { git_merge_conflicts } from '#scripts/git/git-merge-conflicts'
+import { main_merge_guard } from '#scripts/git/main-merge-guard'
+import { main_merge_regenerate } from '#scripts/git/main-merge-regenerate'
+import type { StepResult } from './run-ship-sync'
+
+// Before `josh ship --detach` runs its pre-detach checks, whether merging origin/main would stop on a
+// conflict (joshuafolkken/kit#5018). The supervisor's sync stage is the first to merge, so a branch
+// main had moved under ran the whole pre-detach first and then stopped there, its checks thrown away.
+// The reading touches neither the working tree nor the index (`git-merge-conflicts.ts`); only the
+// remote-tracking ref of the default branch moves with the fetch. A probe that cannot answer — a fetch
+// that failed, a merge base it cannot read — leaves the question to the sync stage, as the sync itself
+// leaves a failed fetch to the followup; the ship then runs exactly as it did before the probe.
+
+const FAILURE_EXIT_CODE = 1
+const CONFLICT_NOTE = 'merging origin/main would stop on a conflict in:'
+
+// The sync's own order: `main:merge` refuses uncommitted work origin/main also changed, so the commit
+// comes first (`main-merge-guard.ts`).
+function fix_note(): string {
+	return `The pre-detach checks did not run. Commit the work with ${main_merge_guard.commit_command()}, run \`pnpm josh main:merge\`, resolve the conflict in those files, then run the ship again.`
+}
+
+async function conflicting_paths(): Promise<ReadonlyArray<string>> {
+	const default_branch = await git_command.get_default_branch()
+
+	await git_command.fetch_branch(default_branch)
+
+	const paths = await changed_paths.read_changed_paths(false)
+	const root = await git_command.repository_root()
+
+	return git_merge_conflicts.working_tree_conflicts(`origin/${default_branch}`, paths, root) ?? []
+}
+
+async function answered_paths(): Promise<ReadonlyArray<string>> {
+	try {
+		return await conflicting_paths()
+	} catch {
+		return []
+	}
+}
+
+// The stop, carrying the paths as the sync stage's conflict does, so the stop is recorded as
+// `conflict`; `undefined` when the merge would go through, the sync's merge would resolve every
+// conflict itself (`main-merge-regenerate.ts`), or the probe could not tell.
+async function probe(): Promise<StepResult | undefined> {
+	const conflicts = await answered_paths()
+
+	if (conflicts.length === 0 || main_merge_regenerate.is_resolvable(conflicts)) return undefined
+
+	const out = [CONFLICT_NOTE, ...conflicts, fix_note()].join('\n')
+
+	return { code: FAILURE_EXIT_CODE, out, conflicts }
+}
+
+const run_ship_conflict_probe = { CONFLICT_NOTE, probe }
+
+export { run_ship_conflict_probe }