@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,21 +1,27 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
-import { lane_ledger } from '#scripts/lane/lane-ledger'
+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_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
@@ -47,7 +53,7 @@ const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 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'
@@ -61,9 +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
+}
+
+interface ShipOutcome {
+	sections: ReadonlyArray<ShipSection>
+	is_handed_over: boolean
 }
 
 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.
@@ -72,12 +86,16 @@ const { PHASE, STAGE } = run_ship_stage
 // 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_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)
@@ -97,15 +115,31 @@ async function run_step(step: Step, args: ShipArguments, state: ShipState): Prom
 	})
 }
 
+// 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
@@ -124,13 +158,13 @@ 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)
@@ -150,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 }
 	}
@@ -159,20 +193,22 @@ 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)
-	// 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())
+	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)
@@ -183,7 +219,7 @@ async function open_context(args: ShipArguments): Promise<ShipContext> {
 		run_ship_stage.clear_waits(path)
 	})
 
-	return { target, done, state, started }
+	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
@@ -192,7 +228,7 @@ async function open_context(args: ShipArguments): Promise<ShipContext> {
 async function record_stop(args: ShipArguments, stage: Stage, failed?: ShipSection): Promise<void> {
 	const issue = Number(args.number)
 
-	await lane_ledger.record_stop(run_ship_stop_cause.record_of(issue, stage, failed))
+	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) })
 }
 
@@ -217,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> {
@@ -283,11 +341,29 @@ 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 {
+// 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 ?? []), lane_ledger.PRE_DETACH_STAGE] }
+	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
@@ -296,19 +372,32 @@ function with_checks(stop: ShipSection, checks: ShipSection): ShipSection {
 // 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.
+// 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.
+// 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 result = await run_ship_pre_detach_timed.checks(args.number)
+	const conflict = await run_ship_conflict_probe.probe()
+
+	if (conflict !== undefined) return await conflict_sections(args, conflict, 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 }
 
-	if (preflight.code !== SUCCESS_EXIT_CODE) {
-		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage, with_checks(preflight, 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 [checks, preflight]
@@ -343,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)
 
@@ -351,9 +442,10 @@ 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)

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 }

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

@@ -3,6 +3,7 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { session_cite } from '#scripts/issue/session-cite'
+import { durable_state } from '#scripts/josh/durable-state'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
@@ -33,7 +34,7 @@ import { z } from 'zod'
 // probe cannot momentarily read is the opposite case: the pid is alive and was verified once, so it is
 // kept running rather than read as a crash that would license a second supervisor.
 
-const LOG_PREFIX = 'josh-ship-log-'
+const LOG_PREFIX = durable_state.PREFIX.SHIP_LOG
 const PID_PREFIX = 'josh-ship-pid-'
 const BODY_PREFIX = 'josh-ship-notify-'
 const KEY_SEPARATOR = '-'
@@ -51,7 +52,7 @@ const SUPERVISED_VALUE = '1'
 const LAUNCHED = 'launched'
 const BUSY = 'busy'
 const FAILED = 'failed'
-const RESULT_PREFIX = 'josh-ship-result-'
+const RESULT_PREFIX = durable_state.PREFIX.SHIP_RESULT
 const RECORD_POLL_MS = 25
 const RECORD_WAIT_ATTEMPTS = 200
 // How long a bare launched pid is believed before the supervisor must have claimed the record: far above
@@ -92,6 +93,7 @@ interface DetachRequest {
 	body: ReadonlyArray<string>
 	cites: ReadonlyArray<string>
 	is_review: boolean
+	unpinned_ok: ReadonlyArray<string>
 	repository: string
 	cwd: string
 }
@@ -106,11 +108,11 @@ function key(prefix: string, request: Pick<DetachRequest, 'number' | 'repository
 }
 
 function log_path(repository: string, number: string): string {
-	return stamp_file.stamp_path(`${LOG_PREFIX}${number}${KEY_SEPARATOR}`, repository, LOG_SUFFIX)
+	return durable_state.path(`${LOG_PREFIX}${number}${KEY_SEPARATOR}`, repository, LOG_SUFFIX)
 }
 
 function result_path(repository: string, number: string): string {
-	return stamp_file.stamp_path(`${RESULT_PREFIX}${number}${KEY_SEPARATOR}`, repository)
+	return durable_state.path(`${RESULT_PREFIX}${number}${KEY_SEPARATOR}`, repository)
 }
 
 function read_record(repository: string, number: string): ShipRecord | undefined {
@@ -277,6 +279,7 @@ function supervisor_argv(request: DetachRequest): LaunchArgv {
 			'josh',
 			'ship',
 			...review,
+			...request.unpinned_ok,
 			...notify_arguments(request),
 			...request.body,
 			...cites,
@@ -381,8 +384,11 @@ const run_ship_detach = {
 	last_launch,
 	log_path,
 	read_log,
+	read_record,
+	result_path,
 	running_since,
 	supervisor_argv,
+	supervisor_environment,
 }
 
 export type { DetachRequest, DetachResult }

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

@@ -0,0 +1,106 @@
+import { fileURLToPath } from 'node:url'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { process_identity } from '#scripts/josh/process-identity'
+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_code } from '#scripts/run/wake/run-wake-code'
+import { run_wake_stop } from '#scripts/run/wake/run-wake-stop'
+import { run_wake_takeover, type TakeoverPorts } from '#scripts/run/wake/run-wake-takeover'
+import type { ShipSection } from './run-ship'
+import { run_ship_detach } from './run-ship-detach'
+import { run_ship_probe } from './run-ship-probe'
+import { run_ship_relaunch } from './run-ship-relaunch'
+import type { ShipArguments } from './run-ship-steps'
+
+// A supervisor whose sync merged a change to its own code hands the ship to a successor on that code
+// (joshuafolkken/kit#4849). The stages run in one process, so a review stage after a sync that pulled
+// a fix to `scripts/review/` still judged on the code the supervisor started with.
+//
+// **The wake supervisor's mechanism, shared**: the loaded code is the import closure of the ship entry
+// (`run-wake-code.ts`), and the successor's own claim on the ship record is the take-over's proof
+// (`run-wake-takeover.ts`). A successor that dies or never claims leaves the record naming this
+// supervisor, which runs the rest on the code it started with.
+
+const ENTRY = fileURLToPath(new URL('run-ship-cli.ts', import.meta.url))
+const ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+const HANDOVER_HEADER = '=== handover ==='
+const SUCCESS_EXIT_CODE = 0
+
+type CodeCheck = () => Promise<boolean>
+
+async function never_stale(): Promise<boolean> {
+	return false
+}
+
+// Only a supervisor hands over: a ship in an agent's own turn ends with that turn, which reads the
+// next command on the merged code anyway.
+async function watch(): Promise<CodeCheck> {
+	if (!run_ship_detach.is_supervised()) return never_stale
+
+	return await run_wake_code.watch(run_wake_code.source_of(ROOT, ENTRY))
+}
+
+function ports_of(repository: string, number: string): TakeoverPorts {
+	return {
+		holder_pid: () => run_ship_relaunch.holder_pid(repository, number),
+		is_alive: process_identity.is_live_pid,
+		stop: run_wake_stop.signal,
+	}
+}
+
+// Several lanes' supervisors hand over at once, so each note leads with its issue for `run:board`.
+async function note(number: string, text: string): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`${issue_cite.plain(number)} ${text}`,
+	)
+}
+
+async function take_over(args: ShipArguments, repository: string): Promise<number | undefined> {
+	const pid = run_ship_relaunch.relaunch({ repository, number: args.number, cwd: process.cwd() })
+	if (pid === undefined) return undefined
+	const result = await run_wake_takeover.await_takeover(pid, ports_of(repository, args.number))
+
+	return result === 'taken' ? pid : undefined
+}
+
+function handed_over(pid: number): ShipSection {
+	return {
+		header: HANDOVER_HEADER,
+		body: `code changed on main — process ${String(pid)} ships the rest on the new code`,
+		code: SUCCESS_EXIT_CODE,
+	}
+}
+
+// The handover section where a successor took the ship over; `undefined` where the code is unchanged
+// or no successor took it, and this supervisor runs the rest of the stages itself.
+async function hand_over(
+	args: ShipArguments,
+	is_stale: CodeCheck,
+): Promise<ShipSection | undefined> {
+	if (!(await is_stale())) return undefined
+	const repository = await run_ship_probe.repository_directory()
+	if (repository === undefined) return undefined
+	const pid = await take_over(args, repository)
+
+	if (pid === undefined) {
+		await note(
+			args.number,
+			`The ship supervisor's code changed on main, but no successor took the ship over, so process ${String(process.pid)} runs the rest on the code it started with.`,
+		)
+
+		return undefined
+	}
+
+	await note(
+		args.number,
+		`The ship supervisor's code changed on main, so process ${String(process.pid)} handed the ship to process ${String(pid)} on the new code.`,
+	)
+
+	return handed_over(pid)
+}
+
+const run_ship_handover = { hand_over, watch }
+
+export type { CodeCheck }
+export { run_ship_handover }

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

@@ -1,4 +1,5 @@
 import { setTimeout as delay } from 'node:timers/promises'
+import { RETRY_PENDING_KEY, RETRY_PENDING_VALUE } from '#scripts/gh/git-gh-comments-unreadable'
 import type { ShipSection } from './run-ship'
 import type { Stage } from './run-ship-stage'
 import { run_ship_stop_cause } from './run-ship-stop-cause'
@@ -35,13 +36,27 @@ function is_retryable(stage: Stage, section: ShipSection): boolean {
 	return run_ship_stop_cause.cause_of(stage, section) === run_ship_stop_cause.CAUSE.INFRA
 }
 
+// An attempt with a retry still left runs with `RETRY_PENDING_KEY` set, so its stop sends no
+// confirmation; the final attempt runs without it and sends the one confirmation.
+async function run_attempt(attempt: Attempt, retries_left: number): Promise<ShipSection> {
+	if (retries_left === 0) return await attempt()
+
+	process.env[RETRY_PENDING_KEY] = RETRY_PENDING_VALUE
+
+	try {
+		return await attempt()
+	} finally {
+		Reflect.deleteProperty(process.env, RETRY_PENDING_KEY)
+	}
+}
+
 async function retried(
 	stage: Stage,
 	attempt: Attempt,
 	hooks: RetryHooks = DEFAULT_HOOKS,
 	retries_left = MAX_INFRA_RETRIES,
 ): Promise<ShipSection> {
-	const section = await attempt()
+	const section = await run_attempt(attempt, retries_left)
 
 	if (retries_left === 0 || !is_retryable(stage, section)) return section
 

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

@@ -0,0 +1,63 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { ShipLapRecord } from '#scripts/lane/lane-ledger-schema'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+
+// The inner steps of a `josh ship` stage, each timed into the lane ledger as a lap, so `lane:breakdown`
+// names what a stage spent its minutes on (joshuafolkken/kit#5294). The stage and the issue are held
+// for the stage's whole run (`within`), so a step deep inside it — the scoped pair the preflight, the
+// review rounds and the gate share — is timed without either being passed down to it. A step run
+// outside a ship stage (the followup's own gate) has no stage to belong to and is not timed.
+
+interface LapScope {
+	issue: number
+	stage: string
+}
+
+type LapSink = (lap: ShipLapRecord) => Promise<void>
+
+// The names a lap is written under, read back by `lane:breakdown` and `lane:stats` as they are.
+const STEP = {
+	PRECONDITIONS: 'preconditions',
+	SCOPED_PAIR: 'scoped pair',
+	GATE: 'josh gate',
+	OVERLAP_WAIT: 'overlap wait',
+	LOCAL_COMMIT: 'local commit',
+	MERGE: 'merge',
+	PUSH: 'push',
+	COMMIT: 'josh git',
+} as const
+
+const scope = new AsyncLocalStorage<LapScope>()
+
+async function to_ledger(lap: ShipLapRecord): Promise<void> {
+	await lane_ledger_write.record_ship_lap(lap)
+}
+
+async function within<T>(issue: string, stage: string, run: () => Promise<T>): Promise<T> {
+	return await scope.run({ issue: Number(issue), stage }, run)
+}
+
+// A step that threw still cost the stage its time, so it is timed either way; the append is
+// best-effort (`lane-ledger-write.ts`), so it never replaces the step's own error.
+async function timed<T>(
+	step: string,
+	run: () => Promise<T>,
+	sink: LapSink = to_ledger,
+): Promise<T> {
+	const current = scope.getStore()
+
+	if (current === undefined) return await run()
+
+	const started_ms = performance.now()
+
+	try {
+		return await run()
+	} finally {
+		await sink({ ...current, step, elapsed_ms: performance.now() - started_ms })
+	}
+}
+
+const run_ship_lap = { STEP, timed, within }
+
+export type { LapSink }
+export { run_ship_lap }