@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -3,10 +3,16 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_pr } from '#scripts/gh/git-pr'
 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 { git_issue } from '#scripts/git/git-issue'
+import { git_preflight, type Unmet } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
+import { report_format_reference } from '#scripts/report/report-format-reference'
+import { acceptance_map } from '#scripts/review/acceptance-map'
+import { acceptance_map_check } from '#scripts/review/acceptance-map-check'
 import { live_evidence } from '#scripts/review/live-evidence'
+import { removed_tests_check } from '#scripts/review/removed-tests-check'
+import { run_ship_body_draft } from './run-ship-body-draft'
 import { run_ship_lock } from './run-ship-lock'
 import { run_ship_scoped } from './run-ship-scoped'
 
@@ -15,25 +21,58 @@ import { run_ship_scoped } from './run-ship-scoped'
 // **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.
+// changed paths and the body this ship will deliver — `--body-file` when given, else the ship body
+// draft, 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.
+//
+// A stop names the kinds of the preconditions it found unmet, beside the git preflight's own, so the
+// lane ledger can count which one stops ships (joshuafolkken/kit#4166).
 
 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>. Write it ${live_evidence.EVIDENCE_FORMAT}`
-const EVIDENCE_PENDING = `This change touches runtime code and no PR is open yet: write the ${live_evidence.EVIDENCE_HEADING} section to a file and hand it to josh ship with --body-file <path>, or the ship refuses. Write it ${live_evidence.EVIDENCE_FORMAT}`
+const UNREADABLE = Symbol('unreadable body')
+const PRECONDITION = {
+	LIVE_EVIDENCE: 'live-evidence',
+	ACCEPTANCE_MAP: 'acceptance-map',
+	REMOVED_TESTS: 'removed-tests',
+	LOCK: 'lock',
+	SCOPED: 'scoped',
+	UNREADABLE: 'unreadable',
+} as const
+const EVIDENCE_PROBLEM = `This change touches runtime code, but the body this ship delivers has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and write it into the ship body draft run:prep wrote (josh ship reads it when --body-file is omitted), or pass the body with --body-file <path>. Write it ${live_evidence.EVIDENCE_FORMAT}`
+const EVIDENCE_PENDING = `This change touches runtime code and no PR is open yet: write the ${live_evidence.EVIDENCE_HEADING} section into the ship body draft run:prep wrote (or a file handed to josh ship with --body-file <path>), or the ship refuses. Write it ${live_evidence.EVIDENCE_FORMAT}`
+
+// The draft `josh ship` reads when `--body-file` is omitted, named so the run fills that file in.
+function acceptance_pending_text(draft_path: string): string {
+	return `Fill in this ${acceptance_map.MAP_HEADING} section in the ship body draft ${draft_path} — josh ship reads it when --body-file is omitted — replacing each pending row's ending with what met or deferred it (format: ${report_format_reference.pointer(report_format_reference.ACCEPTANCE_MAP_HEADING)}), and write ${live_evidence.EVIDENCE_HEADING} there before the ship, or the ship refuses:`
+}
 
 interface PreflightRequest {
 	title: string
 	body_path: string | undefined
 }
 
+// `preconditions` names the kinds a stopped stage found unmet, each once, in the order they were asked.
+interface PreflightResult extends JoshResult {
+	preconditions?: ReadonlyArray<string>
+}
+
+// The body the next ship delivers: `--body-file`, else the run's ship body draft, else the open PR's.
 async function body_text(body_path: string | undefined): Promise<string | undefined> {
 	if (body_path !== undefined) return await readFile(body_path, 'utf8')
+	const branch = await git_branch.current()
+	const issue = git_issue.branch_number(branch)
+	const draft = issue === undefined ? undefined : await run_ship_body_draft.existing(issue)
+
+	if (draft !== undefined) return await readFile(draft, 'utf8')
 
-	return await git_gh_command.pr_get_body(await git_branch.current())
+	return await git_gh_command.pr_get_body(branch)
+}
+
+function of_kind(kind: string, problems: ReadonlyArray<string>): Array<Unmet> {
+	return problems.map((problem) => ({ kind, problem }))
 }
 
 // `no_body_problem` answers a runtime change with no body to read at all — no `--body-file` and no open
@@ -41,7 +80,7 @@ async function body_text(body_path: string | undefined): Promise<string | undefi
 async function evidence_problems(
 	body_path: string | undefined,
 	no_body_problem: string = EVIDENCE_PROBLEM,
-): Promise<Array<string>> {
+): Promise<Array<Unmet>> {
 	const [paths, body] = await Promise.all([
 		changed_paths.read_changed_paths(false),
 		body_text(body_path),
@@ -49,73 +88,165 @@ async function evidence_problems(
 
 	if (live_evidence.verdict_for(paths, body) !== 'required') return []
 
-	return [body === undefined ? no_body_problem : EVIDENCE_PROBLEM]
+	return of_kind(PRECONDITION.LIVE_EVIDENCE, [
+		body === undefined ? no_body_problem : EVIDENCE_PROBLEM,
+	])
 }
 
-function refusal(problems: ReadonlyArray<string>): JoshResult {
-	const lines = problems.map((problem) => `  - ${problem}`)
+function refusal(problems: ReadonlyArray<Unmet>): PreflightResult {
+	const lines = problems.map(({ problem }) => `  - ${problem}`)
 	const head = `${String(problems.length)} pull-request precondition(s) unmet before the review and the gate:`
+	const preconditions = [...new Set(problems.map(({ kind }) => kind))]
 
-	return { code: FAILURE_EXIT_CODE, out: [head, ...lines].join('\n') }
+	return { code: FAILURE_EXIT_CODE, out: [head, ...lines].join('\n'), preconditions }
 }
 
 // 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>> {
+async function caught(problems: Promise<Array<Unmet>>): Promise<Array<Unmet>> {
 	try {
 		return await problems
 	} catch (error) {
-		return [error_text.message_of(error)]
+		return of_kind(PRECONDITION.UNREADABLE, [error_text.message_of(error)])
+	}
+}
+
+async function readable_body(
+	body_path: string | undefined,
+): Promise<string | undefined | typeof UNREADABLE> {
+	try {
+		return await body_text(body_path)
+	} catch {
+		return UNREADABLE
 	}
 }
 
+// `followup`'s acceptance-map refusal, asked of the body this ship will deliver. A branch with no issue
+// number is `git_preflight`'s problem to name, and an unreadable body the evidence side's.
+async function acceptance_problems(body_path: string | undefined): Promise<Array<Unmet>> {
+	const issue = git_issue.branch_number(await git_branch.current())
+	const body = await readable_body(body_path)
+
+	if (issue === undefined || body === UNREADABLE) return []
+	const problem = await acceptance_map_check.body_refusal(issue, body)
+
+	return problem === undefined ? [] : of_kind(PRECONDITION.ACCEPTANCE_MAP, [problem])
+}
+
+// `followup`'s removed-test refusal, asked of the body this ship will deliver.
+async function removed_test_problems(body_path: string | undefined): Promise<Array<Unmet>> {
+	const body = await readable_body(body_path)
+
+	if (body === UNREADABLE) return []
+	const problem = await removed_tests_check.body_refusal(body)
+
+	return problem === undefined ? [] : of_kind(PRECONDITION.REMOVED_TESTS, [problem])
+}
+
+async function lock_problems(): Promise<Array<Unmet>> {
+	return of_kind(PRECONDITION.LOCK, await run_ship_lock.lock_problems())
+}
+
 // The lock file is asked here too, 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, lock] = await Promise.all([
+async function asked_problems(request: PreflightRequest): Promise<Array<Unmet>> {
+	const [preflight, evidence, acceptance, removed, 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()),
+		caught(acceptance_problems(request.body_path)),
+		caught(removed_test_problems(request.body_path)),
+		caught(lock_problems()),
 	])
 
-	return [...preflight, ...evidence, ...lock]
+	return [...preflight, ...evidence, ...acceptance, ...removed, ...lock]
 }
 
-async function stage(request: PreflightRequest): Promise<JoshResult> {
+async function stage(request: PreflightRequest): Promise<PreflightResult> {
 	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
+	if (scoped.code === SUCCESS_EXIT_CODE) return { code: SUCCESS_EXIT_CODE, out: 'ready' }
+
+	return { ...scoped, preconditions: [PRECONDITION.SCOPED] }
 }
 
-async function classification_problems(issue_number: string): Promise<Array<string>> {
+async function classification_problems(issue_number: string): Promise<Array<Unmet>> {
 	await git_pr.release_classification(issue_number, await git_branch.current())
 
 	return []
 }
 
-// **The same two refusals, asked before the ship rather than by it**: a missing
-// classification or missing evidence is known long before the ship, yet refused there at the run's
-// largest context. `run:prep` (and so `run:entry`)
-// and `run:step` print this, so the Issue body and the evidence are met while they are cheap. Nothing
-// here replaces `stage`: the ship and `followup` still refuse on both. Before the PR exists the evidence
-// can only live in the file the ship will be handed, so it is asked for as that file, not reported as a
-// body that already failed.
+// Only a body still to be written is handed every row as pending: a draft or an open PR's body keeps
+// the refusal, which names just the rows missing, stale or deferred to an issue that does not exist.
+async function pending_map(
+	issue_number: string,
+	body: string | undefined,
+): Promise<string | undefined> {
+	if (body !== undefined) return undefined
+
+	return acceptance_map.skeleton(await git_gh_command.issue_get_body(issue_number))
+}
+
+// The rows land in the ship body draft as well as in the report (joshuafolkken/kit#4168).
+async function pending_text(issue_number: string, map: string): Promise<string> {
+	const draft = await run_ship_body_draft.prepare(issue_number, map)
+
+	return `${acceptance_pending_text(draft)}\n${map}`
+}
+
+// A refusal of a draft already written names it again, so a later `run:step` still points at the file.
+async function draft_refusal_text(issue_number: string, problem: string): Promise<string> {
+	const draft = await run_ship_body_draft.existing(issue_number)
+
+	return draft === undefined ? problem : `${acceptance_pending_text(draft)}\n${problem}`
+}
+
+// The acceptance-map refusal asked early carries the rows to write, identifiers included, built by
+// `acceptance_map.skeleton` — the one builder `josh pr` uses too (joshuafolkken/kit#4244). An Issue
+// with no criteria to build rows from keeps the refusal's own wording.
+async function acceptance_pending(issue_number: string): Promise<Array<Unmet>> {
+	const body = await body_text(undefined)
+	const problem = await acceptance_map_check.body_refusal(issue_number, body)
+
+	if (problem === undefined) return []
+	const map = await pending_map(issue_number, body)
+	const pending =
+		map === undefined
+			? await draft_refusal_text(issue_number, problem)
+			: await pending_text(issue_number, map)
+
+	return of_kind(PRECONDITION.ACCEPTANCE_MAP, [pending])
+}
+
+// **The same refusals, asked before the ship rather than by it**: a missing classification, missing
+// evidence or an unmapped acceptance criterion is known long before the ship, yet refused there at the
+// run's largest context. `run:prep` (and so `run:entry`)
+// and `run:step` print this, so the Issue body and the PR body are met while they are cheap. Nothing
+// here replaces `stage`: the ship and `followup` still refuse on all of them. Before the PR exists the
+// evidence can only live in the file the ship will be handed, so it is asked for as that file, not
+// reported as a body that already failed.
 async function ahead(issue_number: string): Promise<Array<string>> {
-	const [classification, evidence] = await Promise.all([
+	const [classification, evidence, acceptance] = await Promise.all([
 		caught(classification_problems(issue_number)),
 		caught(evidence_problems(undefined, EVIDENCE_PENDING)),
+		caught(acceptance_pending(issue_number)),
 	])
 
-	return [...classification, ...evidence]
+	return [...classification, ...evidence, ...acceptance].map(({ problem }) => problem)
 }
 
-const run_ship_preflight = { EVIDENCE_PENDING, EVIDENCE_PROBLEM, ahead, stage }
+const run_ship_preflight = {
+	EVIDENCE_PENDING,
+	EVIDENCE_PROBLEM,
+	acceptance_pending_text,
+	ahead,
+	stage,
+}
 
-export type { PreflightRequest }
+export type { PreflightRequest, PreflightResult }
 export { run_ship_preflight }

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

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_preflight } from '#scripts/run/run-preflight'
@@ -60,16 +61,23 @@ async function read_merged(branch_name: string): Promise<boolean> {
 	return (await git_command.commit_count_beyond(base, HEAD_REFERENCE)) === 0
 }
 
+// The issue changed after the recorded review was briefed — the refusal `josh followup` would make
+// (joshuafolkken/kit#4221) — so the review stage re-runs instead of the followup failing again.
+async function read_review_stale(): Promise<boolean> {
+	return await or_false(async () => (await issue_watch_gate.review_refusal_here()) !== undefined)
+}
+
 const NOTHING_DONE: ShipState = { is_committed: false, is_pushed: false, is_merged: false }
 
 async function read_branch_state(branch_name: string): Promise<ShipState> {
-	const [is_committed, is_pushed, is_merged] = await Promise.all([
+	const [is_committed, is_pushed, is_merged, is_review_stale] = await Promise.all([
 		or_false(read_committed),
 		or_false(async () => await read_pushed(branch_name)),
 		or_false(async () => await read_merged(branch_name)),
+		read_review_stale(),
 	])
 
-	return { is_committed, is_pushed, is_merged }
+	return { is_committed, is_pushed, is_merged, is_review_stale }
 }
 
 // A branch that cannot be named leaves nothing to ask about, so it reads as nothing done.
@@ -101,6 +109,6 @@ async function record_target(issue: string): Promise<string | undefined> {
 	return repository === undefined ? undefined : run_ship_stage.record_path(repository, issue)
 }
 
-const run_ship_probe = { read_state, record_target, repository_directory }
+const run_ship_probe = { read_review_stale, read_state, record_target, repository_directory }
 
 export { run_ship_probe }

package/scripts/run/ship/run-ship-relaunch-cap.ts

@@ -0,0 +1,70 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_park } from '#scripts/issue/issue-park'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_stalled } from '#scripts/run/park/run-stalled'
+
+// How many times a stopped ship relaunches its lane child before the issue goes to a person. A child
+// that keeps stopping — the same red check, a finding it cannot close — would otherwise relaunch
+// without end, one ship's cost each time, with nobody told (joshuafolkken/kit#3999).
+//
+// **The count is the issue's `ship-stop` events since its last fresh dispatch**: a relaunch into the
+// lane emits no `child-launch`, a dispatch does, so a re-dispatched issue starts a new budget. The
+// current stop is emitted before the count is read, so it is part of it. Past the cap the issue is
+// parked with `run:stalled`, which every offer and the lane broker already refuse to start.
+// The whole stream is read, not the run's carry scope: the count scopes itself by issue and dispatch,
+// and a lane child shipping with no carry record (`lane:dispatch` outside a run, or a run already
+// ended) would otherwise read no events and relaunch without a cap.
+
+// One dispatch's own stops in the measured week reached five once and four or fewer otherwise, so four
+// relaunches leave a ship that converges alone and stop the one that does not.
+const MAX_SHIP_STOP_RELAUNCHES = 4
+const PARK_CAUSE = 'ship-stop cap'
+const { CHILD_LAUNCH, PARK, SHIP_STOP } = run_event_stream.EVENT_KIND
+
+function stops_since_dispatch(events: ReadonlyArray<RunEvent>, issue: string): number {
+	const own = events.filter((event) => run_event_scope.issue_named(event) === issue)
+	const dispatched = own.findLastIndex((event) => event.kind === CHILD_LAUNCH)
+
+	return own.slice(dispatched + 1).filter((event) => event.kind === SHIP_STOP).length
+}
+
+async function is_over(issue: string): Promise<boolean> {
+	const events = await run_event_stream_emit.all_events()
+
+	return stops_since_dispatch(events, issue) > MAX_SHIP_STOP_RELAUNCHES
+}
+
+function park_comment(issue: string, reason: string): string {
+	return [
+		`Parked by the \`josh ship\` supervisor: the ship stopped at \`${reason}\` after ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches of the lane child since its dispatch.`,
+		'',
+		`Read the stop with \`pnpm josh ship --log ${issue}\`, then ${run_stalled.next_step(issue)}.`,
+	].join('\n')
+}
+
+// The label is what keeps the issue from being re-dispatched; without it the stop stays a plain stop,
+// which `run:merge` books as an unanswered ship stop under its own outage cap.
+async function park(issue: string, reason: string): Promise<boolean> {
+	const park_write = await issue_park.apply(issue, RUN_STALLED_LABEL, park_comment(issue, reason))
+
+	if (!park_write.is_labelled) return false
+
+	const cite = issue_cite.plain(issue)
+
+	await run_event_stream_emit.emit(PARK, run_stalled.park_event(issue, PARK_CAUSE))
+	await telegram_notify.warn({
+		issue_title: `Ship stop cap reached ${cite}`,
+		body: `The lane child stopped at ${reason} more than ${String(MAX_SHIP_STOP_RELAUNCHES)} times since its dispatch, so it was not relaunched and the issue is parked.`,
+		recovery: `Read pnpm josh ship --log ${issue}, then fix the cause and remove ${RUN_STALLED_LABEL} to offer it again.`,
+	})
+
+	return true
+}
+
+const run_ship_relaunch_cap = { MAX_SHIP_STOP_RELAUNCHES, is_over, park, stops_since_dispatch }
+
+export { run_ship_relaunch_cap }

package/scripts/run/ship/run-ship-removed-rows.ts

@@ -0,0 +1,61 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { removed_tests } from '#scripts/review/removed-tests'
+import { removed_tests_check } from '#scripts/review/removed-tests-check'
+import { run_ship_body_draft } from './run-ship-body-draft'
+
+// **The tests a change removed, shown where a run passes before `josh ship`** — the end of a green
+// `josh test:related`. Their disposition rows were first asked at the ship's preflight, after the
+// pre-detach checks had run, and every lane that renamed a test stopped there and shipped again
+// (joshuafolkken/kit#4563). The removed titles are `removed_tests_check.read()`'s, and the pending
+// rows go into the branch's ship body draft, so the run only replaces each ending; the preflight still
+// refuses a row left pending.
+
+async function draft_of_branch(): Promise<string | undefined> {
+	const issue_number = git_branch.issue_from_branch(await git_command.branch())
+
+	if (issue_number === undefined) return undefined
+
+	return await run_ship_body_draft.existing(String(issue_number))
+}
+
+async function body_of(draft: string | undefined): Promise<string> {
+	return draft === undefined ? '' : await readFile(draft, 'utf8')
+}
+
+// An unreadable base lists nothing here — the preflight refuses on it — and outside a repository it
+// keeps the branch, which git could not answer, from being asked at all.
+async function removed_titles(): Promise<ReadonlyArray<string>> {
+	return (await removed_tests_check.read()) ?? []
+}
+
+function where(draft: string | undefined): string {
+	return draft === undefined
+		? 'Put these rows into the pull request body'
+		: `Pending rows for them are in the ship body draft ${draft}`
+}
+
+function notice(titles: ReadonlyArray<string>, draft: string | undefined): string {
+	return [
+		`Removed tests — this change removes ${String(titles.length)} test(s) the ship body does not dispose of yet. ${where(draft)}; replace each ending, ${removed_tests.ROW_FORMAT}, or the \`josh ship\` preflight refuses:`,
+		...titles.map((title) => `  - ${title}`),
+	].join('\n')
+}
+
+async function surface(): Promise<void> {
+	const removed = await removed_titles()
+
+	if (removed.length === 0) return
+	const draft = await draft_of_branch()
+	const body = await body_of(draft)
+	const titles = removed_tests.undisposed(removed, body)
+
+	if (titles.length === 0) return
+	if (draft !== undefined) await writeFile(draft, removed_tests.with_pending_rows(body, titles))
+	console.info(notice(titles, draft))
+}
+
+const run_ship_removed_rows = { surface }
+
+export { run_ship_removed_rows }

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

@@ -1,3 +1,4 @@
+import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { lane_child_invocation, type ShipStop } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
@@ -6,8 +7,15 @@ import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { lane_session_broker } from '#scripts/lane/lane-session-broker'
 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 { ShipSection } from './run-ship'
+import { run_ship_next, type ShipResume } from './run-ship-next'
+import { run_ship_place } from './run-ship-place'
+import { run_ship_probe } from './run-ship-probe'
+import { run_ship_relaunch_cap } from './run-ship-relaunch-cap'
 import { run_ship_stage, type Stage } from './run-ship-stage'
+import type { ShipArguments } from './run-ship-steps'
+import { run_ship_stop_cause } from './run-ship-stop-cause'
+import { run_ship_stop_context } from './run-ship-stop-context'
 import { run_ship_stop_text } from './run-ship-stop-text'
 
 // How a detached `josh ship` supervisor hands a stopped stage back. The agent
@@ -22,16 +30,26 @@ import { run_ship_stop_text } from './run-ship-stop-text'
 //    effort because a fix is judgement. It is started before the supervisor exits, so the parent's
 //    liveness poll never sees the lane empty. An OpenAI lane is left to its own supervisor, which starts
 //    no successor without a cut, so its parent books the stop exactly as it books any ended child.
+//    The relaunches are capped: past the cap the issue is parked and a person told instead.
 //
 // A ship run in an agent's own turn is not supervised and hands nothing back: its report is already in
 // front of the agent that ran it.
 
 const OPENAI_PROVIDER = 'openai'
+// A minute of polling, long enough for the supervisor's 5-second lane scan to reopen a server.
+const SERVING_POLL_MS = 1000
+const SERVING_POLLS = 60
 
-type ReturnOutcome = 'relaunched' | 'recorded'
+type ReturnOutcome = 'relaunched' | 'recorded' | 'parked' | 'redispatch'
 
-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))
+// The failed stage's output, and its standard output alone where the stage kept it apart.
+type StageOutput = Pick<ShipSection, 'body' | 'out'>
+
+function stop_text(issue: string, stage: Stage, resume: ShipResume, output: StageOutput): string {
+	const reason = run_ship_stage.stop_reason(stage, resume.conflicts)
+	const cause = run_ship_stop_cause.cause_of(stage, { ...resume, ...output })
+
+	return run_ship_stop_text.format(issue, reason, cause)
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
@@ -65,38 +83,128 @@ function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
 // **A served lane's child is relaunched by its broker, not from here**: this supervisor descends from the
 // child's Bash tool, which Claude Code starts without the token, so a child started here could not sign
 // in where the token is the only credential (joshuafolkken/kit#3817).
-async function brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
-	if (await lane_session_broker.request(lane.directory, lane.issue, { kind: 'relaunch', stop })) {
-		return 'relaunched'
+async function ask_broker(lane: LaneInfo, stop: ShipStop): Promise<boolean> {
+	const answer = await lane_session_broker.request(lane.directory, lane.issue, {
+		kind: 'relaunch',
+		stop,
+	})
+
+	if (!answer.is_success) note(`the lane broker did not start the lane child — ${answer.reason}`)
+
+	return answer.is_success
+}
+
+// The session of a broker serving the lane within the wait, other than `previous` — one that stopped
+// serving is reopened by the supervisor's next lane scan (`claude-lane-broker.ts`).
+async function await_server(lane: LaneInfo, previous?: string): Promise<string | undefined> {
+	for (let polled = 0; polled < SERVING_POLLS; polled += 1) {
+		const session = lane_session_broker.serving_session(lane.directory, lane.issue)
+		if (session !== undefined && session !== previous) return session
+
+		// eslint-disable-next-line no-await-in-loop -- polling: each check waits on the scan the previous one missed
+		await sleep(SERVING_POLL_MS)
 	}
 
-	note('the lane child could not be relaunched: the lane broker did not start it')
+	return undefined
+}
+
+// **A relaunch the broker failed is asked once more, of a new broker only, then handed to the driver**: a
+// stop left recorded waited hours for the stall detector (joshuafolkken/kit#4344). The broker that failed
+// may still be starting the first relaunch, so asking it again could start a second child beside it.
+// Once this supervisor exits, the driver's next poll reads the stop as unanswered and re-dispatches the
+// issue (`run-merge-ship.ts`).
+async function brokered(lane: LaneInfo, stop: ShipStop, server: string): Promise<ReturnOutcome> {
+	if (await ask_broker(lane, stop)) return 'relaunched'
+
+	const next = await await_server(lane, server)
+
+	if (next !== undefined && (await ask_broker(lane, stop))) return 'relaunched'
+
+	note('the lane child could not be relaunched: the driver re-dispatches the issue')
+
+	return 'redispatch'
+}
+
+// A child that stopped more often than the cap allows is parked instead of relaunched
+// (`run-ship-relaunch-cap.ts`); a park the label refused leaves the stop recorded, as before.
+async function parked(issue: string, stage: Stage, resume: ShipResume): Promise<ReturnOutcome> {
+	const reason = run_ship_stage.stop_reason(stage, resume.conflicts)
+
+	if (await run_ship_relaunch_cap.park(issue, reason)) return 'parked'
+
+	note('the lane child was not relaunched past the ship-stop cap, and the park label was refused')
 
 	return 'recorded'
 }
 
-async function return_control(
+// `output` is the failed stage's own output: the relaunched child's prompt carries the body's tail, and
+// the stop is classified on its standard output (`run-ship-stop-cause.ts`).
+async function stopped(
 	issue: string,
 	stage: Stage,
 	resume: ShipResume,
+	output: StageOutput,
 ): Promise<ReturnOutcome> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.SHIP_STOP,
-		stop_text(issue, stage, resume),
+		stop_text(issue, stage, resume, output),
 	)
 
 	const lane = await lane_to_relaunch(issue)
 
 	if (lane === undefined) return 'recorded'
 
-	const stop = { stage, ...resume }
+	if (await run_ship_relaunch_cap.is_over(issue)) return await parked(issue, stage, resume)
+	// A followup stop waits for a lane place, keeping the ship-stop prompt and the relaunch cap a driver
+	// re-dispatch would lose (`run-ship-place.ts`).
+	await run_ship_place.await_place(lane, stage)
+
+	const context = await run_ship_stop_context.build(issue, output.body)
+	const stop = { stage, ...resume, context }
+	// **A broker that stopped serving before the stop is waited for**: one that died during the review left
+	// the lane unserved at the stop, and a child started here cannot sign in on a token (joshuafolkken/kit#4344).
+	const server = await await_server(lane)
+
+	return server === undefined ? relaunched(lane, stop) : await brokered(lane, stop, server)
+}
+
+async function return_control(
+	issue: string,
+	stage: Stage,
+	resume: ShipResume,
+	output: string,
+): Promise<ReturnOutcome> {
+	return await stopped(issue, stage, resume, { body: output })
+}
+
+type FailedSection = Pick<ShipSection, 'body' | 'out' | 'conflicts' | 'cause'>
+
+// The section's conflicts and the cause its review round tagged, only where it has them.
+function stopped_resume(resume: ShipResume, failed: FailedSection | undefined): ShipResume {
+	const { conflicts, cause } = failed ?? {}
+
+	return {
+		...resume,
+		...(conflicts !== undefined && { conflicts }),
+		...(cause !== undefined && { cause }),
+	}
+}
+
+// The stopped ship's arguments and its failed section, as `stopped` takes them: the section's conflicts
+// and tagged cause ride on the resume, its body and standard output are the stage's output. A stale
+// review rides on it too, so the relaunched child re-detaches with `--review` (joshuafolkken/kit#4221).
+async function hand_back(
+	args: ShipArguments,
+	stage: Stage,
+	failed: FailedSection | undefined,
+): Promise<ReturnOutcome> {
+	const is_review_stale = await run_ship_probe.read_review_stale()
+	const resume = { ...run_ship_next.resume_of(args), is_review_stale }
 
-	return lane_session_broker.is_serving(lane.directory, issue)
-		? await brokered(lane, stop)
-		: relaunched(lane, stop)
+	return await stopped(args.number, stage, stopped_resume(resume, failed), failed ?? { body: '' })
 }
 
-const run_ship_return = { return_control }
+const run_ship_return = { hand_back, return_control }
 
 export type { ReturnOutcome }
 export { run_ship_return }