@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/run/{run-ship-cli.ts → ship/run-ship-cli.ts}

@@ -2,11 +2,12 @@
 import { fileURLToPath } from 'node:url'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
+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_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_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'
@@ -171,8 +172,9 @@ function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
 
 async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
 	const result = await step.run(args, state)
+	const section = { header: step.header, body: result.out, code: result.code }
 
-	return { header: step.header, body: result.out, code: result.code }
+	return result.conflicts === undefined ? section : { ...section, conflicts: result.conflicts }
 }
 
 async function emit_phase(args: ShipArguments, stage: Stage, phase: Phase): Promise<void> {
@@ -249,7 +251,14 @@ async function stopped(
 	stage: Stage,
 ): Promise<ReadonlyArray<ShipSection>> {
 	if (run_ship_detach.is_supervised()) {
-		await run_ship_return.return_control(args.number, stage, run_ship_next.resume_of(args))
+		const conflicts = sections.at(-1)?.conflicts
+		const resume = run_ship_next.resume_of(args)
+
+		await run_ship_return.return_control(
+			args.number,
+			stage,
+			conflicts === undefined ? resume : { ...resume, conflicts },
+		)
 	}
 
 	return sections
@@ -324,14 +333,26 @@ function should_detach(args: ShipArguments): boolean {
 // joshuafolkken/kit#2966: 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.
+// joshuafolkken/kit#3222: 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.
+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))
+	if (preflight.code !== SUCCESS_EXIT_CODE) return [preflight]
+
+	const result = await run_ship_pre_detach.checks()
+
+	return [preflight, { header: run_ship.PRE_DETACH_HEADER, body: result.out, code: result.code }]
+}
+
 async function detach_after_preflight(args: ShipArguments): Promise<number> {
-	const section = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
+	const sections = await pre_detach_sections(args)
+	const code = run_ship.exit_code(sections)
 
-	if (section.code === SUCCESS_EXIT_CODE) return await detach(args)
+	if (code === SUCCESS_EXIT_CODE) return await detach(args)
 
-	console.info(run_ship.format_report([section]))
+	console.info(run_ship.format_report(sections))
 
-	return run_ship.exit_code([section])
+	return code
 }
 
 async function supervised_repository(): Promise<string | undefined> {

package/scripts/run/{run-ship-detach.ts → ship/run-ship-detach.ts}

@@ -3,10 +3,10 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
+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 { z } from 'zod'
-import { detached_launch, type LaunchArgv } from './detached-launch'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
 
 // `josh ship --detach` — hand the post-implementation region to a supervisor that outlives the agent
 // (joshuafolkken/kit#2428). A lane child used to take the pre-gate cut and relaunch a fresh agent session

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

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { stripVTControlCharacters } from 'node:util'
+import { buffered_process } from '#scripts/lib/buffered-process'
+import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
+
+// A lock file that no longer matches its inputs, asked before the gate (joshuafolkken/kit#3307).
+//
+// The pre-push hook's setup runs `pnpm install`, which rewrites a lock that has drifted — a
+// `.pnpmfile.mjs` edit moves `pnpmfileChecksum` — and so leaves the working tree dirty under the push.
+// The hook then refuses the gate's record and re-runs the whole unit suite, long enough under a crowded
+// machine to time the push out. The frozen, lock-only install answers the same question without
+// writing anything or touching `node_modules`, in about a third of a second.
+//
+// A project with no lock file has nothing to drift, so nothing is asked there.
+//
+// **pnpm's own error line rides along**: the install refuses for reasons other than drift too — an
+// engine mismatch, a timeout on a crowded machine — and there "run `pnpm install`" fixes nothing, so
+// the reader needs pnpm's error code to tell the two apart. The line naming an `ERR_PNPM_` code wins
+// over the first line, which in a workspace is pnpm's "Scope: all N workspace projects" banner.
+
+const LOCK_FILE = 'pnpm-lock.yaml'
+const PNPM_ERROR_CODE = 'ERR_PNPM_'
+const LOCK_CHECK_ARGUMENTS = ['install', '--frozen-lockfile', '--lockfile-only', '--ignore-scripts']
+const LOCK_DRIFT = `${LOCK_FILE} does not match its inputs (\`pnpm install --frozen-lockfile\` refuses it), so the pre-push hook's install would rewrite it under the push: run \`pnpm install\` and commit ${LOCK_FILE}.`
+
+function drift_problem(output: string): string {
+	const lines = stripVTControlCharacters(output)
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line !== '')
+	const reason = lines.find((line) => line.includes(PNPM_ERROR_CODE)) ?? lines[0]
+
+	return reason === undefined ? LOCK_DRIFT : `${LOCK_DRIFT} pnpm said: ${reason}`
+}
+
+async function lock_problems(directory: string = process.cwd()): Promise<Array<string>> {
+	if (!existsSync(path.join(directory, LOCK_FILE))) return []
+
+	const result = await buffered_process.run_buffered_process(LOCK_CHECK_ARGUMENTS, {
+		cwd: directory,
+		timeout_ms: INSTALL_TIMEOUT_MS,
+	})
+
+	return buffered_process.is_process_failed(result) ? [drift_problem(result.output)] : []
+}
+
+const run_ship_lock = { LOCK_CHECK_ARGUMENTS, LOCK_DRIFT, lock_problems }
+
+export { run_ship_lock }

package/scripts/run/{run-ship-next.ts → ship/run-ship-next.ts}

@@ -42,6 +42,8 @@ interface ShipResume {
 	title: string
 	flags: ReadonlyArray<string>
 	is_review: boolean
+	// The paths a merge of the default branch left unmerged (joshuafolkken/kit#3221).
+	conflicts?: ReadonlyArray<string>
 }
 
 // Single quotes, so a `$` or a backtick in a title is never expanded by the shell that runs it.
@@ -90,14 +92,25 @@ const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
 	[STAGE.PREFLIGHT]: detach_as_started,
 	[STAGE.REVIEW]: detach_as_started,
 	[STAGE.GATE]: detach_as_started,
+	[STAGE.SYNC]: detach_as_started,
 	[STAGE.COMMIT]: detach_as_started,
 	[STAGE.ROUND_TWO]: detach_again,
 	[STAGE.FOLLOWUP]: detach_again,
 	[STAGE.REPORT]: detach_again,
 }
 
+// A conflict names its paths (joshuafolkken/kit#3221), 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`
+}
+
 // 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 {
+	const conflicts = resume.conflicts ?? []
+
+	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)}`
 }
 

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

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { type_check_step } from '#scripts/gate/type-check-step'
+import type { JoshResult } from '#scripts/josh/josh-run'
+import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+
+// The fast checks a detached `josh ship` runs in the agent's own turn, after the preflight and before
+// the hand-off (joshuafolkken/kit#3222). In one measured backlogrun about 7 of 31 lane resumes were a
+// gate failure first seen after the detach — a type error in a file the related-only checks never
+// touched, or a document test (a SKILL.md pointer, a byte budget, the command list) that only the full
+// suite runs — each paid for with a relaunched session. These two answer in seconds, so the same
+// session fixes what they find and ships again. **Nothing moves out of the gate**: the supervised gate
+// stage still runs every check, these included.
+//
+// The test targets are the directories those resumes failed in. A consumer has none of them, so only
+// the ones present run, and a consumer meets the type check alone.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const SECTION_SEPARATOR = '\n\n'
+const PASSED = 'type check and document tests passed'
+const DOCUMENT_TEST_TARGETS: ReadonlyArray<string> = [
+	'scripts/document',
+	'scripts/claude',
+	'scripts/rules',
+	'scripts/josh/josh-command-map.test.ts',
+]
+// A present directory need not hold a test the project's Vitest includes — a consumer's own
+// `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
+const DOCUMENT_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+
+function present_targets(directory: string): ReadonlyArray<string> {
+	return DOCUMENT_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
+}
+
+async function command_lists(directory: string): Promise<Array<ReadonlyArray<string>>> {
+	const type_check = await type_check_step.resolve_type_check_args(directory)
+	const targets = present_targets(directory)
+
+	return targets.length === 0 ? [type_check] : [type_check, [...DOCUMENT_TEST_COMMAND, ...targets]]
+}
+
+async function run_in(
+	directory: string,
+	list: ReadonlyArray<string>,
+): Promise<BufferedProcessResult> {
+	return await buffered_process.run_buffered_process(list, { cwd: directory })
+}
+
+// Both run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
+async function checks(directory: string = process.cwd()): Promise<JoshResult> {
+	const lists = await command_lists(directory)
+	const results = await Promise.all(lists.map(async (list) => await run_in(directory, list)))
+	const failed = results.filter((result) => buffered_process.is_process_failed(result))
+
+	if (failed.length === 0) return { code: SUCCESS_EXIT_CODE, out: PASSED }
+
+	return {
+		code: FAILURE_EXIT_CODE,
+		out: failed.map((result) => result.output.trim()).join(SECTION_SEPARATOR),
+	}
+}
+
+const run_ship_pre_detach = { DOCUMENT_TEST_TARGETS, PASSED, checks }
+
+export { run_ship_pre_detach }

package/scripts/run/{run-ship-preflight.ts → ship/run-ship-preflight.ts}

@@ -7,6 +7,7 @@ import { git_preflight } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
 import { live_evidence } from '#scripts/review/live-evidence'
+import { run_ship_lock } from './run-ship-lock'
 import { run_ship_scoped } from './run-ship-scoped'
 
 // `josh ship`'s first stage (joshuafolkken/kit#2946). A detached ship used to meet the pull request's
@@ -71,13 +72,16 @@ async function caught(problems: Promise<Array<string>>): Promise<Array<string>>
 	}
 }
 
+// The lock file is asked here too (joshuafolkken/kit#3307), so a drift stops the ship before the gate
+// rather than being rewritten by the pre-push hook's install under the push.
 async function asked_problems(request: PreflightRequest): Promise<Array<string>> {
-	const [preflight, evidence] = await Promise.all([
+	const [preflight, evidence, lock] = await Promise.all([
 		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
 		caught(evidence_problems(request.body_path)),
+		caught(run_ship_lock.lock_problems()),
 	])
 
-	return [...preflight, ...evidence]
+	return [...preflight, ...evidence, ...lock]
 }
 
 async function stage(request: PreflightRequest): Promise<JoshResult> {

package/scripts/run/{run-ship-probe.ts → ship/run-ship-probe.ts}

@@ -1,8 +1,8 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { error_text } from '#scripts/lib/error-message'
-import { run_hold } from './run-hold'
-import { run_preflight } from './run-preflight'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_preflight } from '#scripts/run/run-preflight'
 import { run_ship_stage, type ShipState } from './run-ship-stage'
 
 // The read side of a resumed `josh ship` (joshuafolkken/kit#2426): the repository's actual state, asked

package/scripts/run/{run-ship-return.ts → ship/run-ship-return.ts}

@@ -3,10 +3,11 @@ import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
+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 type { ShipResume } from './run-ship-next'
-import type { Stage } from './run-ship-stage'
+import { run_ship_stage, type Stage } from './run-ship-stage'
+import { run_ship_stop_text } from './run-ship-stop-text'
 
 // How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
@@ -28,8 +29,8 @@ const OPENAI_PROVIDER = 'openai'
 
 type ReturnOutcome = 'relaunched' | 'recorded'
 
-function stop_text(issue: string, stage: Stage): string {
-	return `#${issue} ${stage} failed — pnpm josh ship --log ${issue}`
+function stop_text(issue: string, stage: Stage, resume: ShipResume): string {
+	return run_ship_stop_text.format(issue, run_ship_stage.stop_reason(stage, resume.conflicts))
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
@@ -53,7 +54,10 @@ async function return_control(
 	stage: Stage,
 	resume: ShipResume,
 ): Promise<ReturnOutcome> {
-	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STOP, stop_text(issue, stage))
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.SHIP_STOP,
+		stop_text(issue, stage, resume),
+	)
 
 	const lane = await lane_to_relaunch(issue)
 

package/scripts/run/{run-ship-review-steps.ts → ship/run-ship-review-steps.ts}

@@ -6,7 +6,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
 import { review_record } from '#scripts/review/review-record'
-import { detached_launch } from './detached-launch'
+import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
 import { run_ship_scoped, type Phase } from './run-ship-scoped'
 
@@ -59,8 +59,8 @@ function failure(out: string): JoshResult {
 	return { code: FAILURE_EXIT_CODE, out }
 }
 
-function paths(root: string = PROJECT_ROOT): { brief: string; findings: string; log: string } {
-	return openai_review_broker.review_paths(root)
+function paths(): { brief: string; findings: string; log: string } {
+	return openai_review_broker.review_paths(PROJECT_ROOT)
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {

package/scripts/run/{run-ship-scoped.ts → ship/run-ship-scoped.ts}

@@ -39,7 +39,16 @@ async function scoped_pair(): Promise<JoshResult> {
 	)
 }
 
-const run_ship_scoped = { run_phases, scoped_pair }
+// The scoped pair and then `josh gate` — the gate stage, and the followup's gate over a merged tree
+// before its push (joshuafolkken/kit#3307), so both leave the record the pre-push hook reuses.
+async function scoped_gate(): Promise<JoshResult> {
+	return await run_phases([
+		scoped_pair,
+		async () => await josh_command.josh_run(['gate'], should_forward_stderr),
+	])
+}
+
+const run_ship_scoped = { run_phases, scoped_gate, scoped_pair }
 
 export type { Phase }
 export { run_ship_scoped }

package/scripts/run/{run-ship-stage.ts → ship/run-ship-stage.ts}

@@ -20,6 +20,7 @@ const STAGE = {
 	PREFLIGHT: 'preflight',
 	REVIEW: 'review',
 	GATE: 'gate',
+	SYNC: 'sync',
 	COMMIT: 'commit',
 	ROUND_TWO: 'round-2',
 	FOLLOWUP: 'followup',
@@ -99,6 +100,9 @@ const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => bo
 	// the recorded round, and only a commit pins the tree that round read.
 	[STAGE.REVIEW]: (_done, state) => state.is_merged || state.is_committed,
 	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
+	// The merge of the default branch before the commit (joshuafolkken/kit#3221): once committed, a
+	// conflicting pull request is the followup's to merge again.
+	[STAGE.SYNC]: (_done, state) => state.is_merged || state.is_committed,
 	[STAGE.COMMIT]: (done, state) => state.is_merged || (done.has(STAGE.COMMIT) && is_shipped(state)),
 	// The round-2 pass (joshuafolkken/kit#2489) reads the pushed fix delta, so its record is honored only
 	// while that push still stands — new work pushed on top reruns it.
@@ -138,6 +142,14 @@ function event_text(issue: string, stage: Stage, phase: Phase): string {
 	return `#${issue} ${stage} ${phase}`
 }
 
+// A stop on a merge git could not finish is named `conflict` rather than by the stage it happened in
+// (joshuafolkken/kit#3221), so the event stream reads the cause without anyone opening the report.
+const CONFLICT = 'conflict'
+
+function stop_reason(stage: Stage, conflicts: ReadonlyArray<string> = []): string {
+	return conflicts.length > 0 ? CONFLICT : stage
+}
+
 const run_ship_stage = {
 	PHASE,
 	STAGE,
@@ -148,6 +160,7 @@ const run_ship_stage = {
 	mark_done,
 	read_done,
 	record_path,
+	stop_reason,
 }
 
 export type { Phase, ShipState, Stage }

package/scripts/run/{run-ship-steps.ts → ship/run-ship-steps.ts}

@@ -4,6 +4,7 @@ import { run_ship_preflight } from './run-ship-preflight'
 import { run_ship_review_steps } from './run-ship-review-steps'
 import { run_ship_scoped } from './run-ship-scoped'
 import { run_ship_stage, type ShipState, type Stage } from './run-ship-stage'
+import { run_ship_sync, type StepResult } from './run-ship-sync'
 
 // The stages `josh ship` runs, in the order a change ships (joshuafolkken/kit#2398), kept apart from the
 // chaining CLI so the order is read in one place.
@@ -24,7 +25,7 @@ interface ShipArguments {
 interface Step {
 	stage: Stage
 	header: string
-	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
+	run: (args: ShipArguments, state: ShipState) => Promise<StepResult>
 }
 
 const { STAGE } = run_ship_stage
@@ -47,14 +48,19 @@ const PREFLIGHT_STEP: Step = {
 // with no green record (joshuafolkken/kit#2946). The commit step carries the `--skip-*` flags a resumed
 // ship needs, so an existing commit or push is never made twice.
 const COMMIT_STEPS: ReadonlyArray<Step> = [
+	// joshuafolkken/kit#3221: the default branch merged again before the commit, so the pull request
+	// opens on a branch that is current; a clean merge goes on without waking anyone. It runs before the
+	// gate (joshuafolkken/kit#3307): a merge after it moved the merge base the gate's record pins, so the
+	// pre-push hook could never reuse that record and re-ran the whole unit suite on every merged ship.
+	{
+		stage: STAGE.SYNC,
+		header: run_ship.SYNC_HEADER,
+		run: async () => await run_ship_sync.sync_stage(),
+	},
 	{
 		stage: STAGE.GATE,
 		header: run_ship.GATE_HEADER,
-		run: async () =>
-			await run_ship_scoped.run_phases([
-				run_ship_scoped.scoped_pair,
-				async () => await josh(['gate']),
-			]),
+		run: async () => await run_ship_scoped.scoped_gate(),
 	},
 	{
 		stage: STAGE.COMMIT,
@@ -69,7 +75,7 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.FOLLOWUP,
 		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await josh(['followup', args.title, ...args.notify]),
+		run: async (args) => await run_ship_sync.followup_stage(args.title, args.notify),
 	},
 	{
 		stage: STAGE.REPORT,
@@ -79,7 +85,8 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 ]
 
 // `--review` (joshuafolkken/kit#2427) puts the supervised round-1 review in front of the gate: it
-// launches the gate itself, so the gate stage that follows reuses that tree's green record. It also
+// launches the gate itself, so the gate stage that follows reuses that tree's green record unless the
+// sync stage between them merged the default branch and changed the tree. It also
 // puts the round-2 pass between the commit and the followup (joshuafolkken/kit#2489), so the PR opens
 // between the rounds and round 2 runs beside CI — a no-op when round 1 left no fix delta.
 const REVIEW_STEP: Step = {

package/scripts/run/ship/run-ship-stop-text.ts

@@ -0,0 +1,13 @@
+// The text a `josh ship` supervisor records when a stage stops, written and read in one place so the
+// retrospective's per-stage count never drifts from the writer (joshuafolkken/kit#3245).
+const STOP_PATTERN = /^#\d+ (\S+) failed — /u
+
+function format(issue: string, reason: string): string {
+	return `#${issue} ${reason} failed — pnpm josh ship --log ${issue}`
+}
+
+function reason_of(text: string): string | undefined {
+	return STOP_PATTERN.exec(text)?.[1]
+}
+
+export const run_ship_stop_text = { format, reason_of }

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

@@ -0,0 +1,128 @@
+import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
+import { is_merge_conflict } from '#scripts/gh/git-pr-checks-eval'
+import { git_command } from '#scripts/git/git-command'
+import { main_merge, type MergeOutcome } from '#scripts/git/main-merge'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { error_text } from '#scripts/lib/error-message'
+import { run_ship_scoped } from './run-ship-scoped'
+
+// `josh ship` keeps the branch current with the default branch itself (joshuafolkken/kit#3221). The
+// lane merged it once, before the hand-off, and nothing merged it again while the pull request opened
+// and CI ran — so a default branch that moved meanwhile stopped the followup as `interrupted`, and a
+// relaunched session spent its first turns finding out that the cause was a conflict. Most of those
+// conflicts were not conflicts at all to git: merging the default branch again resolved them.
+//
+// So the merge happens twice more, mechanically: once before the commit (`sync_stage`), and once when
+// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). Only a merge git
+// itself cannot finish stops the ship, and it stops as `conflict`, naming the unmerged paths so the
+// resumed session goes straight to them.
+
+const should_forward_stderr = true
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+// A default branch that keeps moving under a pull request is merged again at most this often per ship;
+// past it the followup failure stands, so a busy default branch cannot hold a ship in a loop.
+const MAX_MERGE_RETRIES = 2
+const CONFLICT_NOTE = 'merging the default branch left unmerged paths:'
+const DEFERRED_PREFIX = 'merge deferred to the followup: '
+const CURRENT_SUFFIX = ' brings nothing in'
+const MERGED_PREFIX = 'merged '
+
+// A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
+interface StepResult extends JoshResult {
+	conflicts?: ReadonlyArray<string>
+}
+
+async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(argv, should_forward_stderr)
+}
+
+// A merge that could not even be attempted — a fetch that failed — reads as a refusal: nothing was
+// changed, and the followup still finds a real conflict on GitHub's side.
+async function merge_outcome(): Promise<MergeOutcome> {
+	try {
+		return await main_merge.merge()
+	} catch (error) {
+		return { kind: 'refused', message: error_text.message_of(error) }
+	}
+}
+
+function conflict_result(files: ReadonlyArray<string>, lead: string): StepResult {
+	const out = [lead, CONFLICT_NOTE, ...files].filter((line) => line !== '').join('\n')
+
+	return { code: FAILURE_EXIT_CODE, out, conflicts: files }
+}
+
+function sync_note(outcome: Exclude<MergeOutcome, { kind: 'conflict' }>): string {
+	if (outcome.kind === 'refused') return `${DEFERRED_PREFIX}${outcome.message}`
+
+	return outcome.kind === 'current'
+		? `${outcome.branch}${CURRENT_SUFFIX}`
+		: `${MERGED_PREFIX}${outcome.branch}`
+}
+
+// A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
+// touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
+// the tree is checked by the gate stage that follows (joshuafolkken/kit#3307), so the commit never carries
+// an unchecked merge and the gate's record names the merge base the push carries.
+async function sync_stage(): Promise<StepResult> {
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
+
+	return { code: SUCCESS_EXIT_CODE, out: sync_note(outcome) }
+}
+
+// Any read that fails answers "not conflicting": the followup failure then stands as it was.
+async function is_conflicting(): Promise<boolean> {
+	try {
+		const state = await git_gh_pr_read.pr_get_merge_state(await git_command.branch())
+
+		return is_merge_conflict(state?.merge_state_status)
+	} catch {
+		return false
+	}
+}
+
+// The merged tree is gated before it is pushed (joshuafolkken/kit#3307): the push then carries the tree
+// the gate's record describes, so the pre-push hook reuses it rather than re-running the unit suite.
+async function push_merged(title: string): Promise<StepResult | undefined> {
+	const gate = await run_ship_scoped.scoped_gate()
+
+	if (gate.code !== SUCCESS_EXIT_CODE) return gate
+
+	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
+
+	return push.code === SUCCESS_EXIT_CODE ? undefined : push
+}
+
+// The result to stop on, or `undefined` once a clean merge is pushed and the followup can wait again.
+async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
+	if (!(await is_conflicting())) return failed
+
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, failed.out)
+	if (outcome.kind !== 'merged') return failed
+
+	return await push_merged(title)
+}
+
+async function followup_stage(
+	title: string,
+	notify: ReadonlyArray<string>,
+	retries = 0,
+): Promise<StepResult> {
+	const result = await josh(['followup', title, ...notify])
+
+	if (result.code === SUCCESS_EXIT_CODE || retries >= MAX_MERGE_RETRIES) return result
+
+	const stop = await merge_again(title, result)
+
+	return stop ?? (await followup_stage(title, notify, retries + 1))
+}
+
+const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
+
+export type { StepResult }
+export { run_ship_sync }

package/scripts/run/{run-ship.ts → ship/run-ship.ts}

@@ -10,8 +10,10 @@
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
 const PREFLIGHT_HEADER = '=== preflight ==='
+const PRE_DETACH_HEADER = '=== pre-detach checks ==='
 const REVIEW_HEADER = '=== review ==='
 const GATE_HEADER = '=== gate ==='
+const SYNC_HEADER = '=== sync origin/main ==='
 const COMMIT_HEADER = '=== commit/push/PR ==='
 const ROUND_TWO_HEADER = '=== round-2 review ==='
 const FOLLOWUP_HEADER = '=== followup ==='
@@ -29,6 +31,8 @@ interface ShipSection {
 	header: string
 	body: string
 	code: number
+	// The paths a stopped merge left unmerged (joshuafolkken/kit#3221), handed to the stop prompt.
+	conflicts?: ReadonlyArray<string>
 }
 
 function section_report(section: ShipSection): string {
@@ -65,10 +69,12 @@ const run_ship = {
 	FOLLOWUP_HEADER,
 	GATE_HEADER,
 	PREFLIGHT_HEADER,
+	PRE_DETACH_HEADER,
 	REPORT_HEADER,
 	REVIEW_HEADER,
 	ROUND_TWO_HEADER,
 	SKIPPED_BODY,
+	SYNC_HEADER,
 	STOPPED_PREFIX,
 	exit_code,
 	failed_section,

package/scripts/run/{run-tidy-lanes.ts → tidy/run-tidy-lanes.ts}

@@ -3,7 +3,7 @@ import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { error_text } from '#scripts/lib/error-message'
-import { run_hold } from './run-hold'
+import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
 
 // The lane half of `josh run:tidy` (joshuafolkken/kit#2701): each lane whose issue merged, read for