@joshuafolkken/kit 1.1166.0 → 1.1178.0

package/scripts/git/main-merge.ts

@@ -44,44 +44,79 @@ function merge_message(default_branch: string, current_branch: string): string |
 	return `Merge ${default_branch} into ${current_branch} #${issue_number}`
 }
 
-// The refusal is read after the fetch, so the incoming paths are the ones the merge would bring in
-// (joshuafolkken/kit#2445).
-async function merge_refusal(default_branch: string): Promise<string | undefined> {
-	const status = await git_command.status()
-	const incoming = await main_merge_guard.incoming_paths(default_branch)
-
-	return main_merge_guard.refusal(status, incoming, default_branch)
+// What one merge of the default branch came to (joshuafolkken/kit#3221). `josh ship` merges it again
+// before the commit and on a conflicting pull request, and branches on the answer rather than on an
+// exit code: `current` brought nothing in, so the tree is unchanged; `merged` changed it; `refused`
+// is the guard's answer, nothing attempted; `conflict` names the paths git left unmerged, so a resumed
+// session goes straight to them instead of asking git again.
+type MergeOutcome =
+	| { kind: 'current'; branch: string }
+	| { kind: 'merged'; branch: string }
+	| { kind: 'refused'; message: string }
+	| { kind: 'conflict'; files: ReadonlyArray<string> }
+
+interface MergeTarget {
+	default_branch: string
+	current_branch: string
+	is_current: boolean
 }
 
-// A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
-// the sanctioned commit rather than a request for `git add`.
-async function merge_with_hint(default_branch: string, message: string | undefined): Promise<void> {
+// A failure that left no unmerged path — a remote that cannot be reached, a hook that refused — is not
+// a conflict, so it is rethrown rather than reported as one with nothing to resolve.
+async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
+	const { default_branch, current_branch } = target
+
 	try {
-		await git_command.merge_branch(default_branch, message)
+		await git_command.merge_branch(default_branch, merge_message(default_branch, current_branch))
 	} catch (error) {
-		console.error(main_merge_guard.CONFLICT_HINT)
-		throw error
+		const files = main_merge_guard.unmerged_paths(await git_command.status())
+
+		if (files.length === 0) throw error
+
+		return { kind: 'conflict', files }
 	}
+
+	return { kind: target.is_current ? 'current' : 'merged', branch: default_branch }
 }
 
 // The fetch is what makes `origin/<default>` current before the merge reads it. `git pull` did the
-// two together, which is the only thing it was doing here that is worth keeping.
-async function merge_default_branch(): Promise<number> {
+// two together, which is the only thing it was doing here that is worth keeping. The refusal is read
+// after the fetch, so the incoming paths are the ones the merge would bring in (joshuafolkken/kit#2445).
+async function merge(): Promise<MergeOutcome> {
 	const default_branch = await git_command.get_default_branch()
 	const current_branch = await git_command.branch()
 
 	await git_command.fetch_branch(default_branch)
 
-	const refusal = await merge_refusal(default_branch)
+	const status = await git_command.status()
+	const incoming = await main_merge_guard.incoming_paths(default_branch)
+	const message = main_merge_guard.refusal(status, incoming, default_branch)
+
+	if (message !== undefined) return { kind: 'refused', message }
+
+	return await merge_into({ default_branch, current_branch, is_current: incoming.length === 0 })
+}
+
+// A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
+// the sanctioned commit rather than a request for `git add`.
+function failure_text(outcome: MergeOutcome): string | undefined {
+	if (outcome.kind === 'refused') return outcome.message
+	if (outcome.kind === 'conflict') return main_merge_guard.CONFLICT_HINT
+
+	return undefined
+}
+
+async function merge_default_branch(): Promise<number> {
+	const outcome = await merge()
+	const failure = failure_text(outcome)
 
-	if (refusal !== undefined) {
-		console.error(refusal)
+	if (failure !== undefined) {
+		console.error(failure)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	await merge_with_hint(default_branch, merge_message(default_branch, current_branch))
-	console.info(default_branch)
+	if ('branch' in outcome) console.info(outcome.branch)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -114,8 +149,9 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const main_merge = { run }
+const main_merge = { merge, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
 export { main_merge }
+export type { MergeOutcome }

package/scripts/git/schemas.ts

@@ -140,6 +140,8 @@ const open_issue_schema = z.object({
 	labels: z.array(issue_label_schema).optional(),
 	createdAt: z.string(),
 	blockedBy: blocked_by_schema,
+	// Present only on the pickup listing, which reads it for the restructures each issue declares.
+	body: z.string().optional(),
 })
 
 type RollupItemData = z.infer<typeof rollup_item_schema>

package/scripts/josh/josh-commands-development.ts

@@ -168,7 +168,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'test:red': {
 		script: 'scripts/test/test-red.ts',
 		description:
-			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test',
+			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test/test-only',
 		category: 'Development',
 		reference: ['', 'developer', ['git', 'processes']],
 	},

package/scripts/lane/lane-launch-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
+import { lane_registry } from '#scripts/lane/lane-registry'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
@@ -15,6 +16,7 @@ import { execa } from 'execa'
 // and messages are reused rather than cloned — `lane:open`'s cut-session guard and its `full` /
 // `already-open` refusals, `stash:pop`'s message-matched pop, `lane:dispatch`'s in-progress claim and
 // warning. Their explanations stream through to stderr; the child's pid is the one thing on stdout.
+// A lane a park kept is the one `already-open` it steps past — `lane_directory` below.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
@@ -86,14 +88,30 @@ type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } |
 const UNOPENED: LaunchOutcome = { kind: 'unopened' }
 const FAILED: LaunchOutcome = { kind: 'failed' }
 
+// **A lane a park kept open is resumed, not reopened** (joshuafolkken/kit#3228). A child parked before
+// its commit leaves its uncommitted work in its lane, and `lane:open` refuses that lane as
+// `already-open` — so the released child is dispatched into the kept tree instead. **Only a lane a
+// child was already dispatched into counts as kept**: `lane:dispatch` records the child's output in the
+// lane's `.env`, and a lane whose install failed never got that far, so it still goes through
+// `lane:open` and its refusal. So does a stranded lane, whose `.env` is gone with its tree.
+async function lane_directory(issue: string): Promise<string | undefined> {
+	const kept = await lane_registry.find_open_lane(issue)
+
+	if (kept?.output !== undefined) return kept.directory
+
+	const opened = await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
+
+	return opened.code === SUCCESS_EXIT_CODE ? opened.out : undefined
+}
+
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
 // chain (joshuafolkken/kit#2508).
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
-	const opened = await josh_command.josh_run(['lane:open', context.issue], should_forward_stderr)
+	const directory = await lane_directory(context.issue)
 
-	if (opened.code !== SUCCESS_EXIT_CODE) return UNOPENED
+	if (directory === undefined) return UNOPENED
 
-	if (!(await prepare(context.stash, opened.out))) return FAILED
+	if (!(await prepare(context.stash, directory))) return FAILED
 
 	const dispatched = await josh_command.josh_run(
 		['lane:dispatch', context.issue],

package/scripts/notify/telegram-notify.ts

@@ -3,6 +3,10 @@ import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
 
 const TELEGRAM_API_BASE = 'https://api.telegram.org'
+// `sendMessage` refuses a text longer than this.
+const TELEGRAM_TEXT_LIMIT = 4096
+const BODY_TRUNCATION_MARK = '\n...'
+const TRAILING_HIGH_SURROGATE = /[\uD800-\uDBFF]$/u
 
 const telegram_environment_schema = z.object({
 	telegram_bot_token: z.string().min(1, { message: 'TELEGRAM_BOT_TOKEN is required' }),
@@ -188,10 +192,31 @@ function build_blocks(input: TelegramSendInput): Array<string> {
 	return blocks
 }
 
-function build_text(input: TelegramSendInput): string {
+function join_blocks(input: TelegramSendInput): string {
 	return build_blocks(input).join('\n\n')
 }
 
+// A cut between the two halves of a surrogate pair leaves a lone surrogate, which is not valid
+// UTF-8 once encoded, so the half is dropped with the rest of the tail.
+function head_of(body: string, kept: number): string {
+	const head = body.slice(0, kept)
+
+	return TRAILING_HIGH_SURROGATE.test(head) ? head.slice(0, -1) : head
+}
+
+// **The body is cut to fit Telegram's length limit, keeping its head** (joshuafolkken/kit#3242). A
+// warning carrying a whole driver stderr ran past 4096 characters and was refused with `400 Bad
+// Request`, so it reached nobody. A caller puts the cause first, so the tail is what is dropped, and the
+// header and the URLs around the body survive.
+function build_text(input: TelegramSendInput): string {
+	const text = join_blocks(input)
+	const overflow = text.length - TELEGRAM_TEXT_LIMIT
+	if (overflow <= 0 || input.body === undefined) return text
+	const kept = Math.max(0, input.body.length - overflow - BODY_TRUNCATION_MARK.length)
+
+	return join_blocks({ ...input, body: `${head_of(input.body, kept)}${BODY_TRUNCATION_MARK}` })
+}
+
 async function post_message(config: TelegramConfig, text: string): Promise<void> {
 	const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`
 	const response = await timed_fetch(url, {

package/scripts/rules/pre-gate-cut.ts

@@ -100,7 +100,7 @@ interface LaneCutState {
 	directory: string
 	carried: (now?: Date) => RunCut | undefined
 	marked_issue: string | undefined
-	// **The recent-window context verdict, read lazily** (joshuafolkken/kit#2312). It is a thunk, like
+	// **The context verdict, read lazily** (joshuafolkken/kit#2312). It is a thunk, like
 	// `carried`, so `current_state` builds the object without pricing a session — the read happens only
 	// after the command and lane checks pass, off the handful of calls that actually run a lane's gate.
 	context_verdict: () => CostVerdict
@@ -136,7 +136,7 @@ function uncut_lane_issue(state: LaneCutState): string | undefined {
 	return state.carried()?.issue === issue ? undefined : issue
 }
 
-// **The cut is taken only when the recent-window context is worth its resume** (joshuafolkken/kit#2312).
+// **The cut is taken only when the current context is worth its resume** (joshuafolkken/kit#2312).
 // Below the shared `CONTEXT_CUT_THRESHOLD` a short lane has no accumulation a cut would drop, so the
 // gate runs uncut rather than paying for a relaunch; an unmeasurable session keeps the old
 // unconditional cut as the safety net joshuafolkken/kit#1933 relies on. The verdict is

package/scripts/run/run-carry.ts

@@ -480,15 +480,20 @@ function busy_message(carry: RunCarry): string {
 	return `A live run holds this budget — ${describe_carry(carry)}, owner pid ${String(carry.owner_pid)} still running. Nothing was established. Wait for that run, or end its record with \`${END_COMMAND}\` once you know it is over.`
 }
 
+// The adoption command, shared by the standing refusal and the judgment wake's hand-off.
+// **`--owner "$PPID"` is part of the command, not an optional extra.** An adoption made without it
+// leaves the record declaring no owner, and from then on every second parent reads it as not provably
+// live and is answered `standing` rather than `busy` — the ownership defense degrading silently
+// through the very message that recommends the command.
+function claim_command(invocation: string): string {
+	return `${RESUME_COMMAND} "${invocation}" ${OWNER_ARGUMENT}`
+}
+
 // The record's owner is gone and no cut handed it off — the crashed run, and the same command
 // retyped over it. Both ways out are named, because which one is right is the reader's to say and
 // not this command's to guess.
-// **`--owner "$PPID"` is part of the command it prints, not an optional extra.** An adoption made
-// without it leaves the record declaring no owner, and from then on every second parent reads it as
-// not provably live and is answered `standing` rather than `busy` — the ownership defense degrading
-// silently through the very message that recommends the command.
 function standing_message(carry: RunCarry): string {
-	return `A run record is standing here that no cut handed off — ${describe_carry(carry)}. Nothing was established. Carry that budget with \`${RESUME_COMMAND} "${carry.invocation}" ${OWNER_ARGUMENT}\`, or discard it with \`${END_COMMAND}\` and begin again.`
+	return `A run record is standing here that no cut handed off — ${describe_carry(carry)}. Nothing was established. Carry that budget with \`${claim_command(carry.invocation)}\`, or discard it with \`${END_COMMAND}\` and begin again.`
 }
 
 // The count refusal reads differently by cause: a record awaiting its successor, or one a successor
@@ -535,6 +540,7 @@ const run_carry = {
 	begin_carry,
 	busy_message,
 	carry_path,
+	claim_command,
 	classify,
 	classify_claim,
 	count_refused_message,

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

@@ -60,7 +60,7 @@ const {
 } = run_cut_report
 
 // **The pre-gate cut is conditional on the same statistic the implementation-phase cut reads**
-// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the recent `RECENT_REQUEST_WINDOW`
+// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the newest request
 // against `CONTEXT_CUT_THRESHOLD`, so no second threshold is introduced — an `under` session skips the
 // cut, and an unmeasurable one keeps the old unconditional cut as the safety net joshuafolkken/kit#1933
 // relies on. Only the pre-gate phase is checked here; the implementation-phase caller gates its own

package/scripts/run/run-cut-report.ts

@@ -14,7 +14,7 @@ const RESUME_VERDICT = 'resume'
 // re-reading the record.
 const RESUME_IMPL_VERDICT = 'resume-impl'
 const FRESH_VERDICT = 'fresh'
-// The recent-window context is under the shared cut threshold, so the pre-gate cut was not worth its
+// The current context is under the shared cut threshold, so the pre-gate cut was not worth its
 // resume and nothing was cut (joshuafolkken/kit#2312). A benign, non-failing answer: the run carries
 // on to the gate itself, exactly as `not-a-lane` does.
 const UNDER_THRESHOLD_VERDICT = 'under-threshold'
@@ -111,7 +111,7 @@ function refuse_unready(state: CutState): number {
 // relaunch costs more than it saves; the current process carries the run on to the gate uncut.
 function report_under_threshold(): number {
 	console.error(
-		'The recent-window context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
+		'The current context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
 	)
 
 	return report(UNDER_THRESHOLD_VERDICT, SUCCESS_EXIT_CODE)

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

@@ -7,6 +7,7 @@ import { run_event_stream_emit } from './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-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/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-return.ts

@@ -6,7 +6,7 @@ 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 type { ShipResume } from './run-ship-next'
-import type { Stage } from './run-ship-stage'
+import { run_ship_stage, type Stage } from './run-ship-stage'
 
 // 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 +28,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 `#${issue} ${run_ship_stage.stop_reason(stage, resume.conflicts)} failed — pnpm josh ship --log ${issue}`
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
@@ -53,7 +53,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-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

@@ -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
@@ -56,6 +57,13 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 				async () => await josh(['gate']),
 			]),
 	},
+	// joshuafolkken/kit#3221: the default branch merged again right before the commit, so the pull
+	// request opens on a branch that is current; a clean merge goes on without waking anyone.
+	{
+		stage: STAGE.SYNC,
+		header: run_ship.SYNC_HEADER,
+		run: async () => await run_ship_sync.sync_stage(),
+	},
 	{
 		stage: STAGE.COMMIT,
 		header: run_ship.COMMIT_HEADER,
@@ -69,7 +77,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,