@joshuafolkken/kit 1.1050.0 → 1.1094.0

package/scripts/run/run-progress-read.ts

@@ -28,7 +28,7 @@ import { run_progress_clock } from './run-progress-clock'
 // `run-progress-clock.ts`, because the trigger-delivered rule that refuses an early heartbeat reads
 // the same record from inside a `PreToolUse` hook and cannot await the git call this file makes
 // (joshuafolkken/kit#1570). What stays here is the asynchronous way of naming the work tree.
-const { PROGRESS_PREFIX, mark, parse_stamp, read_last_report } = run_progress_clock
+const { mark, parse_stamp, read_last_report } = run_progress_clock
 
 const FIRST_LOAD_AVERAGE = 0
 
@@ -182,7 +182,6 @@ async function read_observations(request: ObservationRequest): Promise<Observati
 }
 
 const run_progress_read = {
-	PROGRESS_PREFIX,
 	has_run_started,
 	live_target,
 	log_target,

package/scripts/run/run-progress.ts

@@ -257,7 +257,7 @@ interface LineTiming {
  * this is that same move for one value.
  *
  * **It is a schedule rather than an observation, and the two conditions on it are said in prose**
- * (`docs/josh-commands.md` → `josh run:progress`): it holds only while the silence continues, and a
+ * (`docs/josh-commands-automation.md` → `josh run:progress`): it holds only while the silence continues, and a
  * real report arriving first restarts the clock through `--mark` and supersedes it. The line printing
  * it is itself a report, so the clock starts at this observation.
  */
@@ -367,7 +367,6 @@ const run_progress = {
 	format_line,
 	format_next_line,
 	format_next_report,
-	format_record,
 	format_report,
 	is_due,
 	minutes_from,

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

@@ -6,6 +6,7 @@ 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_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
@@ -255,7 +256,9 @@ 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
 }
@@ -268,10 +271,12 @@ async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const sections: Array<ShipSection> = []
 
 	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)
 	}
 
@@ -324,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
 }
@@ -346,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)
@@ -376,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

@@ -1,7 +1,7 @@
 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_gh_command } from '#scripts/git/git-gh-command'
 import { git_preflight } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'

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 }

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

@@ -5,6 +5,7 @@ import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
+import { review_record } from '#scripts/review/review-record'
 import { detached_launch } from './detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
 import { run_ship_scoped, type Phase } from './run-ship-scoped'
@@ -43,8 +44,10 @@ const ROUND_TWO_DECISION = ['review:round2', '--round-1-closed']
 const ROUND_TWO_BRIEF = ['review:brief', '--round', '2']
 const ROUND_TWO_REQUIRED = 'required'
 const FIXED_JOIN_NOTE =
-	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate stage re-runs it.'
+	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate re-runs once the tree is fixed.'
 const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
+const ROUND_ONE_RECORDED_NOTE =
+	'round 1 already recorded for this issue — not reviewed again; the gate reads the fixed tree and round 2 decides after the commit.'
 
 // The scoped pair's precondition, met by the supervisor itself rather than stopped on
 // (joshuafolkken/kit#2500), single-sourced with the preflight and gate stages (joshuafolkken/kit#2946).
@@ -125,12 +128,14 @@ function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
 
 // A red join blocks unless the reviewer fixed findings in place: the background gate then read the
 // tree before the fixes, so its verdict describes a tree that no longer exists. The join still ran to
-// its end, so the gate stage that follows never races it.
+// its end, so the gate stage that follows never races it. Any fix drains it, not only a round whose
+// every finding was fixed — a partial fix moved the tree just the same, and the round then stops on its
+// unfixed finding at the record rather than on a `Gate RED` the gate never earned (joshuafolkken/kit#2961).
 async function join_gate(): Promise<JoshResult> {
 	const joined = await josh([RUN_REVIEW, '--join'])
 
 	if (joined.code === SUCCESS_EXIT_CODE) return joined
-	if (current_verdict().kind !== run_ship_review.VERDICT.FIXED) return joined
+	if (!run_ship_review.has_fixes(stamp_file.read_stamp_text(paths().findings))) return joined
 
 	note(FIXED_JOIN_NOTE)
 
@@ -191,7 +196,16 @@ async function round_one_record(issue: string): Promise<JoshResult> {
 
 // The round-1 review, beside the gate: scoped pair → open → review → join → attest → record, stopping
 // at the first that did not pass.
+//
+// **A recorded round 1 is not run again** (joshuafolkken/kit#2964). A ship relaunched with `--review`
+// after a round-1 stop would otherwise review the whole change a second time as round 1 — a new Medium
+// there stops it again, and round 2 after the commit makes a third. The fix delta is round 2's to
+// verify, and `round_two_stage` asks whether it is due after the commit.
 async function review_stage(issue: string): Promise<JoshResult> {
+	const recorded = await review_record.check(Number(issue))
+
+	if (recorded.status === 'ok') return { code: SUCCESS_EXIT_CODE, out: ROUND_ONE_RECORDED_NOTE }
+
 	return await run_phases([
 		scoped_pair,
 		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt, issue, '1'),
@@ -221,6 +235,6 @@ async function round_two_stage(issue: string): Promise<JoshResult> {
 	])
 }
 
-const run_ship_review_steps = { paths, review_stage, round_two_stage }
+const run_ship_review_steps = { review_stage, round_two_stage }
 
 export { run_ship_review_steps }

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

@@ -162,6 +162,16 @@ function is_clean_round_one(text: string | undefined): boolean {
 	return read_verdict(text).kind === VERDICT.CLEAN
 }
 
+// Whether the reviewer edited the tree — any finding marked fixed, whether or not another one still
+// blocks (joshuafolkken/kit#2961). A partial fix moves the tree the background gate read as surely as a
+// full one, so the join reads it red either way; keyed off the verdict kind instead, a round that fixed
+// one Medium and left another stopped at a misleading `Gate RED` before its own blocking note.
+function has_fixes(text: string | undefined): boolean {
+	if (text === undefined) return false
+
+	return spec_findings(text).some((finding) => finding.is_fixed)
+}
+
 // Round 2 is final and reads only, so it passes clean or Low-only alone — a fix it made would itself be
 // unreviewed.
 function round_two_outcome(verdict: ScoredVerdict): RoundOutcome {
@@ -174,6 +184,7 @@ const run_ship_review = {
 	FIXED_PREFIX,
 	UNVERIFIED_OUTCOME,
 	VERDICT,
+	has_fixes,
 	is_clean_round_one,
 	read_verdict,
 	reviewer_prompt,

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

@@ -16,6 +16,7 @@ async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
 	let last: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
 
 	for (const phase of phases) {
+		// eslint-disable-next-line no-await-in-loop -- phases run in order and the first failure stops the rest
 		last = await phase()
 		if (last.code !== SUCCESS_EXIT_CODE) return last
 	}

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

@@ -99,7 +99,7 @@ function steps(args: ShipArguments): ReadonlyArray<Step> {
 	return [PREFLIGHT_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
 }
 
-const run_ship_steps = { steps }
+const run_ship_steps = { PREFLIGHT_STEP, steps }
 
 export type { ShipArguments, Step }
 export { run_ship_steps }

package/scripts/run/run-ship.ts

@@ -70,7 +70,6 @@ const run_ship = {
 	ROUND_TWO_HEADER,
 	SKIPPED_BODY,
 	STOPPED_PREFIX,
-	SUCCESS_EXIT_CODE,
 	exit_code,
 	failed_section,
 	format_report,

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

@@ -0,0 +1,62 @@
+import { has_label_name, PLANNED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { run_halfrun_resume } from './run-halfrun-resume'
+import { run_prrun_resume, type PrrunToken } from './run-prrun-resume'
+import { run_stage, type StageState } from './run-stage'
+
+// The reading half of the stage ladder (joshuafolkken/kit#3042): the facts `run_stage.state_of` folds
+// into one state, each read from where the stage that produced it left it — never from the
+// conversation. A closed issue and the `run:planned` label come from GitHub; a `halfrun` stop and a `prrun`
+// stop come from the stop's own mark on the tree's hold (`run-halfrun-resume.ts`,
+// `run-prrun-resume.ts`).
+
+const CLOSED = 'CLOSED'
+
+interface StageRead {
+	state: StageState
+	// The `prrun` stop's resume token, kept so the entry acts on it without reading the pull request
+	// again; `undefined` when no `prrun` stop is recorded for the issue.
+	prrun_token: PrrunToken | undefined
+}
+
+function is_closed(read: StateRead): boolean {
+	return read.kind === 'state' && read.state.state === CLOSED
+}
+
+function is_planned(read: StateRead): boolean {
+	return read.kind === 'state' && has_label_name(read.state.labels, PLANNED_LABEL)
+}
+
+// The two stops are one hold record, so at most one is present; the `prrun` one is asked only when the
+// `halfrun` one is not, which spares its pull-request read.
+async function read_stop(
+	issue: string,
+): Promise<{ is_halfrun_stopped: boolean; prrun_token: PrrunToken | undefined }> {
+	if (await run_halfrun_resume.is_pending(issue)) {
+		return { is_halfrun_stopped: true, prrun_token: undefined }
+	}
+
+	return { is_halfrun_stopped: false, prrun_token: await run_prrun_resume.resume_token(issue) }
+}
+
+// An unreadable issue reads as neither closed nor planned: the ordinary entry that follows reads it
+// again and answers `unknown` for it, exactly as before the ladder existed.
+async function read_stage(issue: string): Promise<StageRead> {
+	const [issue_read, stop] = await Promise.all([
+		issue_state_cli.read_issue(issue),
+		read_stop(issue),
+	])
+	const state = run_stage.state_of({
+		is_closed: is_closed(issue_read),
+		is_prrun_stopped: stop.prrun_token !== undefined,
+		is_halfrun_stopped: stop.is_halfrun_stopped,
+		is_planned: is_planned(issue_read),
+	})
+
+	return { state, prrun_token: stop.prrun_token }
+}
+
+const run_stage_read = { read_stage }
+
+export type { StageRead }
+export { run_stage_read }