@joshuafolkken/kit 1.1514.0 → 1.2114.0

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,13 +52,14 @@ 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
 // 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
@@ -91,6 +93,7 @@ interface DetachRequest {
 	body: ReadonlyArray<string>
 	cites: ReadonlyArray<string>
 	is_review: boolean
+	unpinned_ok: ReadonlyArray<string>
 	repository: string
 	cwd: string
 }
@@ -105,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 {
@@ -146,35 +149,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 {
@@ -188,7 +199,9 @@ function current_record(repository: string, number: string): ShipRecord | undefi
 function running_since(repository: string, number: string): number | undefined {
 	const record = read_record(repository, number)
 
-	return record !== undefined && result_of(record) === 'running' ? record.launched_at : undefined
+	return record !== undefined && result_of(record, process_identity.read_start) === 'running'
+		? record.launched_at
+		: undefined
 }
 
 function is_pending(record: ShipRecord | undefined): boolean {
@@ -266,6 +279,7 @@ function supervisor_argv(request: DetachRequest): LaunchArgv {
 			'josh',
 			'ship',
 			...review,
+			...request.unpinned_ok,
 			...notify_arguments(request),
 			...request.body,
 			...cites,
@@ -370,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

@@ -0,0 +1,74 @@
+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'
+
+// 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
+}
+
+// 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 run_attempt(attempt, retries_left)
+
+	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-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 }

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

@@ -1,5 +1,7 @@
+import { shell_quote } from '#scripts/lib/shell-quote'
 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
@@ -13,9 +15,9 @@ import type { ShipArguments } from './run-ship-steps'
 //
 // **Every route is a re-detach.** The prompt only ever reaches a lane child, and a lane child's commit
 // and push belong to the detached ship (`scripts/rules/lane-background.ts`), so a `josh git -y` here could never
-// run. The rounds are the supervisor's too: under `--review` it skips a round 1 already recorded for the
-// issue and asks `review:round2` itself after the commit (`run-ship-review-steps.ts`), so the fix delta
-// is verified as round 2 rather than reviewed again as round 1.
+// run. The rounds are the supervisor's too: under `--review` it reuses a round 1 recorded on a tree
+// unmoved or moved only where round 2 reads, reviews only the delta from that record otherwise, and asks `review:round2` itself after the
+// commit (`run-ship-review-steps.ts`), so the whole change is never reviewed again as round 1.
 //
 // **The re-run carries the stopped ship's own options.** A preflight that stopped on missing live
 // evidence asks for `--body-file`, and `followup` delivers the body from it; a command naming only
@@ -29,33 +31,25 @@ const COMMAND = {
 	DETACH_REVIEW: 'pnpm josh ship --detach --review',
 } as const
 
-// A single quote cannot appear inside single quotes, so it closes the quote, escapes one, and reopens.
-const ESCAPED_QUOTE = String.raw`'\''`
-
-// A token of only these characters means the same to the shell quoted or not, so it is left bare.
-const BARE_WORD = /^[\w%+,./:=@-]+$/u
-
 // What a stopped ship is re-run with: its title, every option it was started with, and whether it
 // carried `--review` — the one option a route decides rather than repeats.
 interface ShipResume {
 	title: string
 	flags: ReadonlyArray<string>
 	is_review: boolean
+	// `--unpinned-ok "<reason>"` as started; `josh ship` refuses it without `--review`, so only a
+	// command that carries `--review` repeats it.
+	unpinned_ok?: ReadonlyArray<string>
 	// The paths a merge of the default branch left unmerged.
 	conflicts?: ReadonlyArray<string>
-}
-
-// Single quotes, so a `$` or a backtick in a title is never expanded by the shell that runs it.
-function quoted(title: string): string {
-	return `'${title.split("'").join(ESCAPED_QUOTE)}'`
-}
-
-function shell_word(token: string): string {
-	return BARE_WORD.test(token) ? token : quoted(token)
+	// 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
 }
 
 // A supervised ship's notify tail is already file-form (`run-ship-detach.ts`), so every flag is a path
-// or an issue number and fits the prompt.
+// or an issue number and fits the prompt; `shell_quote.word` quotes the `--unpinned-ok` reason.
 function resume_of(args: ShipArguments): ShipResume {
 	const cites = args.cites.flatMap((cite) => ['--cite', cite])
 
@@ -63,28 +57,40 @@ function resume_of(args: ShipArguments): ShipResume {
 		title: args.title,
 		flags: [...args.notify, ...args.body, ...cites],
 		is_review: args.is_review,
+		unpinned_ok: args.unpinned_ok,
 	}
 }
 
 // The command prefix stays as written; only the stopped ship's own tokens are quoted where needed.
-function ship_command(command: string, resume: ShipResume): string {
-	const words = [...resume.flags, resume.title].map((token) => shell_word(token))
+function ship_command(
+	command: string,
+	resume: ShipResume,
+	review_flags: ReadonlyArray<string> = [],
+): string {
+	const words = [...review_flags, ...resume.flags, resume.title].map((token) =>
+		shell_quote.word(token),
+	)
 
 	return [command, ...words].join(' ')
 }
 
+function review_command(resume: ShipResume): string {
+	return ship_command(COMMAND.DETACH_REVIEW, resume, resume.unpinned_ok)
+}
+
 // After the merge-side stages, or after round 2 — which is final — the re-detach reviews nothing.
 function detach_again(resume: ShipResume): string {
 	return `leave the fix uncommitted and run \`${ship_command(COMMAND.DETACH, resume)}\`.`
 }
 
 // Before round 2 the re-run takes the stopped ship's own shape: `--review` only when it carried it. A
-// reviewing ship skips its recorded round 1 and decides round 2 after the commit; a ship started
+// reviewing ship reviews only the fix delta from its recorded round 1 and decides round 2 after the
+// commit; a ship started
 // without `--review` was re-detached after round 2, which is final, so it reviews nothing.
 function detach_as_started(resume: ShipResume): string {
-	const command = resume.is_review ? COMMAND.DETACH_REVIEW : COMMAND.DETACH
+	const command = resume.is_review ? review_command(resume) : ship_command(COMMAND.DETACH, resume)
 
-	return `leave the fix uncommitted and run \`${ship_command(command, resume)}\`.`
+	return `leave the fix uncommitted and run \`${command}\`.`
 }
 
 const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
@@ -98,6 +104,17 @@ 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 \`${review_command(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 {
@@ -116,11 +133,11 @@ function fix_step(issue: string, stage: Stage, is_excerpted: boolean): 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 `${fix_step(issue, stage, is_excerpted)}, 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 }
+const run_ship_next = { COMMAND, next_step, resume_of }
 
 export { run_ship_next, type ShipResume }

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

@@ -1,9 +1,12 @@
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_diff_reads } from '#scripts/git/git-diff-reads'
+import { git_merge_conflicts } from '#scripts/git/git-merge-conflicts'
 import { git_spawn } from '#scripts/git/git-spawn'
+import { main_merge_regenerate } from '#scripts/git/main-merge-regenerate'
 import { session_cite } from '#scripts/issue/session-cite'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
-import { lane_ledger, type OverlapRecord } from '#scripts/lane/lane-ledger'
+import type { OverlapRecord } from '#scripts/lane/lane-ledger-schema'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { poll } from '#scripts/lib/poll'
 
@@ -13,7 +16,7 @@ import { poll } from '#scripts/lib/poll'
 // often as a `conflict` stop its child no longer had the context for.
 //
 // **The later ship waits for the earlier one rather than anything being pushed into a lane.** A lane
-// whose actual change overlaps this one's and whose pull request is already open (its branch pushed,
+// whose actual change conflicts with this one's and whose pull request is already open (its branch pushed,
 // its detached ship still running) is waited on until that ship ends, merged or stopped; the sync that
 // follows then merges a default branch that already holds it, so a conflict surfaces before this
 // lane's gate rather than after its CI. Merging into the other lane's tree instead could not work: a
@@ -37,6 +40,13 @@ const NAME_ONLY_ARGUMENTS = [
 	'--no-relative',
 	'--no-renames',
 ]
+// Only the regenerated entries: a rewritten one resolves some conflicts and refuses the rest, so its
+// conflict is still waited on.
+const REGENERATED_PATHS: ReadonlySet<string> = new Set(
+	main_merge_regenerate.RESOLVED_FILES.filter((entry) => 'command' in entry).map(
+		(entry) => entry.path,
+	),
+)
 
 interface OverlapOptions {
 	sleeper?: (duration_ms: number) => Promise<void>
@@ -102,6 +112,35 @@ async function is_open_ship(lane: LaneInfo, own: Launch): Promise<boolean> {
 	return await has_upstream(lane.directory)
 }
 
+async function lane_head(directory: string): Promise<string | undefined> {
+	try {
+		return await git_spawn.read(['-C', directory, 'rev-parse', 'HEAD'])
+	} catch {
+		return undefined
+	}
+}
+
+// Of the paths both lanes change, the ones merging the other lane's head into this lane's working
+// tree would actually stop on (joshuafolkken/kit#4348) — the working tree, since this lane's change is
+// not committed until after the sync: an identical addition merges cleanly, so only a real conflict
+// is waited on. Only a shared path is tried: a lane forked from an older default branch also
+// conflicts on files the default branch changed since, which this lane's sync takes from the default
+// branch, not from that lane. A file `main:merge` regenerates is resolved by the sync either way, so
+// it never counts. A merge that could not be tried falls back to every shared path, as the wait was
+// decided before.
+async function conflicting_paths(
+	lane: LaneInfo,
+	shared: ReadonlyArray<string>,
+): Promise<Array<string>> {
+	const theirs = await lane_head(lane.directory)
+	const conflicted =
+		theirs === undefined
+			? undefined
+			: git_merge_conflicts.working_tree_conflicts(theirs, shared, process.cwd())
+
+	return (conflicted ?? shared).filter((file_path) => !REGENERATED_PATHS.has(file_path))
+}
+
 async function shared_paths(
 	lane: LaneInfo,
 	launch: Launch,
@@ -110,8 +149,11 @@ async function shared_paths(
 	if (!(await is_open_ship(lane, launch))) return []
 
 	const paths = await lane_paths(lane.directory)
+	const shared = paths.filter((file_path) => own.has(file_path))
+
+	if (shared.length === 0) return []
 
-	return paths.filter((file_path) => own.has(file_path))
+	return await conflicting_paths(lane, shared)
 }
 
 async function other_lanes(issue: string): Promise<ReadonlyArray<LaneInfo>> {
@@ -120,8 +162,8 @@ async function other_lanes(issue: string): Promise<ReadonlyArray<LaneInfo>> {
 	return lanes.filter((lane) => lane.issue !== issue && !lane.is_stranded)
 }
 
-// Every other lane whose open pull request, shipped before this one, touches a path this lane changed,
-// with the shared paths.
+// Every other lane whose open pull request, shipped before this one, conflicts with this lane's change,
+// with the conflicting paths.
 async function find_overlap(issue: string): Promise<Overlap> {
 	const own = new Set(await changed_paths.read_changed_paths(false))
 	const launch = own_launch(issue)
@@ -174,7 +216,7 @@ async function await_overlap(
 	const waited_ms = Date.now() - started
 	const record = { issue: Number(issue), lanes, paths: [...overlap.paths], waited_ms, is_cleared }
 
-	await lane_ledger.record_overlap(record, options.ledger)
+	await lane_ledger_write.record_overlap(record, options.ledger)
 
 	return record
 }
@@ -186,7 +228,7 @@ function note(record: OverlapRecord | undefined): string {
 	const lanes = record.lanes.map((lane) => session_cite.issue(lane)).join(', ')
 	const outcome = record.is_cleared ? 'waited for' : 'gave up waiting for'
 
-	return `${outcome} ${lanes}, whose open pull requests also change: ${record.paths.join(', ')}`
+	return `${outcome} ${lanes}, whose open pull requests conflict on: ${record.paths.join(', ')}`
 }
 
 const run_ship_overlap = { MAX_WAIT_ATTEMPTS, await_overlap, note }