@joshuafolkken/kit 1.3101.0 → 1.3125.0

package/scripts/run/board/run-board-closed-pace.ts

@@ -0,0 +1,76 @@
+import { MS_PER_MINUTE, MS_PER_SECOND } from '#scripts/lib/timeouts'
+import type { LocalRead } from './run-board-read'
+import type { BoardState } from './run-board-state'
+import { run_board_status, type ItemState } from './run-board-status'
+
+// Which children a `run:board` closed read asks about once its run has ended.
+
+// A child waiting on a person, drawn in 🙋 decision until a closed read settles it.
+const { WAITING_STATES } = run_board_status
+const STOPPED_STATE: ItemState = 'stopped'
+const ALWAYS_ASKED_STATES: ReadonlySet<ItemState> = new Set([STOPPED_STATE, ...WAITING_STATES])
+// A child that merged itself is drawn stopped until GitHub answers it closed, and the answer can lag
+// the merge by minutes (joshuafolkken/kit#7556). The board stays open between runs, so a stopped child
+// that never closes stops being asked about this long after the run ended — several retry intervals,
+// well past the lag of a merge that already happened.
+const STOPPED_ASK_MINUTES = 15
+const STOPPED_ASK_LIMIT_MS = STOPPED_ASK_MINUTES * MS_PER_MINUTE
+// The first closed read after a lane ends often lands before GitHub shows the merge, which kept the
+// child drawn 🛑 a whole retry interval (joshuafolkken/kit#7557). While a child the read asks about ended
+// its lane within the window, the read is asked again this often. Rate limit: one lane end adds at most
+// window ÷ retry (8) closed reads, each one read of the children still unanswered.
+const FRESH_END_WINDOW_SECONDS = 120
+const FRESH_RETRY_SECONDS = 15
+const FRESH_END_WINDOW_MS = FRESH_END_WINDOW_SECONDS * MS_PER_SECOND
+const FRESH_RETRY_MS = FRESH_RETRY_SECONDS * MS_PER_SECOND
+// Only a closed lane is about to merge; a withdrawn one never closes its Issue.
+const CLOSING_END = 'lane:close'
+
+function has_asked_since_end(state: BoardState, ended_ms: number | undefined): boolean {
+	const { closed_answered_ms } = state
+	if (closed_answered_ms === undefined || ended_ms === undefined) return false
+
+	return closed_answered_ms >= ended_ms
+}
+
+// An ended run asks as a going run does until one ask after it ended has answered whole. After that it
+// asks only about a child drawn stopped, until the limit, or waiting on a person — the person closing
+// it is what the board waits to draw. `undefined` while the run still asks as a going run does.
+function ended_asked_states(
+	state: BoardState,
+	local: LocalRead,
+	now_ms: number,
+): ReadonlySet<ItemState> | undefined {
+	const { ended_ms } = local
+	if (ended_ms === undefined || !has_asked_since_end(state, ended_ms)) return undefined
+
+	return now_ms - ended_ms <= STOPPED_ASK_LIMIT_MS ? ALWAYS_ASKED_STATES : WAITING_STATES
+}
+
+function is_fresh_end(local: LocalRead, issue: number, now_ms: number): boolean {
+	const end = local.lane_states.ended?.get(issue)
+
+	return end?.by === CLOSING_END && now_ms - end.ended_ms <= FRESH_END_WINDOW_MS
+}
+
+// How long after the last closed read the next is due: sooner while a child it asks about has just had
+// its lane ended by its record, else `usual_ms`.
+function closed_retry_ms(
+	local: LocalRead,
+	unread: ReadonlyArray<number>,
+	now_ms: number,
+	usual_ms: number,
+): number {
+	return unread.some((issue) => is_fresh_end(local, issue, now_ms)) ? FRESH_RETRY_MS : usual_ms
+}
+
+const run_board_closed_pace = {
+	ALWAYS_ASKED_STATES,
+	FRESH_END_WINDOW_MS,
+	FRESH_RETRY_MS,
+	STOPPED_ASK_LIMIT_MS,
+	closed_retry_ms,
+	ended_asked_states,
+}
+
+export { run_board_closed_pace }

package/scripts/run/board/run-board-github.ts

@@ -1,6 +1,7 @@
 import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_progress } from '#scripts/run/progress/run-progress'
 import type { ClosedAnswer } from './run-board-closed'
+import { run_board_closed_pace } from './run-board-closed-pace'
 import { run_board_fetch, type Fetch } from './run-board-fetch'
 import { run_board_idle } from './run-board-idle'
 import type { BoardPlan } from './run-board-layout'
@@ -25,11 +26,8 @@ const PLAN_RETRY_MS = run_progress.DECLINE_RETRY_SECONDS * MS_PER_SECOND
 // A rejected closed read answers nothing closed and not whole, so it is asked again.
 const UNANSWERED: ClosedAnswer = { closed: new Map(), is_whole: false }
 const { is_due } = run_board_state
-const STOPPED_STATE: ItemState = 'stopped'
 const RUNNING_STATE: ItemState = 'running'
-// A child waiting on a person, drawn in 🙋 decision until a closed read settles it.
-const { WAITING_STATES } = run_board_status
-const ALWAYS_ASKED_STATES: ReadonlySet<ItemState> = new Set([STOPPED_STATE, ...WAITING_STATES])
+const { ALWAYS_ASKED_STATES, closed_retry_ms, ended_asked_states } = run_board_closed_pace
 
 // What a step of the GitHub reads works against.
 interface Gather {
@@ -151,31 +149,21 @@ function is_closed_candidate(
 	return is_unlisted(issue, read) && !is_closed_cached(issue, read)
 }
 
-// An ended run asks until one ask after it ended has answered whole, then holds what it has, as its
-// plan is held: the board is left open between runs, so a child that never answers closed would
-// otherwise be asked about every retry interval while no run is going. A child waiting on a person
-// is the exception — the person closing it is what the board waits to draw.
-function has_asked_since_end(state: BoardState, local: LocalRead): boolean {
-	const { closed_answered_ms } = state
-	if (closed_answered_ms === undefined || local.ended_ms === undefined) return false
-
-	return closed_answered_ms >= local.ended_ms
-}
-
 // The children the board has not read closed yet that the open listing no longer holds, or that it
 // draws stopped or waiting: a child that merged itself and left its lane is drawn stopped until GitHub
-// says it merged (joshuafolkken/kit#4401), and a listing cut short proves nothing missing.
-function unread_closed(state: BoardState, local: LocalRead): Array<number> {
+// says it merged (joshuafolkken/kit#4401), and a listing cut short proves nothing missing. An ended
+// run narrows them as `run-board-closed-pace.ts` says.
+function unread_closed(state: BoardState, gather: Gather): Array<number> {
 	const read = open_read_of(state, state.plan)
-	const drawn = run_board_status.settle_closed(statuses_for(state, local), read)
+	const drawn = run_board_status.settle_closed(statuses_for(state, gather.local), read)
 	const is_plan_failed = state.failed_ms !== undefined
-	const is_ended = has_asked_since_end(state, local)
+	const ended_asked = ended_asked_states(state, gather.local, gather.now_ms)
 
 	return [...drawn]
 		.filter(([issue, status]) =>
-			is_ended
-				? WAITING_STATES.has(status.state)
-				: is_closed_candidate(issue, status, read, is_plan_failed),
+			ended_asked === undefined
+				? is_closed_candidate(issue, status, read, is_plan_failed)
+				: ended_asked.has(status.state),
 		)
 		.map(([issue]) => issue)
 }
@@ -187,16 +175,17 @@ function has_new_child(state: BoardState, unread: ReadonlyArray<number>): boolea
 function is_closed_due(state: BoardState, gather: Gather, unread: ReadonlyArray<number>): boolean {
 	if (state.closed_fetch !== undefined) return false
 
-	return (
-		has_new_child(state, unread) || is_due(state.closed_attempted_ms, PLAN_RETRY_MS, gather.now_ms)
-	)
+	const { local, now_ms } = gather
+	const retry_ms = closed_retry_ms(local, unread, now_ms, PLAN_RETRY_MS)
+
+	return has_new_child(state, unread) || is_due(state.closed_attempted_ms, retry_ms, now_ms)
 }
 
 // A closed child is read once and its answer kept; one that has not answered closed is asked again no
-// sooner than the plan is — unless a child the last ask did not hold has joined it — and an ended
-// run's not again once an ask after the end has answered whole.
+// sooner than the plan is — unless a child the last ask did not hold has joined it, or one just ended
+// its lane (`run-board-closed-pace.ts`).
 function launch_closed(state: BoardState, gather: Gather): BoardState {
-	const unread = unread_closed(state, gather.local)
+	const unread = unread_closed(state, gather)
 
 	if (unread.length === 0 || !is_closed_due(state, gather, unread)) return state
 

package/scripts/run/board/run-board-labels.ts

@@ -62,6 +62,7 @@ const WORDS = {
 	waiting: 'waiting',
 	queued: 'queued',
 	not_before: 'not before',
+	publication: 'publication pending',
 	decision: 'decision',
 	waits: 'waits on',
 	// What a waiting row waits on, where the legend names its icon.
@@ -272,9 +273,10 @@ const STAGE_ICONS: Readonly<Partial<Record<string, string>>> = {
 // running issue holds, 📋 the declared order, ✋ an unblocked issue held for its judgment, ❓ a
 // blocked issue nobody has judged, 🧍 a `run:solo` issue waiting for the running lanes, 🙅 a row behind it (#4294; 🚧 is a
 // held check's) and 🔒 a row a running `run:solo` issue holds (#4391), chosen on the same rule as
-// every row icon, and 🪫 the account's Claude usage limit until it resets (#4796). The rest are the
-// board's own, shared rather than copied.
+// every row icon, 🪫 the account's Claude usage limit until it resets (#4796), and 📰 an issue whose
+// filing has not published yet (#7572). The rest are the board's own, shared rather than copied.
 const WAIT_ICONS = {
+	publication: '📰',
 	human_merge: '🔏',
 	usage_limit: '🪫',
 	path: '📂',
@@ -310,6 +312,7 @@ const WAIT_WORDS: ReadonlyArray<readonly [icon: string, word: keyof Words]> = [
 	[WAIT_ICONS.blocker, 'waits'],
 	[STATE_ICONS.human, 'on_human'],
 	[WAIT_ICONS.not_before, 'not_before'],
+	[WAIT_ICONS.publication, 'publication'],
 ]
 
 // **The machine gauges' three colors, decided here alone**: Activity Monitor's green, yellow and red

package/scripts/run/board/run-board-reason.ts

@@ -6,6 +6,7 @@ import { epic_triage } from '#scripts/epic/epic-triage'
 import { has_label_name, has_parked_label, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
 import { issue_not_before } from '#scripts/issue/issue-not-before'
 import { issue_observation_gate } from '#scripts/issue/issue-observation-gate'
+import { issue_publication_state } from '#scripts/issue/issue-publication-state'
 import { issue_sample_gate } from '#scripts/issue/issue-sample-gate'
 import { lane_state } from '#scripts/lane/lane-state'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
@@ -344,6 +345,14 @@ function wait_of(
 	return not_before_of(child, read.now_ms) ?? offer_wait(child, read, pool)
 }
 
+// `📰`: an issue whose filing has not published yet (`issue-publication-state.ts`), which no pickup
+// offers until it does, whatever else would keep it (joshuafolkken/kit#7572).
+function publication_of(child: EpicChild): RowReason | undefined {
+	return issue_publication_state.is_pending(child.body)
+		? { icon: WAIT_ICONS.publication }
+		: undefined
+}
+
 // What each waiting row of one layout says, the pool-wide facts read once for all of them.
 function reader(read: ReasonRead): ReasonOf {
 	const current = { ...read, ...run_board_human_merge.overlay_of(read.plan, read.statuses) }
@@ -354,6 +363,7 @@ function reader(read: ReasonRead): ReasonOf {
 			run_board_human_merge.reason_of(child, current.plan) ??
 			stage_of(child, current) ??
 			planned_of(child, pool) ??
+			publication_of(child) ??
 			wait_of(child, waits, current, pool)
 		)
 	}

package/scripts/run/entry/run-entry-sync.ts

@@ -1,7 +1,9 @@
+import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_preflight } from '#scripts/run/run-preflight'
 
 // The tree sync every entry runs before its reads — `#N` (joshuafolkken/kit#5943) and `new`
 // (`--adopt`, joshuafolkken/kit#5747) — so no run issues it as commands of its own: pre-existing changes
@@ -60,8 +62,17 @@ async function step(argv: ReadonlyArray<string>): Promise<JoshResult> {
 	return await josh_command.josh_run(argv, should_forward_stderr)
 }
 
-async function sync_command(): Promise<string> {
-	return (await git_worktree.is_linked()) ? 'main:merge' : 'main:sync'
+// **A primary checkout on the issue's own branch merges, too** (joshuafolkken/kit#7543): the hold was
+// taken there to resume a returned pull request, and `main:sync` would check out the default branch
+// under it, so the fix would land on main instead of the pull request's branch.
+async function is_merged_in_place(issue_number: string): Promise<boolean> {
+	if (await git_worktree.is_linked()) return true
+
+	return run_preflight.is_issue_branch(await git_command.branch(), issue_number)
+}
+
+async function sync_command(issue_number: string): Promise<string> {
+	return (await is_merged_in_place(issue_number)) ? 'main:merge' : 'main:sync'
 }
 
 function stopped({ failed, kept, recommended, later }: StopText): EntryStop {
@@ -117,7 +128,8 @@ async function restore(message: string, is_stashed: boolean): Promise<EntryStop
 	return verdict === CONFLICTED_VERDICT ? pop_conflicted(message) : pop_unmatched(message)
 }
 
-async function sync_tree(message: string): Promise<EntryStop | undefined> {
+async function sync_tree(entry: SyncEntry): Promise<EntryStop | undefined> {
+	const message = stash_message(entry)
 	const pushed = await step([STASH_PUSH, message])
 
 	if (pushed.code !== SUCCESS_EXIT_CODE) {
@@ -125,7 +137,7 @@ async function sync_tree(message: string): Promise<EntryStop | undefined> {
 	}
 
 	const is_stashed = verdict_of(pushed) === STASHED_VERDICT
-	const command = await sync_command()
+	const command = await sync_command(entry.issue_number)
 	const synced = await step([command])
 
 	if (synced.code === SUCCESS_EXIT_CODE) return await restore(message, is_stashed)
@@ -137,7 +149,7 @@ async function sync_tree(message: string): Promise<EntryStop | undefined> {
 async function sync(entry: SyncEntry): Promise<EntryStop | undefined> {
 	if (lane_child_marker.is_child_of(process.cwd())) return undefined
 
-	return await sync_tree(stash_message(entry))
+	return await sync_tree(entry)
 }
 
 const run_entry_sync = {

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

@@ -266,9 +266,15 @@ async function preflight_gate(issue: string, is_linked: boolean): Promise<number
 
 	const decision = await run_preflight.check(issue)
 
-	if (decision.verdict === run_preflight.CLEAN_VERDICT) return undefined
+	if (decision.verdict !== run_preflight.CLEAN_VERDICT) return report_preflight(decision)
 
-	return report_preflight(decision)
+	// A clean tree on the issue's own branch is a resume: the hold is taken, and the whole-gate rule is
+	// still said, because nobody verified what the earlier run committed.
+	if (decision.advice === run_preflight.RESUME_ADVICE) {
+		console.error(`${decision.reason}\n${decision.advice}`)
+	}
+
+	return undefined
 }
 
 async function claim(target: string, request: ClaimRequest, is_linked: boolean): Promise<number> {

package/scripts/run/merge/run-merge-health.ts

@@ -41,8 +41,15 @@ function is_filed(events: ReadonlyArray<RunEvent>): boolean {
 		)
 }
 
-// The lines `issue:file` requires of a defect whose origin is unknown (`issue:file --check`).
+// The lines `issue:file` requires of a defect whose origin is unknown (`issue:file --check`), after the
+// plain-language summary it requires first.
 const DECLARATIONS = [
+	issue_body_keys.heading('summary'),
+	'',
+	'**The verification gate fails on `main`, so every lane is held until it is repaired.**',
+	'',
+	'Several lanes failed one after another, and the same verification then failed on `main` twice in a row, so the cause is on `main` rather than in any one lane. Fix whatever makes the verification fail on `main`; the output is under the reproduction below.',
+	'',
 	issue_body_keys.heading('background'),
 	'',
 	issue_body_keys.line('kind', 'bug'),
@@ -132,6 +139,6 @@ async function check(child: string): Promise<boolean> {
 	return false
 }
 
-const run_merge_health = { TITLE, check }
+const run_merge_health = { TITLE, body_of, check }
 
 export { run_merge_health }

package/scripts/run/review/run-review-pinned-accepted.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import { git_command } from '#scripts/git/git-command'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import type { UnpinnedPath, UnpinnedStop } from '#scripts/lane/lane-ledger-schema-ship'
 import { error_text } from '#scripts/lib/error-message'
 import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
 import { test_pinned_record, type PinnedSummary } from '#scripts/test/test-pinned-record'
@@ -135,6 +136,28 @@ async function judge(summary: PinnedSummary, reason: string | undefined): Promis
 	return { kind: 'accepted', text: test_pinned_logic.report_text(summary, note) }
 }
 
-const run_review_pinned_accepted = { RECORD_NAME, judge, keep_reason, recorded_reason }
+function stop_path(summary: PinnedSummary, reason: string | undefined): UnpinnedPath {
+	if (reason === undefined) return 'no-reason'
+
+	return summary.is_cut === true ? 'truncated' : 'new-site'
+}
+
+// Which path a `judge` stop without a reason took (joshuafolkken/kit#7552): no recorded reason, a
+// recorded one a place outside its record outran, or one a cut check never applies — and how many
+// unpinned places it found, with the hunks a cut check never probed.
+async function unpinned_stop(summary: PinnedSummary): Promise<UnpinnedStop> {
+	const stop = { path: stop_path(summary, await recorded_reason()), hunks: summary.unpinned.length }
+	const { is_cut, remaining } = summary
+
+	return is_cut === true && remaining !== undefined ? { ...stop, remaining } : stop
+}
+
+const run_review_pinned_accepted = {
+	RECORD_NAME,
+	judge,
+	keep_reason,
+	recorded_reason,
+	unpinned_stop,
+}
 
 export { run_review_pinned_accepted }

package/scripts/run/run-preflight.ts

@@ -6,6 +6,7 @@ import { session_cite } from '#scripts/issue/session-cite'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
+import { shell_quote } from '#scripts/lib/shell-quote'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { z } from 'zod'
 
@@ -52,6 +53,9 @@ interface TreeState {
 
 interface ChildState {
 	branch_name: string | undefined
+	// The open lane's worktree when it has `branch_name` checked out — git refuses to switch another
+	// checkout onto that branch, so the resume happens in the lane's directory instead.
+	lane_directory?: string
 	pr_state: PrState
 }
 
@@ -94,8 +98,25 @@ const STASH_LABEL_PREFIX = 'run:hold reclaimed before #'
 const { require_issue_number } = issue_number_shape
 const UNREADABLE_PR_MESSAGE = 'The pull request could not be read for branch '
 
-function needs_reclaim(tree: TreeState): boolean {
-	return tree.is_dirty || tree.branch !== tree.default_branch
+const RESUME_IN_PLACE_REASON =
+	'HEAD is on this issue’s own branch over a clean tree, so the run resumes there.'
+
+const ISSUE_BRANCH_SEPARATOR = '-'
+
+// The same `<N>-` rule `read_branch_candidates` globs by, so `<N><digit>-…` is another issue's branch.
+function is_issue_branch(branch: string, issue: string): boolean {
+	return branch.startsWith(`${issue}${ISSUE_BRANCH_SEPARATOR}`)
+}
+
+function is_off_default(tree: TreeState): boolean {
+	return tree.branch !== tree.default_branch
+}
+
+// **The issue's own branch over a clean tree is where a resume belongs, not something to reclaim**
+// (joshuafolkken/kit#7543): reclaiming it sends the run to the default branch, where `resume` sends it
+// straight back, and neither answer takes the hold. Another issue's branch is still reclaimed.
+function needs_reclaim(tree: TreeState, issue: string): boolean {
+	return tree.is_dirty || (is_off_default(tree) && !is_issue_branch(tree.branch, issue))
 }
 
 // A pull request that was merged or closed is a decision somebody already made. Carrying on over a
@@ -114,17 +135,23 @@ function has_leftover_work(child: ChildState): boolean {
 	return child.branch_name !== undefined || child.pr_state === OPEN_PR
 }
 
+// A clean tree past `needs_reclaim` and off the default branch is on the issue's own branch; it has
+// followed `resume`'s advice only when the work found is on that same branch, not on a sibling one.
+function is_resuming_in_place(tree: TreeState, child: ChildState): boolean {
+	return is_off_default(tree) && (child.branch_name ?? tree.branch) === tree.branch
+}
+
 // The precedence is fixed, and the first row is why it has to be. A `resume` or a `park` decided over
 // a dirty tree hands the next child a checkout it cannot switch — so the tree is reclaimed first and
 // the question asked again on the clean tree, rather than two answers being merged into one.
-function to_verdict(tree: TreeState, child: ChildState): PreflightVerdict {
-	if (needs_reclaim(tree)) return RECLAIM_VERDICT
+function to_verdict(tree: TreeState, child: ChildState, issue: string): PreflightVerdict {
+	if (needs_reclaim(tree, issue)) return RECLAIM_VERDICT
 
 	if (is_pr_decided(child.pr_state)) return PARK_VERDICT
 
-	if (has_leftover_work(child)) return RESUME_VERDICT
+	if (is_resuming_in_place(tree, child)) return CLEAN_VERDICT
 
-	return CLEAN_VERDICT
+	return has_leftover_work(child) ? RESUME_VERDICT : CLEAN_VERDICT
 }
 
 function reclaim_reason(tree: TreeState): string {
@@ -154,7 +181,7 @@ function to_reason(verdict: PreflightVerdict, tree: TreeState, child: ChildState
 
 	if (verdict === RESUME_VERDICT) return resume_reason(child)
 
-	return CLEAN_REASON
+	return is_off_default(tree) ? RESUME_IN_PLACE_REASON : CLEAN_REASON
 }
 
 // **`-u` is not optional.** What an interrupted run leaves almost always includes a new `*.test.ts`,
@@ -183,21 +210,49 @@ function reclaim_advice(tree: TreeState, issue: string): string {
 	].join('\n')
 }
 
-function to_advice(verdict: PreflightVerdict, issue: string, tree: TreeState): string {
+// **`resume` names the one command that leads to a hold.** Switched onto the branch, the same ask
+// answers `clean` and takes the hold, so the caller never alternates between `resume` and `reclaim`.
+// A branch an open lane has checked out cannot be switched to here, so that lane's directory is named.
+function resume_steps(child: ChildState): Array<string> {
+	if (child.lane_directory !== undefined) {
+		return [
+			`cd ${shell_quote.word(child.lane_directory)}`,
+			'Resume in that lane worktree, where the branch is checked out; keep its directory.',
+		]
+	}
+
+	if (child.branch_name === undefined) return []
+
+	return [
+		`git switch ${shell_quote.word(child.branch_name)}`,
+		'Then ask this command again: it takes the hold there.',
+	]
+}
+
+function resume_advice(child: ChildState): string {
+	return [...resume_steps(child), RESUME_ADVICE].join('\n')
+}
+
+function to_advice(
+	verdict: PreflightVerdict,
+	issue: string,
+	tree: TreeState,
+	child: ChildState,
+): string {
 	if (verdict === RECLAIM_VERDICT) return reclaim_advice(tree, issue)
 
-	if (verdict === RESUME_VERDICT) return RESUME_ADVICE
+	if (verdict === RESUME_VERDICT) return resume_advice(child)
 
 	if (verdict === PARK_VERDICT) return PARK_ADVICE
 
-	return CLEAN_ADVICE
+	return is_off_default(tree) ? RESUME_ADVICE : CLEAN_ADVICE
 }
 
 function decide(tree: TreeState, child: ChildState, issue: string): PreflightDecision {
-	const verdict = to_verdict(tree, child)
+	const verdict = to_verdict(tree, child, issue)
 
 	return {
-		advice: to_advice(verdict, issue, tree),
+		advice: to_advice(verdict, issue, tree, child),
 		reason: to_reason(verdict, tree, child),
 		verdict,
 	}
@@ -260,8 +315,16 @@ function is_pr_open(state: PrState): boolean {
 	return state === OPEN_PR
 }
 
-async function read_pr_of_branch(branch_name: string): Promise<ChildState> {
-	return { branch_name, pr_state: await read_pr_state(branch_name) }
+async function read_pr_of_branch(
+	branch_name: string,
+	lane: LaneInfo | undefined,
+): Promise<ChildState> {
+	const pr_state = await read_pr_state(branch_name)
+	const is_lane_branch = lane?.branch === branch_name && !lane.is_stranded
+
+	return is_lane_branch
+		? { branch_name, lane_directory: lane.directory, pr_state }
+		: { branch_name, pr_state }
 }
 
 // **A decided pull request on any candidate branch outranks an open one on another.** An interrupted
@@ -273,7 +336,7 @@ function pick_child_state(reads: ReadonlyArray<ChildState>): ChildState {
 	const decided = reads.find((read) => is_pr_decided(read.pr_state))
 	const open = reads.find((read) => is_pr_open(read.pr_state))
 
-	return decided ?? open ?? { branch_name: reads[0]?.branch_name, pr_state: NO_PR }
+	return decided ?? open ?? reads[0] ?? NO_CHILD_WORK
 }
 
 // `git branch --list` takes a glob, so the branch is found without knowing its slug: `pnpm josh git`
@@ -356,7 +419,7 @@ async function read_candidate(
 	references: ReadonlyArray<string>,
 	context: CandidateContext,
 ): Promise<ChildState | undefined> {
-	const state = await read_pr_of_branch(name)
+	const state = await read_pr_of_branch(name, context.lane)
 
 	if (state.pr_state !== NO_PR || (await has_commits_beyond(context.base, references))) return state
 
@@ -389,7 +452,7 @@ async function check(issue: string): Promise<PreflightDecision> {
 
 	const tree = await read_tree_state()
 
-	if (needs_reclaim(tree)) return decide(tree, NO_CHILD_WORK, issue)
+	if (needs_reclaim(tree, issue)) return decide(tree, NO_CHILD_WORK, issue)
 
 	return decide(tree, await read_child_state(issue), issue)
 }
@@ -401,6 +464,7 @@ const run_preflight = {
 	STASH_LABEL_PREFIX,
 	check,
 	decide,
+	is_issue_branch,
 	read_child_state,
 	read_pr_state,
 	to_pr_state,

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

@@ -1,6 +1,5 @@
 import { randomUUID } from 'node:crypto'
 import { check_reuse } from '#scripts/gate/check-reuse'
-import type { JoshResult } from '#scripts/josh/josh-run'
 import { buffered_process } from '#scripts/lib/buffered-process'
 import { error_text } from '#scripts/lib/error-message'
 import { review_round_reuse } from '#scripts/review/review-round-reuse'
@@ -12,7 +11,7 @@ import { run_review_pinned_steps } from '#scripts/run/review/run-review-pinned-s
 import { test_pinned } from '#scripts/test/test-pinned'
 import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
 import { test_pinned_record, type PinnedSummary } from '#scripts/test/test-pinned-record'
-import { run_ship_pre_detach, type PreDetachResult } from './run-ship-pre-detach'
+import { run_ship_pre_detach, type PinnedResult, type PreDetachResult } from './run-ship-pre-detach'
 import { run_ship_pre_detach_timed } from './run-ship-pre-detach-timed'
 import type { ShipArguments } from './run-ship-steps'
 
@@ -125,21 +124,27 @@ async function is_listed_after_detach(number: string): Promise<boolean> {
 	}
 }
 
+// A stop carries the path it took into the ledger's stop record (joshuafolkken/kit#7552).
+async function judged(answer: PinnedSummary, reason: string | undefined): Promise<PinnedResult> {
+	const verdict = await run_review_pinned_accepted.judge(answer, reason)
+
+	if (verdict.kind !== 'stop') return { code: SUCCESS_EXIT_CODE, out: verdict.text }
+
+	const unpinned = await run_review_pinned_accepted.unpinned_stop(answer)
+
+	return { code: FAILURE_EXIT_CODE, out: verdict.text, unpinned }
+}
+
 // **A reason accepts any answer, so no probe is waited on** (joshuafolkken/kit#4833) when a fresh
 // round 1 lists the places after the detach.
-async function pinned_check(options: CheckOptions): Promise<JoshResult> {
+async function pinned_check(options: CheckOptions): Promise<PinnedResult> {
 	const reason = run_review_pinned.ok_reason_of(options.unpinned_ok)
 
 	if (reason !== undefined && (await is_listed_after_detach(options.number))) {
 		return { code: SUCCESS_EXIT_CODE, out: `${SKIPPED_NOTE}${reason}\n` }
 	}
 
-	const verdict = await run_review_pinned_accepted.judge(await summary_for(reason), reason)
-
-	return {
-		code: verdict.kind === 'stop' ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE,
-		out: verdict.text,
-	}
+	return await judged(await summary_for(reason), reason)
 }
 
 // **A ship with no `--review` reads no background probe, so it stops the one left running**

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

@@ -8,6 +8,7 @@ import { metrics_totals } from '#scripts/gate/metrics-totals'
 import { structural_checks } from '#scripts/gate/structural-checks'
 import { type_check_step } from '#scripts/gate/type-check-step'
 import type { JoshResult } from '#scripts/josh/josh-run'
+import type { UnpinnedStop } from '#scripts/lane/lane-ledger-schema-ship'
 import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 
@@ -145,7 +146,12 @@ function verdict(runs: ReadonlyArray<PreDetachRun>): JoshResult {
 }
 
 // The `test:pinned` check a `--review` ship adds (`run-ship-pre-detach-pinned.ts`); none is asked by default.
-type PinnedCheck = () => Promise<JoshResult>
+// A red one carries the path its stop took (joshuafolkken/kit#7552).
+interface PinnedResult extends JoshResult {
+	unpinned?: UnpinnedStop
+}
+
+type PinnedCheck = () => Promise<PinnedResult>
 
 async function not_asked(): Promise<JoshResult> {
 	return { code: SUCCESS_EXIT_CODE, out: PASSED }
@@ -153,8 +159,8 @@ async function not_asked(): Promise<JoshResult> {
 
 // The checks' answer, with the kinds a `stop` record names its red by: `pre-detach` for the static
 // checks, `unpinned` for `test:pinned`, so `lane:stats` tells an unpinned stop apart
-// (joshuafolkken/kit#5228).
-interface PreDetachResult extends JoshResult {
+// (joshuafolkken/kit#5228), and the path that `unpinned` stop took.
+interface PreDetachResult extends PinnedResult {
 	preconditions?: ReadonlyArray<string>
 }
 
@@ -173,11 +179,14 @@ function red_kinds(result: JoshResult, pinned: JoshResult): ReadonlyArray<string
 }
 
 // The pinned check's stop joins the others' rather than hiding them.
-function with_pinned(result: JoshResult, pinned: JoshResult): PreDetachResult {
+function with_pinned(result: JoshResult, pinned: PinnedResult): PreDetachResult {
 	const preconditions = red_kinds(result, pinned)
-	const answer = joined(result, pinned)
+	const { code, out } = joined(result, pinned)
+	const { unpinned } = pinned
+
+	if (preconditions.length === 0) return { code, out }
 
-	return preconditions.length === 0 ? answer : { ...answer, preconditions }
+	return { code, out, preconditions, ...(unpinned !== undefined && { unpinned }) }
 }
 
 // All run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
@@ -213,5 +222,5 @@ const run_ship_pre_detach = {
 	with_pinned,
 }
 
-export type { PinnedCheck, PreDetachCheck, PreDetachResult }
+export type { PinnedCheck, PinnedResult, PreDetachCheck, PreDetachResult }
 export { run_ship_pre_detach }