@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/run/run-prrun-resume.ts

@@ -0,0 +1,117 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { PullMergeState } from '#scripts/gh/git-gh-pr-read'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { run_halfrun_resume, type StopMark } from './run-halfrun-resume'
+import { run_hold, type HoldRead } from './run-hold'
+
+// joshuafolkken/kit#3023: a `prrun` stops at a green, mergeable pull request and **keeps** its hold, so
+// a person can look before anything merges. What comes next is one of three, and `run:entry` answers
+// which as the resume token `fullrun #N` acts on — read, never inferred:
+//
+// - `prrun-merged` — the person merged it by hand. Only `followup`'s tail is left.
+// - `prrun-merge` — the branch is where the stop left it, both here and on the pull request, and the
+//   tree is clean. What was verified is what would merge, so `followup` merges without the gate and
+//   the review again.
+// - `prrun-gate` — the branch moved since the stop, or the tree is dirty: a person changed something,
+//   so the gate and the review run again before `followup`. **The pull request's own head is asked
+//   too**: a commit pushed on GitHub (a suggestion applied, "Update branch") moves only the remote,
+//   and `followup` merges the remote — an unread or moved one is never taken as untouched.
+//
+// **Only a marked record is adopted**, as for the `halfrun` stop (`run-halfrun-resume.ts`): the stop
+// writes the commit it stopped on (`run:hold <N> --prrun-stop`), and a hold without it is a run still
+// working, never one waiting for a person.
+
+const PRRUN_MERGED = 'prrun-merged'
+const PRRUN_MERGE = 'prrun-merge'
+const PRRUN_GATE = 'prrun-gate'
+
+type PrrunToken = typeof PRRUN_GATE | typeof PRRUN_MERGE | typeof PRRUN_MERGED
+
+interface ResumeFacts {
+	is_merged: boolean
+	stop_head: string
+	head: string
+	// The commit the pull request's head is on, or `undefined` when it could not be read.
+	pr_head: string | undefined
+	is_dirty: boolean
+}
+
+function is_untouched(facts: ResumeFacts): boolean {
+	return facts.head === facts.stop_head && facts.pr_head === facts.stop_head && !facts.is_dirty
+}
+
+function decide(facts: ResumeFacts): PrrunToken {
+	if (facts.is_merged) return PRRUN_MERGED
+
+	return is_untouched(facts) ? PRRUN_MERGE : PRRUN_GATE
+}
+
+function stop_head_of(read: HoldRead, issue: string): string | undefined {
+	const hold = run_halfrun_resume.hold_of(read)
+
+	return hold?.issue === issue ? hold.prrun_stop_head : undefined
+}
+
+async function read_merge_state(): Promise<PullMergeState | undefined> {
+	return await git_gh_command.pr_get_merge_state(await git_branch.current())
+}
+
+async function read_facts(stop_head: string): Promise<ResumeFacts> {
+	const [state, head, is_dirty] = await Promise.all([
+		read_merge_state(),
+		git_command.head_commit(),
+		run_hold.is_tree_dirty(),
+	])
+
+	return {
+		is_merged: state?.is_merged === true,
+		stop_head,
+		head,
+		pr_head: state?.head_sha,
+		is_dirty,
+	}
+}
+
+// Read-only, so `run:entry` can ask the session budget before it takes anything over. `undefined` is
+// "no `prrun` stop for this issue here", and the ordinary claim decides the tree as before.
+async function resume_token(issue: string): Promise<PrrunToken | undefined> {
+	const target = await run_halfrun_resume.hold_target()
+
+	if (target === undefined) return undefined
+
+	const stop_head = stop_head_of(run_hold.read_hold(target), issue)
+
+	return stop_head === undefined ? undefined : decide(await read_facts(stop_head))
+}
+
+async function adopt(issue: string): Promise<boolean> {
+	const target = await run_halfrun_resume.hold_target()
+
+	if (target === undefined || stop_head_of(run_hold.read_hold(target), issue) === undefined) {
+		return false
+	}
+
+	return run_halfrun_resume.take_over(target, issue)
+}
+
+// The `--prrun-stop` mark: the run's own record re-written with the commit the pull request is on.
+async function mark_stop_at(target: string, issue: string): Promise<StopMark> {
+	const head = await git_command.head_commit()
+
+	return run_halfrun_resume.mark_stop_at(target, issue, { prrun_stop_head: head })
+}
+
+const run_prrun_resume = {
+	PRRUN_GATE,
+	PRRUN_MERGE,
+	PRRUN_MERGED,
+	adopt,
+	decide,
+	mark_stop_at,
+	resume_token,
+	stop_head_of,
+}
+
+export type { PrrunToken, ResumeFacts }
+export { run_prrun_resume }

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { git_followup_pending } from '#scripts/git/git-followup-pending'
+import { git_followup_pending } from '#scripts/followup/git-followup-pending'
 import { release_scope_cli } from '#scripts/release/release-scope-cli'
 import { run_carry } from './run-carry'
 import { run_event_scope, type EventScope } from './run-event-scope'
@@ -62,7 +62,6 @@ async function main(): Promise<void> {
 }
 
 const run_report_cli = {
-	main,
 	run,
 }
 

package/scripts/run/run-report.ts

@@ -71,7 +71,6 @@ function build_report(input: ReportInput): string {
 const run_report = {
 	UNKNOWN_SCOPE_NOTICE,
 	build_report,
-	release_tail,
 }
 
 export type { ReportInput }

package/scripts/run/run-retrospective.ts

@@ -28,7 +28,7 @@ function is_owed(facts: RetrospectiveFacts): boolean {
 	return !facts.is_lane_child && !facts.is_retrospective_done && !facts.is_consumer
 }
 
-const run_retrospective = { RETROSPECTIVE_ENV_KEY, is_enabled, is_owed }
+const run_retrospective = { is_enabled, is_owed }
 
 export type { RetrospectiveFacts }
 export { run_retrospective }

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

@@ -118,10 +118,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_review_cli = {
-	JOIN_FLAG,
-	USAGE,
 	join_exit_code,
-	main,
 	run,
 }
 

package/scripts/run/run-review-steps.ts

@@ -94,7 +94,9 @@ async function wait_for_gate_finish(now: Clock = () => Date.now()): Promise<Gate
 	let state = await read_gate_state()
 
 	while (!run_review.is_gate_settled(state) && now() - started < MAX_JOIN_WAIT_MS) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_INTERVAL_MS)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		state = await read_gate_state()
 	}
 

package/scripts/run/run-review.ts

@@ -105,12 +105,10 @@ const run_review = {
 	GATE_RED,
 	GATE_RUNNING,
 	adopt_verdict,
-	format_seconds,
 	format_timing,
 	gate_state,
 	is_gate_settled,
 	overlap_seconds,
-	span_seconds,
 }
 
 export type { AdoptVerdict, GateState, ReviewTiming, TimingStart }

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

@@ -1,16 +1,16 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
-import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { run_event_stream } from './run-event-stream'
 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_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
-import { run_ship_review_steps } from './run-ship-review-steps'
 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'
 
 // `josh ship "<title> #<N>"` — one call for the fixed commit-to-report region a run ships a change on
 // (joshuafolkken/kit#2398). The loop used to spend a round trip each on `gate`, `git -y`, `followup`
@@ -67,7 +67,6 @@ const USAGE =
 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'
-const should_forward_stderr = true
 
 type NotifyValues = Partial<Record<(typeof NOTIFY_OPTIONS)[number], string>>
 
@@ -84,24 +83,8 @@ const OPTIONS = {
 	cite: { type: 'string', multiple: true },
 } as const
 
-interface ShipArguments {
-	title: string
-	number: string
-	notify: ReadonlyArray<string>
-	body: ReadonlyArray<string>
-	cites: ReadonlyArray<string>
-	is_review: boolean
-	is_detach: boolean
-}
-
 type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number: string }
 
-interface Step {
-	stage: Stage
-	header: string
-	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
-}
-
 // What a resumed ship knows before its first stage: the record's path (absent outside a repository),
 // the stages it says completed, and the repository's actual state (`run-ship-stage.ts` decides from it).
 interface ShipContext {
@@ -124,58 +107,7 @@ function body_arguments(path: string | undefined): ReadonlyArray<string> {
 	return path === undefined ? [] : [`--${BODY_FILE_OPTION}`, path]
 }
 
-const { STAGE, PHASE } = run_ship_stage
-
-// The four steps in the order a change ships: the gate before the commit, the commit/push/PR before
-// the merge, the merge before the report bookkeeping. The commit step carries the `--skip-*` flags a
-// resumed ship needs, so an existing commit or push is never made twice.
-async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
-	return await josh_command.josh_run(argv, should_forward_stderr)
-}
-
-const COMMIT_STEPS: ReadonlyArray<Step> = [
-	{ stage: STAGE.GATE, header: run_ship.GATE_HEADER, run: async () => await josh(['gate']) },
-	{
-		stage: STAGE.COMMIT,
-		header: run_ship.COMMIT_HEADER,
-		run: async (args, state) =>
-			await josh(['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]),
-	},
-]
-
-const MERGE_STEPS: ReadonlyArray<Step> = [
-	{
-		stage: STAGE.FOLLOWUP,
-		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await josh(['followup', args.title, ...args.notify]),
-	},
-	{
-		stage: STAGE.REPORT,
-		header: run_ship.REPORT_HEADER,
-		run: async (args) => await josh(['run:tail', args.number, ...args.cites]),
-	},
-]
-
-// `--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
-// 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 = {
-	stage: STAGE.REVIEW,
-	header: run_ship.REVIEW_HEADER,
-	run: async (args) => await run_ship_review_steps.review_stage(args.number),
-}
-const ROUND_TWO_STEP: Step = {
-	stage: STAGE.ROUND_TWO,
-	header: run_ship.ROUND_TWO_HEADER,
-	run: async (args) => await run_ship_review_steps.round_two_stage(args.number),
-}
-
-function steps(args: ShipArguments): ReadonlyArray<Step> {
-	if (!args.is_review) return [...COMMIT_STEPS, ...MERGE_STEPS]
-
-	return [REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
-}
+const { PHASE } = run_ship_stage
 
 function issue_number(title: string): string | undefined {
 	return TRAILING_ISSUE_PATTERN.exec(title)?.[NUMBER_GROUP]
@@ -211,6 +143,7 @@ function ship_args(
 		number,
 		notify: notify_arguments(values),
 		body: body_arguments(values[BODY_FILE_OPTION]),
+		body_path: values[BODY_FILE_OPTION],
 		cites,
 		is_review: values.review === true,
 		is_detach: values.detach === true,
@@ -323,23 +256,27 @@ async function stopped(
 	args: ShipArguments,
 	stage: Stage,
 ): Promise<ReadonlyArray<ShipSection>> {
-	if (run_ship_detach.is_supervised()) await run_ship_return.return_control(args.number, stage)
+	if (run_ship_detach.is_supervised()) {
+		await run_ship_return.return_control(args.number, stage, run_ship_next.resume_of(args))
+	}
 
 	return sections
 }
 
-// Run the four in order, stopping at the first that failed: a red gate never reaches the commit, so
+// 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 gate.
+// record, so the next ship of the same issue starts from the preflight.
 async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const context = await open_context(args)
 	const sections: Array<ShipSection> = []
 
-	for (const step of steps(args)) {
+	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)
 
+		// 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.stage)
 	}
 
@@ -392,6 +329,19 @@ function should_detach(args: ShipArguments): boolean {
 	return !run_ship_detach.is_supervised() && lane_child_marker.is_child_of(process.cwd())
 }
 
+// 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.
+async function detach_after_preflight(args: ShipArguments): Promise<number> {
+	const section = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
+
+	if (section.code === SUCCESS_EXIT_CODE) return await detach(args)
+
+	console.info(run_ship.format_report([section]))
+
+	return run_ship.exit_code([section])
+}
+
 async function supervised_repository(): Promise<string | undefined> {
 	return run_ship_detach.is_supervised() ? await run_ship_probe.repository_directory() : undefined
 }
@@ -414,7 +364,7 @@ async function run_ship_command(args: ShipArguments): Promise<number> {
 	if (should_detach(args)) {
 		if (!args.is_detach) console.error(LANE_CHILD_DETACH_NOTE)
 
-		return await detach(args)
+		return await detach_after_preflight(args)
 	}
 
 	await claim_supervised_identity(args)
@@ -444,7 +394,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_ship_cli = { SUCCESS_EXIT_CODE, USAGE, main, parse, run, ship }
+const run_ship_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

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

@@ -195,6 +195,7 @@ async function ready_record(repository: string, number: string): Promise<ShipRec
 	for (let attempt = 0; attempt < RECORD_WAIT_ATTEMPTS; attempt += 1) {
 		if (!is_pending(record)) return record
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(RECORD_POLL_MS)
 		record = current_record(repository, number)
 	}

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

@@ -0,0 +1,106 @@
+import { run_ship_stage, type Stage } from './run-ship-stage'
+import type { ShipArguments } from './run-ship-steps'
+
+// The command a relaunched lane child runs once it has fixed what stopped its detached ship
+// (joshuafolkken/kit#2964). The ship-stop prompt used to say only "hand the region back per
+// chain-rule.md", so every relaunched session searched that document and re-derived the next command
+// — 179 reads of it in one run. The stopped stage decides the command mechanically, so it is decided
+// here, once, and the prompt carries it. `chain-rule.md` step 0 stays the single source of the
+// procedure; `ship-stop-prompt-document-rule.test.ts` holds every command below to it.
+//
+// The fix is left uncommitted on purpose: a dirty tree reads as not committed
+// (`run-ship-probe.ts`), so a re-detached ship runs the gate and the commit again on the fixed tree
+// instead of passing over them.
+//
+// **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.
+//
+// **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
+// the title would stop on the same evidence again, and drop the `--cite` follow-ups `run:tail` reads.
+
+const { STAGE } = run_ship_stage
+
+const COMMAND = {
+	LOG: 'pnpm josh ship --log',
+	DETACH: 'pnpm josh ship --detach',
+	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
+}
+
+// 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)
+}
+
+// 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.
+function resume_of(args: ShipArguments): ShipResume {
+	const cites = args.cites.flatMap((cite) => ['--cite', cite])
+
+	return {
+		title: args.title,
+		flags: [...args.notify, ...args.body, ...cites],
+		is_review: args.is_review,
+	}
+}
+
+// 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))
+
+	return [command, ...words].join(' ')
+}
+
+// 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
+// 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
+
+	return `leave the fix uncommitted and run \`${ship_command(command, resume)}\`.`
+}
+
+const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
+	[STAGE.PREFLIGHT]: detach_as_started,
+	[STAGE.REVIEW]: detach_as_started,
+	[STAGE.GATE]: detach_as_started,
+	[STAGE.COMMIT]: detach_as_started,
+	[STAGE.ROUND_TWO]: detach_again,
+	[STAGE.FOLLOWUP]: detach_again,
+	[STAGE.REPORT]: detach_again,
+}
+
+// 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 {
+	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure, then ${AFTER_FIX[stage](resume)}`
+}
+
+const run_ship_next = { COMMAND, next_step, quoted, resume_of }
+
+export { run_ship_next, type ShipResume }

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

@@ -0,0 +1,87 @@
+import { readFile } from 'node:fs/promises'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_branch } from '#scripts/git/git-branch'
+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_scoped } from './run-ship-scoped'
+
+// `josh ship`'s first stage (joshuafolkken/kit#2946). A detached ship used to meet the pull request's
+// preconditions only at the commit stage — `git -y`'s preflight — or at the merge — `followup`'s
+// live-evidence refusal — each after the review and the gate had already run, so every such stop
+// relaunched a session to repeat them. **Every precondition decidable before the review is asked here,
+// and all of them are reported at once.** No check is new: the classification, issue and branch answers
+// are `git_preflight.problems_of`, and the evidence answer is `live_evidence.verdict_for` over the same
+// changed paths and the body this ship will deliver — `--body-file` when given, else the open PR's.
+//
+// The scoped pair runs last, met rather than stopped on (`run-ship-scoped.ts`), so the review and the
+// gate start on a tree both checks are green on.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const EVIDENCE_PROBLEM = `This change touches runtime code, but the PR body has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and pass the body with --body-file <path>.`
+
+interface PreflightRequest {
+	title: string
+	body_path: string | undefined
+}
+
+async function body_text(body_path: string | undefined): Promise<string | undefined> {
+	if (body_path !== undefined) return await readFile(body_path, 'utf8')
+
+	return await git_gh_command.pr_get_body(await git_branch.current())
+}
+
+async function evidence_problems(body_path: string | undefined): Promise<Array<string>> {
+	const [paths, body] = await Promise.all([
+		changed_paths.read_changed_paths(false),
+		body_text(body_path),
+	])
+
+	return live_evidence.verdict_for(paths, body) === 'required' ? [EVIDENCE_PROBLEM] : []
+}
+
+function refusal(problems: ReadonlyArray<string>): JoshResult {
+	const lines = problems.map((problem) => `  - ${problem}`)
+	const head = `${String(problems.length)} pull-request precondition(s) unmet before the review and the gate:`
+
+	return { code: FAILURE_EXIT_CODE, out: [head, ...lines].join('\n') }
+}
+
+// The reads here run in the ship's own process, where the commit stage's ran in a `git -y` child: a
+// throw — a `--body-file` path that does not exist, a git read that failed — would escape `ship()`
+// past the stop a supervised ship hands back on, so it is reported as one more unmet precondition.
+// Each side is caught on its own, so one side's failed read never hides what the other side found.
+async function caught(problems: Promise<Array<string>>): Promise<Array<string>> {
+	try {
+		return await problems
+	} catch (error) {
+		return [error_text.message_of(error)]
+	}
+}
+
+async function asked_problems(request: PreflightRequest): Promise<Array<string>> {
+	const [preflight, evidence] = await Promise.all([
+		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
+		caught(evidence_problems(request.body_path)),
+	])
+
+	return [...preflight, ...evidence]
+}
+
+async function stage(request: PreflightRequest): Promise<JoshResult> {
+	const problems = await asked_problems(request)
+
+	if (problems.length > 0) return refusal(problems)
+
+	const scoped = await run_ship_scoped.scoped_pair()
+
+	return scoped.code === SUCCESS_EXIT_CODE ? { code: SUCCESS_EXIT_CODE, out: 'ready' } : scoped
+}
+
+const run_ship_preflight = { EVIDENCE_PROBLEM, stage }
+
+export type { PreflightRequest }
+export { run_ship_preflight }

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

@@ -5,6 +5,7 @@ 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 type { ShipResume } from './run-ship-next'
 import type { Stage } from './run-ship-stage'
 
 // How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
@@ -47,14 +48,18 @@ function note(text: string): void {
 	process.stderr.write(`${text}\n`)
 }
 
-async function return_control(issue: string, stage: Stage): Promise<ReturnOutcome> {
+async function return_control(
+	issue: string,
+	stage: Stage,
+	resume: ShipResume,
+): Promise<ReturnOutcome> {
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STOP, stop_text(issue, stage))
 
 	const lane = await lane_to_relaunch(issue)
 
 	if (lane === undefined) return 'recorded'
 
-	const invocation = lane_child_invocation.ship_stop_invocation(issue)
+	const invocation = lane_child_invocation.ship_stop_invocation(issue, { stage, ...resume })
 	const result = lane_relaunch.relaunch(
 		lane,
 		invocation,
@@ -69,7 +74,7 @@ async function return_control(issue: string, stage: Stage): Promise<ReturnOutcom
 	return 'recorded'
 }
 
-const run_ship_return = { return_control, stop_text }
+const run_ship_return = { return_control }
 
 export type { ReturnOutcome }
 export { run_ship_return }