@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -44,6 +44,9 @@ interface ShipState {
 	is_committed: boolean
 	is_pushed: boolean
 	is_merged: boolean
+	// The issue changed after the recorded review's brief (`issue-watch-gate.ts`), so the review re-runs
+	// even on a committed tree (joshuafolkken/kit#4221).
+	is_review_stale?: boolean
 }
 
 const RECORD_PREFIX = 'josh-ship-stages-'
@@ -56,15 +59,24 @@ const STARTED_INDEX = 3
 const WORD_COUNT = STARTED_INDEX + 1
 
 // `started` lists the stages the current attempt started, kept across a supervisor that ended without a
-// stop so its successor's lines still carry them.
+// stop so its successor's lines still carry them. `is_merge_waiting` is set only while `josh followup`
+// itself runs, `is_place_waiting` only while a followup stop waits for a lane place
+// (`run-ship-place.ts`) (joshuafolkken/kit#4466).
 const record_schema = z.object({
 	done: z.array(z.string()),
 	started: z.array(z.string()).default([]),
+	is_merge_waiting: z.boolean().default(false),
+	is_place_waiting: z.boolean().default(false),
 })
 
 type ShipRecord = z.infer<typeof record_schema>
 
-const EMPTY_RECORD: ShipRecord = { done: [], started: [] }
+const EMPTY_RECORD: ShipRecord = {
+	done: [],
+	started: [],
+	is_merge_waiting: false,
+	is_place_waiting: false,
+}
 
 // Keyed on the repository and the issue: every lane of one repository shares the common git directory,
 // and two issues shipping from two lanes keep two records.
@@ -109,7 +121,36 @@ function mark_started(target: string, stage: Stage): void {
 // A `ship-stop` ends the attempt on the board (`run-board-phase.ts`), so the next attempt lists afresh
 // while the completed stages stay recorded.
 function end_attempt(target: string): void {
-	stamp_file.replace_stamp(target, { ...read_record(target), started: [] })
+	stamp_file.replace_stamp(target, { ...read_record(target), started: [], is_merge_waiting: false })
+}
+
+// Whether the ship waits on CI, CodeRabbit and the merge alone: its lane then holds no place under the
+// lane limit (`backlog-occupied.ts`). Cleared before any gate the followup stage runs, at a stop, and
+// when a successor supervisor opens the record, so a dead supervisor's flag frees nothing.
+function read_merge_waiting(target: string): boolean {
+	return read_record(target).is_merge_waiting
+}
+
+function mark_merge_waiting(target: string, is_merge_waiting: boolean): void {
+	stamp_file.replace_stamp(target, { ...read_record(target), is_merge_waiting })
+}
+
+// Whether a followup stop waits for a place before it relaunches its child (`run-ship-place.ts`).
+function read_place_waiting(target: string): boolean {
+	return read_record(target).is_place_waiting
+}
+
+function mark_place_waiting(target: string, is_place_waiting: boolean): void {
+	stamp_file.replace_stamp(target, { ...read_record(target), is_place_waiting })
+}
+
+// A supervisor that died mid-wait left its wait marked; its successor waits on nothing yet.
+function clear_waits(target: string): void {
+	stamp_file.replace_stamp(target, {
+		...read_record(target),
+		is_merge_waiting: false,
+		is_place_waiting: false,
+	})
 }
 
 // Removed once the report stage completes, so a later ship of the same issue starts from the preflight.
@@ -129,8 +170,9 @@ const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => bo
 	[STAGE.PREFLIGHT]: (_done, state) => state.is_merged || state.is_committed,
 	// The `--review` round precedes the commit, so a commit is its output as it
 	// is the gate's. A record alone is not honored: before a commit the tree may have been edited since
-	// the recorded round, and only a commit pins the tree that round read.
-	[STAGE.REVIEW]: (_done, state) => state.is_merged || state.is_committed,
+	// the recorded round, and only a commit pins the tree that round read — unless the issue changed since.
+	[STAGE.REVIEW]: (_done, state) =>
+		state.is_merged || (state.is_committed && state.is_review_stale !== true),
 	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
 	// The merge of the default branch before the commit: once committed, a
 	// conflicting pull request is the followup's to merge again.
@@ -173,9 +215,11 @@ function commit_flags(state: ShipState): ReadonlyArray<string> {
 // **The newest line carries the attempt's history**: a fourth word lists every
 // stage the attempt has started, so the one line per issue a stream full of positions keeps still
 // draws the whole track. A line with no started stage keeps the three-word form.
+// The stage is a word rather than a `Stage`: the pre-detach checks, which are not one, are written in
+// the same form (`run-ship-pre-detach-timed.ts`).
 function event_text(
 	issue: string,
-	stage: Stage,
+	stage: string,
 	phase: Phase,
 	started: ReadonlyArray<string> = [],
 ): string {
@@ -205,13 +249,18 @@ const run_ship_stage = {
 	PHASE,
 	STAGE,
 	clear,
+	clear_waits,
 	commit_flags,
 	end_attempt,
 	event_text,
 	is_done,
 	mark_done,
+	mark_merge_waiting,
+	mark_place_waiting,
 	mark_started,
 	read_done,
+	read_merge_waiting,
+	read_place_waiting,
 	read_started,
 	record_path,
 	started_of,

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

@@ -1,15 +1,18 @@
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { run_ship } from './run-ship'
+import { run_ship_body_draft } from './run-ship-body-draft'
 import { run_ship_preflight } from './run-ship-preflight'
+import { run_ship_probe } from './run-ship-probe'
 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'
+import { run_ship_sync, type StepResult, type WaitMark } from './run-ship-sync'
 
 // The stages `josh ship` runs, in the order a change ships, kept apart from the chaining
 // CLI so the order is read in one place.
 
 const should_forward_stderr = true
+const SUCCESS_EXIT_CODE = 0
 
 interface ShipArguments {
 	title: string
@@ -54,19 +57,22 @@ async function gate_stage(): Promise<StepResult> {
 	return { ...result, is_skipped }
 }
 
+// The default branch is merged before the gate, so the pull request opens on a branch that is current;
+// a clean merge goes on without waking anyone. A merge after the gate would move the merge base the
+// gate's record pins, so the pre-push hook could not reuse that record. **With `--review` it runs before
+// round 1 too**: the gate round 1 launches then reads the base the commit carries, so a clean round
+// leaves the gate stage a reuse rather than a whole second gate over a moved base (joshuafolkken/kit#4442).
+const SYNC_STEP: Step = {
+	stage: STAGE.SYNC,
+	header: run_ship.SYNC_HEADER,
+	run: async (args) => await run_ship_sync.sync_stage(args.number),
+}
+
 // The gate before the commit, the commit/push/PR before the merge. The gate meets the scoped pair
 // first: a round-1 reviewer may have edited the tree since the preflight, and `josh gate` refuses a tree
 // with no green record. 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> = [
-	// The default branch is 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: a merge after it
-	// would move the merge base the gate's record pins, so the pre-push hook could not reuse that record.
-	{
-		stage: STAGE.SYNC,
-		header: run_ship.SYNC_HEADER,
-		run: async () => await run_ship_sync.sync_stage(),
-	},
 	{
 		stage: STAGE.GATE,
 		header: run_ship.GATE_HEADER,
@@ -80,12 +86,36 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 	},
 ]
 
+// The followup's merge wait on the stage record, written best-effort as the stages are
+// (`run-ship-cli.ts`): a lost mark only keeps the lane counted (joshuafolkken/kit#4466).
+function wait_mark(target: string | undefined): WaitMark {
+	return function mark(is_merge_waiting: boolean): void {
+		if (target === undefined) return
+
+		try {
+			run_ship_stage.mark_merge_waiting(target, is_merge_waiting)
+		} catch {
+			// Best-effort: an unmarked wait holds the lane's place, the safe direction.
+		}
+	}
+}
+
+// The merge, then the ship body draft goes with it (`run-ship-body-draft.ts`).
+async function followup_stage(args: ShipArguments): Promise<StepResult> {
+	const mark = wait_mark(await run_ship_probe.record_target(args.number))
+	const result = await run_ship_sync.followup_stage(args.title, args.notify, mark)
+
+	if (result.code === SUCCESS_EXIT_CODE) await run_ship_body_draft.remove(args.number)
+
+	return result
+}
+
 // The merge before the report bookkeeping.
 const MERGE_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.FOLLOWUP,
 		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await run_ship_sync.followup_stage(args.title, args.notify),
+		run: async (args) => await followup_stage(args),
 	},
 	{
 		stage: STAGE.REPORT,
@@ -95,14 +125,15 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 ]
 
 // `--review` 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 unless the sync stage between them
-// merged the default branch and changed the tree. It also puts the round-2 pass between the commit
+// the gate stage that follows reuses that tree's green record unless the round changed the tree. It
+// also puts the round-2 pass between the commit
 // and the followup, 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),
+	run: async (args, state) =>
+		await run_ship_review_steps.review_stage(args.number, state.is_review_stale === true),
 }
 const ROUND_TWO_STEP: Step = {
 	stage: STAGE.ROUND_TWO,
@@ -111,9 +142,9 @@ const ROUND_TWO_STEP: Step = {
 }
 
 function steps(args: ShipArguments): ReadonlyArray<Step> {
-	if (!args.is_review) return [PREFLIGHT_STEP, ...COMMIT_STEPS, ...MERGE_STEPS]
+	if (!args.is_review) return [PREFLIGHT_STEP, SYNC_STEP, ...COMMIT_STEPS, ...MERGE_STEPS]
 
-	return [PREFLIGHT_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
+	return [PREFLIGHT_STEP, SYNC_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
 }
 
 const run_ship_steps = { PREFLIGHT_STEP, steps }

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

@@ -0,0 +1,135 @@
+import { api_auth } from '#scripts/agent/api-auth'
+import { NO_CHECKS_MESSAGE } from '#scripts/gh/git-pr-checks-watch'
+import type { StopRecord } from '#scripts/lane/lane-ledger'
+import { run_ship_review, type StopFinding } from './run-ship-review'
+import { run_ship_stage, type Stage } from './run-ship-stage'
+
+// Why a `josh ship` stage stopped, beside the stage it stopped at: a review that found something, a
+// merge git could not finish, a check that went red, or the infrastructure — a rate limit, a check list
+// GitHub did not return, a network blip — that a re-run clears (joshuafolkken/kit#3998).
+//
+// **Only a stage whose output is the tooling's own is read for infrastructure**: a gate's or a review's
+// output carries test titles and findings, which may name a rate limit without being one, and their
+// stops are the quality gate's own verdict — never retried, never relabelled.
+//
+// **A review round names its own cause**: the step of the round that stopped tags its result — a red
+// join or scoped pair `check`, a reviewer that did not finish `infra`, a refused attestation `attest` —
+// so only a stop on a recorded finding counts as one (joshuafolkken/kit#4431). An untagged review stop
+// stays a finding.
+
+const CAUSE = {
+	FINDING: 'finding',
+	INFRA: 'infra',
+	CONFLICT: 'conflict',
+	CHECK: 'check',
+	AUTH: 'auth',
+	ATTEST: 'attest',
+} as const
+
+type Cause = (typeof CAUSE)[keyof typeof CAUSE]
+
+const { STAGE } = run_ship_stage
+const REVIEW_STAGES: ReadonlySet<Stage> = new Set([STAGE.REVIEW, STAGE.ROUND_TWO])
+const INFRA_STAGES: ReadonlySet<Stage> = new Set([
+	STAGE.SYNC,
+	STAGE.COMMIT,
+	STAGE.FOLLOWUP,
+	STAGE.REPORT,
+])
+const INFRA_PATTERNS: ReadonlyArray<RegExp> = [
+	/rate limit/iu,
+	new RegExp(NO_CHECKS_MESSAGE, 'u'),
+	/\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND)\b/u,
+	/socket hang up/iu,
+	/could not resolve host/iu,
+	/\bHTTP 50[234]\b/u,
+]
+
+function is_infra(output: string): boolean {
+	return INFRA_PATTERNS.some((pattern) => pattern.test(output))
+}
+
+// A reviewer that could not authenticate is no finding: the review steps put `AUTH_FAILURE_NOTE` at the
+// head of a stop line (`isolated reviewer failed: <note>` or `<note>`), and only there is it read — a
+// finding that quotes the note mid-line stays a finding (joshuafolkken/kit#4216).
+const AUTH_LINE = new RegExp(
+	`^(?:isolated reviewer failed: (?:the broker answered a failure: )?)?${api_auth.AUTH_FAILURE_NOTE}`,
+	'mu',
+)
+
+function is_review(stage: Stage): boolean {
+	return REVIEW_STAGES.has(stage)
+}
+
+function review_cause(output: string, tagged: Cause = CAUSE.FINDING): Cause {
+	return AUTH_LINE.test(output) ? CAUSE.AUTH : tagged
+}
+
+// What a stopped stage handed back: its output, the paths a stopped merge left unmerged, the kinds
+// of the preconditions a stopped preflight found unmet, and the cause a review round tagged its stop with.
+interface StoppedOutput {
+	body: string
+	// The standard output alone, read for the infrastructure in place of the body when present.
+	out?: string
+	conflicts?: ReadonlyArray<string>
+	preconditions?: ReadonlyArray<string>
+	cause?: Cause
+}
+
+const NO_OUTPUT: StoppedOutput = { body: '' }
+
+// A failed stage's body also carries its stderr, where a poll warns of a transient rate limit it then
+// recovered from — so the infrastructure is read on the standard output alone wherever the stage kept it.
+function infra_text({ body, out = body }: StoppedOutput): string {
+	return out
+}
+
+function cause_of(stage: Stage, failed: StoppedOutput): Cause {
+	const { body, conflicts, cause } = failed
+	const reason = run_ship_stage.stop_reason(stage, conflicts)
+
+	if (reason === run_ship_stage.CONFLICT) return CAUSE.CONFLICT
+	if (is_review(stage)) return review_cause(body, cause)
+
+	return INFRA_STAGES.has(stage) && is_infra(infra_text(failed)) ? CAUSE.INFRA : CAUSE.CHECK
+}
+
+// Whether a finding decided the stop — false on any other stop, and on a review stop no finding decided
+// (a red gate at the join, a reviewer that never answered).
+function is_finding_stop(stage: Stage, cause: Cause): boolean {
+	return is_review(stage) && cause === CAUSE.FINDING
+}
+
+// The kind of every blocking finding a review stop's output lists.
+function findings_of(stage: Stage, cause: Cause, body: string): ReadonlyArray<string> {
+	return is_finding_stop(stage, cause) ? run_ship_review.blocking_kinds(body) : []
+}
+
+// Each finding that decided a review stop, whole, for the durable stop log (joshuafolkken/kit#4519).
+function details_of(stage: Stage, failed: StoppedOutput = NO_OUTPUT): ReadonlyArray<StopFinding> {
+	if (!is_finding_stop(stage, cause_of(stage, failed))) return []
+
+	return run_ship_review.blocking_details(failed.body)
+}
+
+// The lane ledger's record of one stop — the stage, its cause and, for a preflight, which
+// preconditions were unmet, so `lane:stats` counts the one worth meeting before a ship
+// (joshuafolkken/kit#4166); for a review, which kinds of finding stopped it (joshuafolkken/kit#4426).
+function record_of(issue: number, stage: Stage, failed: StoppedOutput = NO_OUTPUT): StopRecord {
+	const { body, conflicts, preconditions } = failed
+	const cause = cause_of(stage, failed)
+	const findings = findings_of(stage, cause, body)
+
+	return {
+		issue,
+		reason: run_ship_stage.stop_reason(stage, conflicts),
+		cause,
+		...(preconditions !== undefined && { preconditions: [...preconditions] }),
+		...(findings.length > 0 && { findings: [...findings] }),
+	}
+}
+
+const run_ship_stop_cause = { CAUSE, cause_of, details_of, is_review, record_of }
+
+export type { Cause }
+export { run_ship_stop_cause }

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

@@ -0,0 +1,206 @@
+import { stripVTControlCharacters } from 'node:util'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+import { run_ship_next } from './run-ship-next'
+import { run_ship_probe } from './run-ship-probe'
+
+// What a relaunched lane child needs in front of it to fix a stopped ship: the tail of the failed
+// stage's output — a red check, or the High/Medium findings a review stage reports — and the branch's
+// changed files. Without them the resumed session opened `josh ship --log` and `git diff` itself before
+// doing anything (joshuafolkken/kit#3923).
+//
+// **Both are bounded**, so a long gate log never becomes the whole prompt. The tail is kept because a
+// check reports its verdict last; the lines left out go to a file whose path and line range the prompt
+// names, so nothing is lost and the session reads only the range it needs.
+
+const EXCERPT_LINE_LIMIT = 40
+const EXCERPT_LINE_WIDTH = 240
+const CHANGED_PATH_LIMIT = 30
+const OUTPUT_PREFIX = 'josh-ship-stop-'
+const OUTPUT_SUFFIX = '.log'
+const KEY_SEPARATOR = '-'
+const LINE_BREAK = '\n'
+const CARRIAGE_RETURN = '\r'
+
+const omitted_schema = z
+	.object({ path: z.string().optional(), last_line: z.number().int() })
+	.strict()
+const stop_context_schema = z
+	.object({
+		excerpt: z.array(z.string()).readonly(),
+		omitted: omitted_schema.optional(),
+		changed: z.array(z.string()).readonly().optional(),
+		more_changed: z.number().int(),
+	})
+	.strict()
+
+type StopContext = z.infer<typeof stop_context_schema>
+type Omitted = z.infer<typeof omitted_schema>
+
+// A spinner redraws its line with a carriage return, so only the frame after the last one is what the
+// terminal showed; a CRLF line ends in one and keeps its whole text.
+function shown_frame(line: string): string {
+	return line.trimEnd().split(CARRIAGE_RETURN).at(-1) ?? ''
+}
+
+function output_lines(output: string): Array<string> {
+	return stripVTControlCharacters(output)
+		.trimEnd()
+		.split(LINE_BREAK)
+		.map((line) => agent_role_profile.printable(shown_frame(line)))
+}
+
+// The full output is kept beside the ship log, keyed the same way, so the prompt's line range points at
+// text that reads exactly as the excerpt was cut from.
+async function keep_full_output(issue: string, output: string): Promise<string | undefined> {
+	const repository = await run_ship_probe.repository_directory()
+
+	if (repository === undefined) return undefined
+
+	const target = stamp_file.stamp_path(
+		`${OUTPUT_PREFIX}${issue}${KEY_SEPARATOR}`,
+		repository,
+		OUTPUT_SUFFIX,
+	)
+
+	try {
+		return stamp_file.replace_text_stamp(target, output)
+	} catch {
+		return undefined
+	}
+}
+
+// A full output that could not be kept still reports the cut, with no path: the prompt then points at
+// the stopped report, which holds the same lines.
+async function omitted_range(issue: string, lines: ReadonlyArray<string>): Promise<Omitted> {
+	const path = await keep_full_output(issue, lines.join(LINE_BREAK))
+	const last_line = lines.length - EXCERPT_LINE_LIMIT
+
+	return path === undefined ? { last_line } : { path, last_line }
+}
+
+// A line is cut to a width, so one minified or wrapped line cannot spend the prompt's whole budget.
+function clipped(lines: ReadonlyArray<string>): Array<string> {
+	return lines.map((line) => line.slice(0, EXCERPT_LINE_WIDTH))
+}
+
+async function excerpt_of(
+	issue: string,
+	output: string,
+): Promise<Pick<StopContext, 'excerpt' | 'omitted'>> {
+	const lines = output.trim() === '' ? [] : output_lines(output)
+
+	if (lines.length <= EXCERPT_LINE_LIMIT) return { excerpt: clipped(lines) }
+
+	return {
+		excerpt: clipped(lines.slice(-EXCERPT_LINE_LIMIT)),
+		omitted: await omitted_range(issue, lines),
+	}
+}
+
+// A git that cannot answer leaves the list out rather than costing the relaunch — never empty, which
+// would read as a branch with no changes.
+async function read_paths(): Promise<Array<string> | undefined> {
+	try {
+		return await changed_paths.read_changed_paths(false)
+	} catch {
+		return undefined
+	}
+}
+
+async function changed_of(): Promise<Pick<StopContext, 'changed' | 'more_changed'>> {
+	const paths = await read_paths()
+
+	if (paths === undefined) return { more_changed: 0 }
+
+	return {
+		changed: paths.slice(0, CHANGED_PATH_LIMIT),
+		more_changed: Math.max(0, paths.length - CHANGED_PATH_LIMIT),
+	}
+}
+
+async function build(issue: string, output: string): Promise<StopContext> {
+	return { ...(await excerpt_of(issue, output)), ...(await changed_of()) }
+}
+
+function has_excerpt(context: StopContext | undefined): boolean {
+	return context !== undefined && context.excerpt.length > 0
+}
+
+function excerpt_heading(issue: string, omitted: Omitted | undefined, shown: number): string {
+	if (omitted === undefined) return 'The failed stage output:'
+
+	const source = omitted.path ?? `the stopped report (\`${run_ship_next.COMMAND.LOG} ${issue}\`)`
+	const range = `lines 1-${String(omitted.last_line)} are in ${source}`
+
+	return `The failed stage output (its last ${String(shown)} lines; ${range}):`
+}
+
+// The head lines a budget leaves out join the range the heading names; the file, when one was kept,
+// still holds every line.
+function with_dropped(omitted: Omitted | undefined, dropped: number): Omitted | undefined {
+	if (dropped === 0) return omitted
+
+	return { ...omitted, last_line: (omitted?.last_line ?? 0) + dropped }
+}
+
+function excerpt_block(
+	issue: string,
+	context: StopContext,
+	changed: string,
+	dropped: number,
+): string {
+	const shown = context.excerpt.slice(dropped)
+	const heading = excerpt_heading(issue, with_dropped(context.omitted, dropped), shown.length)
+
+	return [heading, ...shown, changed].join(LINE_BREAK)
+}
+
+function changed_text(context: StopContext): string {
+	if (context.changed === undefined) return 'The changed files could not be read from git.'
+
+	if (context.changed.length === 0) return 'No files changed against the default branch.'
+
+	const more = context.more_changed > 0 ? ` (and ${String(context.more_changed)} more)` : ''
+
+	return `Changed files on the branch: ${context.changed.join(', ')}${more}.`
+}
+
+// The block the ship-stop prompt carries between the next command and the closing invocation.
+//
+// **It fits the `budget` the prompt leaves it** — the prompt is one argv element, refused past
+// `MAX_VALUE_LENGTH` (joshuafolkken/kit#3964) — by dropping the excerpt's head first, since a check
+// reports its verdict last; the tail line always stays.
+function describe(
+	issue: string,
+	context: StopContext,
+	budget: number = agent_role_profile.MAX_VALUE_LENGTH,
+): string {
+	const changed = changed_text(context)
+
+	if (!has_excerpt(context)) return changed
+
+	let dropped = 0
+	let block = excerpt_block(issue, context, changed, dropped)
+
+	while (block.length > budget && dropped < context.excerpt.length - 1) {
+		dropped += 1
+		block = excerpt_block(issue, context, changed, dropped)
+	}
+
+	return block
+}
+
+const run_ship_stop_context = {
+	CHANGED_PATH_LIMIT,
+	EXCERPT_LINE_LIMIT,
+	build,
+	describe,
+	has_excerpt,
+	stop_context_schema,
+}
+
+export type { StopContext }
+export { run_ship_stop_context }

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

@@ -1,15 +1,20 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 
 // 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.
-const STOP_PATTERN = /^#\d+ (\S+) failed — /u
+// retrospective's per-stage count never drifts from the writer. The cause rides in parentheses after
+// `failed` (`run-ship-stop-cause.ts`); a text written before it had one reads back with none.
+const STOP_PATTERN = /^#\d+ (?<reason>\S+) failed(?: \((?<cause>\S+)\))? — /u
 
-function format(issue: string, reason: string): string {
-	return `${issue_cite.plain(issue)} ${reason} failed — pnpm josh ship --log ${issue}`
+function format(issue: string, reason: string, cause: string): string {
+	return `${issue_cite.plain(issue)} ${reason} failed (${cause}) — pnpm josh ship --log ${issue}`
 }
 
 function reason_of(text: string): string | undefined {
-	return STOP_PATTERN.exec(text)?.[1]
+	return STOP_PATTERN.exec(text)?.groups?.['reason']
 }
 
-export const run_ship_stop_text = { format, reason_of }
+function cause_of(text: string): string | undefined {
+	return STOP_PATTERN.exec(text)?.groups?.['cause']
+}
+
+export const run_ship_stop_text = { format, reason_of, cause_of }