@joshuafolkken/kit 1.1128.0 → 1.1166.0

package/scripts/run/run-carry-conversation.ts

@@ -0,0 +1,94 @@
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { own_session } from '#scripts/cost-runtime/own-session'
+import type { CarryOwner, RunCarry } from './run-carry'
+
+// **A conversation outlives its process, so an owner named by a pid alone dies too early**
+// (joshuafolkken/kit#3137). The carry record names the agent process spending the budget, and that is
+// right while the process lives — but an interactive conversation is not its process. On 2026-10-04 a
+// VS Code extension-host restart ended the session's process at 15:17:34 UTC, and the same
+// conversation resumed eighteen seconds later in a new process (`--resume=<id>`), writing on into the
+// same transcript. `run:wake` read the old pid as dead, recovered the record as a crash, and dispatched
+// a second lane child for the issue the conversation was still running.
+//
+// **The transcript is what persists across the restart, so it is the second half of the identity.**
+// Every resume path — the extension's `--resume=<id>`, a person's `claude -c` — appends to the one
+// file named by the session id, and nothing else writes it. So a record also names its owner's
+// transcript, and a dead pid whose transcript was written inside the quiet window below is a
+// conversation still being continued rather than a crash. Matching the transcript is also how the
+// resumed conversation is recognized as the record's own owner, so it can keep counting.
+//
+// **A hand-off ends the conversation's claim.** A record `--cut` handed off is waited on by the pid
+// alone, because the cutting conversation is meant to end there — counted by its transcript, the
+// supervisor would hold every cut for the whole window after the cutting process had already exited.
+
+// How long after its last write a conversation whose process has gone still counts as continuing. It
+// bridges a restart and a resume — measured at eighteen seconds — with room for a person reopening a
+// window, and it is the order of the wake grace window, so a genuine crash is recovered no later than
+// a lost wake would be retried.
+const CONVERSATION_QUIET_MS = 600_000
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+// The calling session's own transcript, or `undefined` outside a session or when its file cannot be
+// found. **The id comes from the environment, which a detached supervisor never inherits**
+// (`agent-session-environment.ts` strips it), so a record the supervisor adopts names no transcript.
+function own_transcript(
+	environment: Environment = process.env,
+	directories: ReadonlyArray<string> = cost_transcript.transcript_directories(process.cwd()),
+): string | undefined {
+	const session_id = own_session.session_id_of(environment)
+
+	if (session_id === undefined) return undefined
+
+	const name = `${session_id}${cost_transcript.TRANSCRIPT_EXTENSION}`
+
+	return directories.map((directory) => path.join(directory, name)).find((file) => existsSync(file))
+}
+
+function modified_ms(transcript: string): number | undefined {
+	try {
+		return statSync(transcript).mtimeMs
+	} catch {
+		return undefined
+	}
+}
+
+function is_recent(modified: number | undefined, now: Date): boolean {
+	return modified !== undefined && now.getTime() - modified <= CONVERSATION_QUIET_MS
+}
+
+function is_conversation_live(
+	carry: RunCarry,
+	now: Date = new Date(),
+	read_modified: (transcript: string) => number | undefined = modified_ms,
+): boolean {
+	if (carry.is_handed_off === true || carry.owner_transcript === undefined) return false
+
+	return is_recent(read_modified(carry.owner_transcript), now)
+}
+
+function is_same_conversation(carry: RunCarry, owner: CarryOwner): boolean {
+	return owner.transcript !== undefined && owner.transcript === carry.owner_transcript
+}
+
+// The record with its owner moved to the caller's process when the caller is the same conversation in
+// a new one, so the record goes on naming a live process once the conversation falls quiet. A record a
+// cut handed off is the successor's to take, never the cutting conversation's to take back.
+function reclaim_owner(carry: RunCarry, owner: CarryOwner): RunCarry {
+	if (carry.is_handed_off === true || !is_same_conversation(carry, owner)) return carry
+	if (owner.pid === carry.owner_pid) return carry
+
+	return { ...carry, owner_pid: owner.pid, owner_start: owner.start }
+}
+
+const run_carry_conversation = {
+	CONVERSATION_QUIET_MS,
+	own_transcript,
+	is_conversation_live,
+	is_same_conversation,
+	reclaim_owner,
+}
+
+export { run_carry_conversation }

package/scripts/run/run-carry-reclaim.ts

@@ -0,0 +1,37 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_carry, type CarryOwner } from './run-carry'
+import { run_carry_conversation } from './run-carry-conversation'
+
+// **A resumed conversation has to take its record back before it falls quiet** (joshuafolkken/kit#3137).
+// A count moves the owner to the conversation's new process, but a parent waiting on a lane child
+// counts nothing — `lane:await` blocks in the background and the transcript stays unwritten — so a
+// restart followed by a long wait outlasts the quiet window with the record still naming the dead
+// process, and `run:wake` recovers it as a crash. The wait itself is therefore where the parent
+// declares its owner: `lane:await --owner "$PPID"` reclaims the record before it starts waiting.
+
+// Writes the record back under the caller's process when the caller is the record's own conversation
+// in a new one; answers whether it did.
+function reclaim_at(target: string, owner: CarryOwner): boolean {
+	const read = run_carry.read_carry(target)
+
+	if (read.kind !== 'carried') return false
+
+	const reclaimed = run_carry_conversation.reclaim_owner(read.carry, owner)
+
+	if (reclaimed === read.carry) return false
+
+	// Replaced atomically: a `run:wake` reading between an unlink and a write would see no record.
+	stamp_file.replace_stamp(target, reclaimed)
+
+	return true
+}
+
+async function reclaim_carry(owner: CarryOwner): Promise<boolean> {
+	const directory = await run_carry.repository_directory()
+
+	return directory !== undefined && reclaim_at(run_carry.carry_path(directory), owner)
+}
+
+const run_carry_reclaim = { reclaim_at, reclaim_carry }
+
+export { run_carry_reclaim }

package/scripts/run/run-carry.ts

@@ -4,6 +4,7 @@ import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { z } from 'zod'
 import { run_carry_change } from './run-carry-change'
+import { run_carry_conversation } from './run-carry-conversation'
 import { run_invocation } from './run-invocation'
 
 // joshuafolkken/kit#1714: a `backlogrun` declares a budget — `--max`, `--idle` and the 8-hour
@@ -106,6 +107,9 @@ interface RunCarry {
 	// them apart would be asserting a distinction nothing here can observe.
 	owner_pid?: number | undefined
 	owner_start?: string | undefined
+	// The owner conversation's transcript, which outlives a restart of its process
+	// (`run-carry-conversation.ts`, joshuafolkken/kit#3137). Optional for the same reason as the pid.
+	owner_transcript?: string | undefined
 	// Set by `--cut`, and by nothing else. A crash never reaches `--cut`, which is what makes a
 	// declared cut the only standing record carried without a person deciding.
 	is_handed_off?: boolean | undefined
@@ -129,10 +133,12 @@ interface RunCarry {
 }
 
 // The identity of a process, as `process-identity.ts` keeps it: the pid plus an opaque start-time
-// token, so a reissued pid is never mistaken for the process that wrote the record.
+// token, so a reissued pid is never mistaken for the process that wrote the record — and the
+// transcript of the conversation that process runs, which outlives it (`run-carry-conversation.ts`).
 interface CarryOwner {
 	pid?: number | undefined
 	start?: string | undefined
+	transcript?: string | undefined
 }
 
 // **`resume` is the only one of the four that establishes anything.** The other three are refusals,
@@ -201,6 +207,7 @@ const run_carry_schema = z.object({
 	// which is the not-provably-live answer rather than a live one.
 	owner_pid: z.number().optional(),
 	owner_start: z.string().optional(),
+	owner_transcript: z.string().optional(),
 	is_handed_off: z.boolean().optional(),
 	done: z.array(z.number()).optional(),
 	// Optional, so a record written before the retrospective existed still parses (joshuafolkken/kit#2328).
@@ -256,12 +263,14 @@ function read_carry(target: string, now: Date = new Date()): CarryRead {
 
 // The identity to record for a pid the caller declared. `read_start` is what makes the pair an
 // identity rather than a number; injected in tests so the sandbox branch is exercised without
-// changing the machine's process capabilities.
+// changing the machine's process capabilities. The transcript is the calling session's own — the
+// declared pid is that session's process (`--owner "$PPID"`).
 function owner_of(
 	pid: number,
 	read: (owner_pid: number) => string | undefined = process_identity.read_start,
+	transcript: string | undefined = run_carry_conversation.own_transcript(),
 ): CarryOwner {
-	return { pid, start: read(pid) }
+	return { pid, start: read(pid), transcript }
 }
 
 function fresh_carry(invocation: string, owner: CarryOwner, now: Date): RunCarry {
@@ -275,6 +284,7 @@ function fresh_carry(invocation: string, owner: CarryOwner, now: Date): RunCarry
 		outages: NO_INCREMENT,
 		owner_pid: owner.pid,
 		owner_start: owner.start,
+		owner_transcript: owner.transcript,
 	}
 }
 
@@ -329,6 +339,7 @@ function adopt_carry(
 		...carry,
 		owner_pid: owner.pid,
 		owner_start: owner.start,
+		owner_transcript: owner.transcript,
 		is_handed_off: false,
 	}
 
@@ -340,11 +351,16 @@ function adopt_carry(
 // A live pid with no readable start token is conservatively held rather than replaced. The command
 // cannot prove its generation inside that sandbox, but a false `busy` stops for a person while a
 // false `standing` can put two parents on one budget. A record with no pid still resolves false.
-function is_owner_live(carry: RunCarry): boolean {
-	return process_identity.is_same_process(carry.owner_pid, carry.owner_start) !== false
+// A gone process whose conversation is still being continued is live (`run-carry-conversation.ts`).
+function is_owner_live(carry: RunCarry, now: Date = new Date()): boolean {
+	if (process_identity.is_same_process(carry.owner_pid, carry.owner_start) !== false) return true
+
+	return run_carry_conversation.is_conversation_live(carry, now)
 }
 
 function is_owned_by(carry: RunCarry, owner: CarryOwner): boolean {
+	if (run_carry_conversation.is_same_conversation(carry, owner)) return true
+
 	return carry.owner_pid === owner.pid && carry.owner_start === owner.start
 }
 

package/scripts/run/run-cut-handoff.ts

@@ -41,6 +41,22 @@ const UNTOUCHED_LABEL = 'Deliberately untouched'
 const INSTRUCTION_LABEL = 'Instruction (verbatim)'
 const EMPTY_LIST_NOTE = '(none)'
 
+type HandoffKey = keyof Handoff
+
+function describe_key(key: HandoffKey): string {
+	const value = handoff_schema.shape[key] instanceof z.ZodArray ? '["…"]' : '"…"'
+
+	return `"${key}": ${value}`
+}
+
+// The shape a handoff file must have, derived from `handoff_schema` so the refusal that asks for the file
+// and the error that rejects it can never name a key the parser does not read (joshuafolkken/kit#3195).
+// A refusal that listed the four items in prose was answered with Markdown, which `parse_handoff` rejects.
+const HANDOFF_FORMAT = `a JSON object {${handoff_schema
+	.keyof()
+	.options.map((key) => describe_key(key))
+	.join(', ')}}`
+
 function parse_handoff(raw: string): Handoff | undefined {
 	try {
 		const parsed = handoff_schema.safeParse(JSON.parse(raw))
@@ -84,7 +100,10 @@ function load_handoff(handoff_path: string | undefined, max_bytes: number): Hand
 	const handoff = read_handoff_file(handoff_path)
 
 	if (handoff === undefined) {
-		return { kind: 'bad', note: `--handoff ${handoff_path} is not a readable handoff file` }
+		return {
+			kind: 'bad',
+			note: `--handoff ${handoff_path} is not a readable handoff file — write ${HANDOFF_FORMAT}`,
+		}
 	}
 
 	if (!is_within_bound(handoff, max_bytes)) {
@@ -114,6 +133,7 @@ function describe_handoff(handoff: Handoff): string {
 }
 
 const run_cut_handoff = {
+	HANDOFF_FORMAT,
 	describe_handoff,
 	handoff_schema,
 	is_complete_handoff,

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

@@ -7,6 +7,7 @@ import { run_entry, type EntryParts } from './run-entry'
 import { run_entry_stop } from './run-entry-stop'
 import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_hold_cli } from './run-hold-cli'
+import { run_label } from './run-label'
 import { run_next } from './run-next'
 import { run_prep } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
@@ -231,6 +232,15 @@ function is_settled(decision: StageDecision): boolean {
 	return decision.is_reached && decision.state !== run_stage.MERGED
 }
 
+// The tree is held and the budget allows the run, so the issue is marked as running before its reads
+// (joshuafolkken/kit#3182) — the label then shows in the `labels:` line the report below carries.
+async function proceed(issue_number: string, hold: string, cost: string): Promise<number> {
+	await run_label.mark(issue_number)
+	const reads = await gather_reads(issue_number)
+
+	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+}
+
 async function claim_run({ issue_number, command }: EntryRequest): Promise<number> {
 	const hold = await claim_hold(issue_number, command)
 
@@ -248,9 +258,7 @@ async function claim_run({ issue_number, command }: EntryRequest): Promise<numbe
 		return await stop_run({ parts, command, reason: BUDGET_REASON, should_release: true })
 	}
 
-	const reads = await gather_reads(issue_number)
-
-	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+	return await proceed(issue_number, hold, cost)
 }
 
 // A carried cut is asked first, before anything is read (`run:cut --resume`); `kickoff` claims and cuts

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

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
+import { run_label } from './run-label'
 import { run_preflight, type PreflightDecision } from './run-preflight'
 import { run_prrun_resume } from './run-prrun-resume'
 import { run_tidy_cli } from './run-tidy-cli'
@@ -267,7 +268,7 @@ function report_unreadable_release(): number {
 // Until then this removed whatever was there, and the `busy` stop message sent a person here to clear
 // a record they had judged stale from outside the run that wrote it — so the guard's own recovery
 // instruction was a way to free a live run's tree, which is the incident it was written after.
-function release(target: string, claimant: string): number {
+function release_record(target: string, claimant: string): number {
 	const read = run_hold.read_hold(target)
 
 	if (read.kind === 'free') return remove_record(target, false)
@@ -279,6 +280,19 @@ function release(target: string, claimant: string): number {
 	return remove_record(target, true)
 }
 
+// **A numbered run's own release takes its `in-progress` marker back off** (joshuafolkken/kit#3182),
+// whether or not a record was still there — the stop that releases is the run ending its hold on the
+// issue. A refused release (another run's record, an unreadable one) touches no label, and an
+// unnumbered run names no issue to touch.
+async function release(target: string, claimant: string): Promise<number> {
+	const code = release_record(target, claimant)
+	const is_own_end = code === SUCCESS_EXIT_CODE && claimant !== run_hold.UNNUMBERED_ISSUE
+
+	if (is_own_end) await run_label.unmark(claimant)
+
+	return code
+}
+
 // The one path that removes a record without matching it, which is why it says what it removed: a
 // record genuinely abandoned by a crashed session has no run left to release it, and the eight-hour
 // expiry alone leaves a dirty tree held until a person acts.
@@ -335,7 +349,7 @@ async function dispatch(request: HoldRequest, target: string, is_linked: boolean
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
 
-	return release(target, request.claimant)
+	return await release(target, request.claimant)
 }
 
 async function answer(request: HoldRequest): Promise<number> {

package/scripts/run/run-label.ts

@@ -0,0 +1,50 @@
+import { git_followup_label } from '#scripts/followup/git-followup-label'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+
+// **The `in-progress` marker belongs to the commands that open and release a run**
+// (joshuafolkken/kit#3182). Every manifest used to spell the label's create, apply and removal as raw
+// `gh api` calls, so each copy was a place the marker could be forgotten; `run:entry` applies it the
+// moment the tree is held and the budget allows the run, and `run:release` takes it back off.
+//
+// **Neither half ever fails the command it rides on.** The hold is the guard and the label only
+// reports it, so a refused write is warned about by name — with the call that finishes it by hand —
+// and the run's own verdict stands.
+
+const MARK_RECOVERY = "gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=in-progress'"
+const UNMARK_RECOVERY = 'gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress'
+
+function warn(action: string, issue: string, recovery: string): void {
+	console.warn(`⚠ could not ${action} \`in-progress\` on #${issue} — run by hand: ${recovery}`)
+}
+
+// `issue_add_label` creates the label when the repository lacks it (`lane-dispatch.ts`), so no
+// separate provisioning call is made here.
+async function mark(issue: string): Promise<boolean> {
+	const is_marked = await git_gh_command.issue_add_label(issue, IN_PROGRESS_LABEL)
+
+	if (!is_marked) warn('apply', issue, MARK_RECOVERY)
+
+	return is_marked
+}
+
+// The removal is `followup`'s own — read first, removed only when present, under the stored
+// casing — so an issue that never carried the label is never written to.
+async function unmark(issue: string): Promise<boolean> {
+	try {
+		await git_followup_label.strip_in_progress(issue)
+
+		return true
+	} catch {
+		warn('remove', issue, UNMARK_RECOVERY)
+
+		return false
+	}
+}
+
+const run_label = {
+	mark,
+	unmark,
+}
+
+export { run_label }

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

@@ -10,6 +10,7 @@ import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { run_carry, type CarryChange, type CarryOwner, type RunCarry } from './run-carry'
+import { run_carry_conversation } from './run-carry-conversation'
 import { run_cut, type RunCut } from './run-cut'
 import { run_merge } from './run-merge'
 
@@ -47,7 +48,10 @@ interface MergeContext {
 	child: string
 	epic: string | undefined
 	repo: string | undefined
-	over: number
+	// The hand-off threshold, or `undefined` where no AI session owns the loop — the supervisor's
+	// `backlog:drive` has no context to cut, so a merge there is never handed back as `over`
+	// (joshuafolkken/kit#3156).
+	over: number | undefined
 	owner: CarryOwner
 	// The child's transcript output path, when the caller passed `--output`. Read to tell an API-outage
 	// ending apart from a genuine child failure (joshuafolkken/kit#2240); absent leaves outage detection
@@ -105,7 +109,9 @@ async function apply_carry(
 		return { kind: 'refused', carry: record.carry }
 	}
 
-	return { kind: 'applied', carry: run_carry.apply_change(record.target, record.carry, change) }
+	const owned = run_carry_conversation.reclaim_owner(record.carry, ctx.owner)
+
+	return { kind: 'applied', carry: run_carry.apply_change(record.target, owned, change) }
 }
 
 // The carry record when this session may not act on it — the same ownership guard `apply_carry` asks —
@@ -324,8 +330,10 @@ async function resume_cut(child: string): Promise<boolean> {
 }
 
 // The hand-off check, asked at a merge alone. A subprocess that cannot measure exits non-zero, which
-// is read as `over` — "could not measure" is never "still cheap".
-async function is_over_budget(over: number): Promise<boolean> {
+// is read as `over` — "could not measure" is never "still cheap". No threshold is no session to measure.
+async function is_over_budget(over: number | undefined): Promise<boolean> {
+	if (over === undefined) return false
+
 	const result = await josh(['cost', '--over', String(over)])
 
 	return result.code !== 0 || result.out === OVER

package/scripts/run/run-merge.ts

@@ -35,7 +35,7 @@ const ONE = 1
 // - `merged`      — CLOSED; the child finished and its pull request merged. Also an OPEN, unparked
 //                   child a merged pull request's `closes #N` names — GitHub merged it without closing
 //                   the issue (joshuafolkken/kit#2769).
-// - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (SKILL.md → §2z).
+// - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (needs-human-review.md).
 // - `parked`      — OPEN and carrying `needs-decision` or `already-done`; a person still owns it.
 // - `split`       — OPEN and carrying `epic`; its work was divided into new children.
 // - `outage`      — OPEN and carrying neither, but the exit record shows it could not reach the API; not

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

@@ -8,6 +8,7 @@ import { error_text } from '#scripts/lib/error-message'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_locate } from './run-prep-locate'
+import { run_ship_preflight } from './run-ship-preflight'
 
 // `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit
 // (joshuafolkken/kit#1978): the issue body and comments (`issue:read`), the state, labels and
@@ -41,6 +42,7 @@ interface PrepReads {
 	latest: LatestDecision
 	has_changes: boolean
 	locations: string
+	ship_problems: ReadonlyArray<string>
 }
 
 // Exactly one issue number, or the call is refused: `run:prep` prepares one run, and a second number
@@ -91,15 +93,16 @@ async function lane_has_changes(): Promise<boolean> {
 }
 
 async function gather(issue_number: string): Promise<PrepReads> {
-	const [content, state, has_changes] = await Promise.all([
+	const [content, state, has_changes, ship_problems] = await Promise.all([
 		issue_read_cli.read_block(issue_number),
 		issue_state_cli.read_issue(issue_number),
 		lane_has_changes(),
+		run_ship_preflight.ahead(issue_number),
 	])
 	// Located from the body just read, so it waits for that read rather than joining the batch above.
 	const locations = await run_prep_locate.locate(content.kind === 'ok' ? content.block : '')
 
-	return { content, state, latest: latest_decision(), has_changes, locations }
+	return { content, state, latest: latest_decision(), has_changes, locations, ship_problems }
 }
 
 function content_body(issue_number: string, content: BlockRead): string {
@@ -119,6 +122,7 @@ function to_parts(issue_number: string, reads: PrepReads): PrepParts {
 		latest_reason: reads.latest.reason,
 		has_changes: reads.has_changes,
 		locations: reads.locations,
+		ship_problems: reads.ship_problems,
 	}
 }
 

package/scripts/run/run-prep.ts

@@ -24,6 +24,10 @@ const CONTENT_HEADER = '=== issue ==='
 const STATE_HEADER = '=== state ==='
 const LATEST_HEADER = '=== dependency update ==='
 const LOCATIONS_HEADER = '=== code locations ==='
+const SHIP_HEADER = '=== ship preconditions ==='
+const SHIP_MET = 'met — nothing `josh ship` refuses on as the tree stands'
+const SHIP_UNMET =
+	'unmet — `josh ship` will refuse until these are fixed; fix them before the gate:'
 const SECTION_SEPARATOR = '\n\n'
 const LATEST_JOINER = ' — '
 
@@ -41,6 +45,9 @@ interface PrepParts {
 	// Whether a lane child's tree holds uncommitted work — read for the verdict, not printed in the
 	// report (joshuafolkken/kit#2476).
 	has_changes: boolean
+	// What `josh ship` would refuse on as the tree stands — `run_ship_preflight.ahead`
+	// (joshuafolkken/kit#3154).
+	ship_problems: ReadonlyArray<string>
 }
 
 function human_review_value(state: IssueState | undefined): string {
@@ -72,6 +79,12 @@ function section(header: string, body: string): string {
 	return `${header}\n${body}`
 }
 
+function ship_body(problems: ReadonlyArray<string>): string {
+	if (problems.length === 0) return SHIP_MET
+
+	return [SHIP_UNMET, ...problems.map((problem) => `  - ${problem}`)].join('\n')
+}
+
 function format_report(parts: PrepParts): string {
 	return [
 		summary(parts),
@@ -79,6 +92,7 @@ function format_report(parts: PrepParts): string {
 		section(STATE_HEADER, state_body(parts)),
 		section(LATEST_HEADER, `${parts.latest_scope}${LATEST_JOINER}${parts.latest_reason}`),
 		section(LOCATIONS_HEADER, parts.locations),
+		section(SHIP_HEADER, ship_body(parts.ship_problems)),
 	].join(SECTION_SEPARATOR)
 }
 
@@ -86,9 +100,12 @@ const run_prep = {
 	CONTENT_HEADER,
 	LATEST_HEADER,
 	LOCATIONS_HEADER,
+	SHIP_HEADER,
+	SHIP_UNMET,
 	STATE_HEADER,
 	SUMMARY_PREFIX,
 	format_report,
+	ship_body,
 }
 
 export type { PrepParts }

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises'
 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'
@@ -22,6 +23,7 @@ import { run_ship_scoped } from './run-ship-scoped'
 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>.`
+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.`
 
 interface PreflightRequest {
 	title: string
@@ -34,13 +36,20 @@ async function body_text(body_path: string | undefined): Promise<string | undefi
 	return await git_gh_command.pr_get_body(await git_branch.current())
 }
 
-async function evidence_problems(body_path: string | undefined): Promise<Array<string>> {
+// `no_body_problem` answers a runtime change with no body to read at all — no `--body-file` and no open
+// PR, which is every run before its ship opens one.
+async function evidence_problems(
+	body_path: string | undefined,
+	no_body_problem: string = EVIDENCE_PROBLEM,
+): Promise<Array<string>> {
 	const [paths, body] = await Promise.all([
 		changed_paths.read_changed_paths(false),
 		body_text(body_path),
 	])
 
-	return live_evidence.verdict_for(paths, body) === 'required' ? [EVIDENCE_PROBLEM] : []
+	if (live_evidence.verdict_for(paths, body) !== 'required') return []
+
+	return [body === undefined ? no_body_problem : EVIDENCE_PROBLEM]
 }
 
 function refusal(problems: ReadonlyArray<string>): JoshResult {
@@ -81,7 +90,29 @@ async function stage(request: PreflightRequest): Promise<JoshResult> {
 	return scoped.code === SUCCESS_EXIT_CODE ? { code: SUCCESS_EXIT_CODE, out: 'ready' } : scoped
 }
 
-const run_ship_preflight = { EVIDENCE_PROBLEM, stage }
+async function classification_problems(issue_number: string): Promise<Array<string>> {
+	await git_pr.release_classification(issue_number, await git_branch.current())
+
+	return []
+}
+
+// **The same two refusals, asked before the ship rather than by it** (joshuafolkken/kit#3154). In one
+// measured backlogrun 20 of 41 lane `ship` refusals were a missing classification or missing evidence —
+// facts fixed long before the ship, refused 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.
+async function ahead(issue_number: string): Promise<Array<string>> {
+	const [classification, evidence] = await Promise.all([
+		caught(classification_problems(issue_number)),
+		caught(evidence_problems(undefined, EVIDENCE_PENDING)),
+	])
+
+	return [...classification, ...evidence]
+}
+
+const run_ship_preflight = { EVIDENCE_PENDING, EVIDENCE_PROBLEM, ahead, stage }
 
 export type { PreflightRequest }
 export { run_ship_preflight }

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

@@ -155,7 +155,7 @@ async function record_and_route(
 	if (recorded.code !== SUCCESS_EXIT_CODE) return recorded
 
 	const outcome = outcome_of(verdict)
-	const out = [...verdict.specs, outcome.note].join('\n')
+	const out = [...verdict.report, outcome.note].join('\n')
 
 	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
 }