@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/run/run-prep.ts

@@ -1,3 +1,4 @@
+import { delegation_policy } from '#scripts/delegation/delegation-policy'
 import { issue_state, type IssueState } from '#scripts/issue/issue-state'
 
 // `josh run:prep <N>` — the reads a `fullrun` makes before its first edit, assembled into one report.
@@ -22,6 +23,9 @@ const CONTENT_HEADER = '=== issue ==='
 const STATE_HEADER = '=== state ==='
 const LATEST_HEADER = '=== dependency update ==='
 const LOCATIONS_HEADER = '=== code locations ==='
+const INVESTIGATION_HEADER = '=== investigation ==='
+// The step the investigation guard would otherwise name only once it refuses, mid-reading (#4345).
+const INVESTIGATION_BODY = `Delegate before the first read — the guard refuses at ${delegation_policy.INVESTIGATION_LIMIT}. ${delegation_policy.INVESTIGATION_STEP} Brief it with the code locations above; read in the main line only the files this run will edit.`
 const SHIP_HEADER = '=== ship preconditions ==='
 const SHIP_MET = 'met — nothing `josh ship` refuses on as the tree stands'
 const SHIP_UNMET =
@@ -89,12 +93,14 @@ 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(INVESTIGATION_HEADER, INVESTIGATION_BODY),
 		section(SHIP_HEADER, ship_body(parts.ship_problems)),
 	].join(SECTION_SEPARATOR)
 }
 
 const run_prep = {
 	CONTENT_HEADER,
+	INVESTIGATION_HEADER,
 	LATEST_HEADER,
 	LOCATIONS_HEADER,
 	SHIP_HEADER,

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

@@ -1,12 +1,17 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { git_followup_pending } from '#scripts/followup/git-followup-pending'
+import { session_cite } from '#scripts/issue/session-cite'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { release_scope_cli } from '#scripts/release/release-scope-cli'
-import { run_carry } from '#scripts/run/carry/run-carry'
+import { report_labels } from '#scripts/report/report-labels'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_scope, type EventScope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_report } from './run-report'
+import { run_report_handoff, type Handoff } from './run-report-handoff'
 
 // `josh run:report` — the session-facing report, generated from the run's event stream rather than
 // composed by hand. It reads the events the run appended, asks `release:scope`
@@ -18,8 +23,23 @@ import { run_report } from './run-report'
 // **The body it prints is the Telegram body too.** `josh notify --body-file <file>` sends exactly this
 // output, so the summary a session shows and the message a person reads off-screen are one string from one
 // generator, never a second wording of the same facts.
+//
+// `--handoff` prints the `backlogrun` hand-off report (`run-report-handoff.ts`) from the same reads —
+// the run record and the scoped stream — and sends it itself as the `confirmation`, the resume command
+// as its `recommended` choice (joshuafolkken/kit#4161). The body is built with plain `#N` and linked
+// here, at the print boundary, through `session_cite.text`.
 
+const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const HANDOFF_FLAG = '--handoff'
+const USAGE = `Usage: josh run:report [${HANDOFF_FLAG}]`
+const NO_RECORD_NOTE =
+	'No readable run record, so there is no run to hand off. Begin one with `pnpm josh run:carry --begin` first.'
+const HANDOFF_TITLE = 'backlogrun hand-off'
+const HANDOFF_RECOVERY = 'If this did not arrive, the session transcript holds the same report.'
+const NO_RESUME_NOTE =
+	'The run record names no resume command, so no hand-off confirmation was sent; the report above is the hand-off.'
 
 // An absent or unreadable stream is an empty run, the same fail-quiet direction the stream's own reader
 // takes — a report with no events is a report, not an error.
@@ -31,40 +51,108 @@ async function read_stream(): Promise<ReadonlyArray<RunEvent>> {
 	return run_event_stream.read_events(target)
 }
 
+// The run record this checkout holds, or `undefined` when the git directory cannot be resolved.
+async function read_record(): Promise<CarryRead | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return undefined
+
+	return run_carry.read_carry(run_carry.carry_path(directory))
+}
+
 // The invocation this report covers, taken from the run record that already holds the start time.
 // A checkout whose git directory cannot be resolved has no record to read, which is the same
 // undetermined answer an absent record gives — and neither one falls back to the whole stream.
-async function read_scope(): Promise<EventScope> {
-	const directory = await run_carry.repository_directory()
+function scope_of(read: CarryRead | undefined): EventScope {
+	if (read === undefined) return run_event_scope.UNKNOWN_EVENT_SCOPE
 
-	if (directory === undefined) return run_event_scope.UNKNOWN_EVENT_SCOPE
-
-	return run_event_scope.scope_of(run_carry.read_carry(run_carry.carry_path(directory)))
+	return run_event_scope.scope_of(read)
 }
 
 // The three reads are independent, so they are issued together rather than one after another — the stream, the
 // pending-merge count and the run record share no input.
-async function run(): Promise<number> {
-	const [events, pending, scope] = await Promise.all([
+async function run_summary(): Promise<number> {
+	const [events, pending, read] = await Promise.all([
 		read_stream(),
 		git_followup_pending.read_pending({}),
-		read_scope(),
+		read_record(),
 	])
 	const release = release_scope_cli.decide(pending)
 
-	process.stdout.write(`${run_report.build_report({ events, release, scope })}\n`)
+	process.stdout.write(`${run_report.build_report({ events, release, scope: scope_of(read) })}\n`)
 
 	return SUCCESS_EXIT_CODE
 }
 
-async function main(): Promise<void> {
-	process.exitCode = await run()
+type CarriedRead = Extract<CarryRead, { kind: 'carried' }>
+
+// The report is the hand-off, so it succeeds once printed. The send is `confirm`'s tolerant one, which
+// already reports its own failure with `HANDOFF_RECOVERY` — a checkout with no Telegram credentials is
+// one, and pointing it at `josh notify` would fail the same way. A record whose invocation names no
+// resume command has no `recommended` to send.
+async function send_handoff(handoff: Handoff): Promise<void> {
+	if (handoff.resume === undefined) {
+		console.error(NO_RESUME_NOTE)
+
+		return
+	}
+
+	await telegram_notify.confirm({
+		issue_title: HANDOFF_TITLE,
+		body: handoff.body,
+		recovery: HANDOFF_RECOVERY,
+		recommended: handoff.resume,
+		alternatives: [],
+	})
+}
+
+function handoff_of(read: CarriedRead, events: ReadonlyArray<RunEvent>): Handoff {
+	return run_report_handoff.build_handoff({
+		carry: read.carry,
+		events: run_event_scope.scoped_events(events, scope_of(read)) ?? [],
+		figures: cost_cli.session_figures(),
+		labels: report_labels.session_labels(),
+	})
+}
+
+async function run_handoff(): Promise<number> {
+	const [events, read] = await Promise.all([read_stream(), read_record()])
+
+	if (read?.kind !== 'carried') {
+		console.error(NO_RECORD_NOTE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const built = handoff_of(read, events)
+	const handoff = { ...built, body: session_cite.text(built.body) }
+
+	process.stdout.write(`${handoff.body}\n`)
+	await send_handoff(handoff)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string> = []): Promise<number> {
+	if (argv.length === 0) return await run_summary()
+	if (argv.length === 1 && argv[0] === HANDOFF_FLAG) return await run_handoff()
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
 }
 
 const run_report_cli = {
+	NO_RECORD_NOTE,
+	NO_RESUME_NOTE,
+	USAGE,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
 export { run_report_cli }

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

@@ -0,0 +1,114 @@
+import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
+import type { SessionFigures } from '#scripts/cost-runtime/cost-cli'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { HandoffLabels, ReportLabels } from '#scripts/report/report-labels'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_invocation } from '#scripts/run/run-invocation'
+
+// `josh run:report --handoff` — the report a `backlogrun` writes when it hands the rest of a batch to a
+// new session, generated from the values that already answer each line rather than filled in by hand:
+// the run record (`run:carry`) names what merged, what is left and the command that resumes the run,
+// the invocation's events name what parked, and `cost --cut`'s figures name why it stopped. **The
+// hand-off is a fourth kind of stop**, so it carries the hand-off labels and never the completion
+// report's `cause` / `fix` / `result` — an unfinished epic would read as finished.
+//
+// **The body is the Telegram body too**, as `run:report`'s is: the CLI prints it and sends it as the
+// `confirmation`, the resume command as its `recommended` choice.
+
+const LINE_SEPARATOR = '\n'
+const LIST_SEPARATOR = ', '
+const COST_COMMAND = '`pnpm josh cost --cut`'
+
+interface HandoffInput {
+	carry: RunCarry
+	// This invocation's events, already scoped by `run-event-scope.ts`.
+	events: ReadonlyArray<RunEvent>
+	figures: SessionFigures
+	labels: ReportLabels
+}
+
+interface Handoff {
+	body: string
+	// The command that resumes the run, or `undefined` for a record whose invocation does not parse.
+	resume: string | undefined
+}
+
+function issue_list(issues: ReadonlyArray<number>, labels: HandoffLabels): string {
+	if (issues.length === 0) return labels.none
+
+	return issues.map((issue) => issue_cite.plain(issue)).join(LIST_SEPARATOR)
+}
+
+// The children that parked in this invocation and never merged — named apart from the remaining list,
+// because a parked child is settled for this run but is not done.
+function parked_of(input: HandoffInput): ReadonlyArray<number> {
+	const merged = input.carry.merged_issues ?? []
+
+	return [...backlog_drive_restore.parked_issues(input.events)].filter(
+		(issue) => !merged.includes(issue),
+	)
+}
+
+// **Never omitted**: it is the one line that tells this report from a completion report. A budget-only
+// invocation named no list, so what is left is the pool rather than a count.
+function remaining_line(input: HandoffInput, remaining: ReadonlyArray<number> | undefined): string {
+	const labels = input.labels.handoff
+	const parked = parked_of(input)
+	const listed = remaining === undefined ? labels.pool : issue_list(remaining, labels)
+	const count = remaining === undefined ? '' : ` (${String(remaining.length)})`
+	const parked_note =
+		parked.length === 0 ? '' : ` · ${labels.parked}: ${issue_list(parked, labels)}`
+
+	return `${listed}${count}${parked_note}`
+}
+
+// An unmeasurable session quotes its verdict where the cost would be, never a `0`.
+function measurement_line(figures: SessionFigures): string {
+	const cost = figures.cost === undefined ? figures.verdict : String(figures.cost)
+
+	return `${cost} / ${String(figures.threshold)}`
+}
+
+function command_line(resume: string | undefined, labels: HandoffLabels): string {
+	return resume === undefined ? labels.none : `\`${resume}\``
+}
+
+function body_lines(
+	input: HandoffInput,
+	handoff_resume: string | undefined,
+): ReadonlyArray<string> {
+	const labels = input.labels.handoff
+	const remaining = run_carry.remaining_of(input.carry)
+
+	return [
+		`**${labels.title}**`,
+		'',
+		`- **${labels.done}**: ${issue_list(input.carry.merged_issues ?? [], labels)}`,
+		`- **${labels.remaining}**: ${remaining_line(input, remaining)}`,
+		`- **${labels.why_stopped}**: ${COST_COMMAND} → ${input.figures.verdict}`,
+		`- **${labels.next_command}**: ${command_line(handoff_resume, labels)}`,
+		'',
+		`**${input.labels.details}**`,
+		'',
+		`- ${labels.measurement}: ${measurement_line(input.figures)}`,
+		`- ${labels.handover}: ${labels.handover_text}`,
+	]
+}
+
+// Handed the same record, events and figures it returns the same report — nothing here reads a clock,
+// the environment or the network, which is what the tests pin. The resume command is the record's own
+// invocation: `run:carry` resumes a record only when the invocation matches it exactly, so a command
+// shrunk to the remaining issues would be refused and its recovery would drop the carried counts.
+function build_handoff(input: HandoffInput): Handoff {
+	const resume = run_invocation.rebuild(input.carry.invocation)
+
+	return { body: body_lines(input, resume).join(LINE_SEPARATOR), resume }
+}
+
+const run_report_handoff = {
+	build_handoff,
+}
+
+export type { Handoff, HandoffInput }
+export { run_report_handoff }

package/scripts/run/run-step.ts

@@ -271,7 +271,7 @@ function closed_action(input: StepInput): StepAction {
 
 	return {
 		kind: 'decide',
-		line: `decide: ${session_cite.issue(input.issue_number)} is closed but this tree holds uncommitted work — keep it with \`git stash push -u -m "${message}"\` | carry it into a new issue`,
+		line: `decide: ${session_cite.issue(input.issue_number)} is closed but this tree holds uncommitted work — keep it with \`pnpm josh stash:push "${message}"\` | carry it into a new issue`,
 	}
 }
 

package/scripts/run/run-stranded-detect.ts

@@ -42,6 +42,8 @@ interface DetectPorts {
 	notify_stranded: (body: string) => Promise<boolean>
 }
 
+type SameProcess = NonNullable<Parameters<typeof run_stranded.supervisor_liveness>[1]>
+
 interface RecordTargets {
 	carry: string
 	wake: string
@@ -151,6 +153,16 @@ function is_stranded_at(directory: string, ports: DetectPorts = DEFAULT_PORTS):
 	return input !== undefined && run_stranded.is_stranded(input)
 }
 
+// The default ports with both liveness probes asked through `same_process` — `run:board` hands the one
+// that reads its own `ps` snapshot (joshuafolkken/kit#4263).
+function ports_with(same_process: SameProcess): DetectPorts {
+	return {
+		...DEFAULT_PORTS,
+		is_owner_live: (carry) => run_carry.is_owner_live(carry, new Date(), same_process),
+		supervisor_liveness: (wake) => run_stranded.supervisor_liveness(wake, same_process),
+	}
+}
+
 // The judgement a supervisor asks of the run it is about to stop watching. The asker is that
 // supervisor on its way out, so it is taken as gone, and so is an owner that is the asker itself
 // (`run_carry.is_held_by_another`) — that owner is about to be gone. A
@@ -173,6 +185,7 @@ const run_stranded_detect = {
 	detect_and_report,
 	is_left_stranded,
 	is_stranded_at,
+	ports_with,
 	run_stranded_check,
 }
 

package/scripts/run/run-watcher-guard-cli.ts

@@ -9,7 +9,7 @@ import { run_watcher_guard } from './run-watcher-guard'
 // through `run-watcher-hook.ts` so every tool call is checked.
 //
 // **Exits 0 (ok) or 1 (stale).** A non-zero exit is what the hook mechanism treats as a refusal —
-// the same contract `batch:guard` and `rule:guard` hold.
+// the same contract `pretool:guard` holds.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1

package/scripts/run/run-watcher-guard.ts

@@ -1,4 +1,5 @@
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_progress_clock } from '#scripts/run/progress/run-progress-clock'
 import { run_headless } from './run-headless'
 
@@ -18,7 +19,6 @@ import { run_headless } from './run-headless'
 
 const WATCHER_TICK_MS = 30_000
 const TICK_MULTIPLIER = 3
-const MS_PER_SECOND = 1000
 
 const STALE_THRESHOLD_MS = WATCHER_TICK_MS * TICK_MULTIPLIER
 const STALE_THRESHOLD_S = STALE_THRESHOLD_MS / MS_PER_SECOND

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

@@ -0,0 +1,121 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_ship_body_draft } from './run-ship-body-draft'
+import type { ShipArguments } from './run-ship-steps'
+
+// The command line `josh ship` takes (`run-ship-cli.ts`). The first positional is the
+// `"<title> #<N>"` string `git -y` and `followup` already take; the issue number is read off its tail
+// for `run:tail`. Any further positionals are follow-up citations filed this run (`fullrun-steps.md`
+// routes branch-2 filing before `ship`), forwarded to `run:tail` after the closed issue so `issue:cite`
+// reports them too. A notify body — `--notify-message` or the shell-body-safe `--notify-message-file` —
+// is forwarded to `followup` alone; the completion prose is composed before this command and passed
+// straight through.
+
+const FIRST = 0
+const NUMBER_GROUP = 1
+const EXTRA_CITE_START = 1
+// The issue reference at the tail of the title — `git -y` and `followup` read the whole string, and
+// `run:tail` needs the number alone.
+const TRAILING_ISSUE_PATTERN = /#([1-9]\d*)\s*$/u
+// Both body forms `followup` documents, forwarded verbatim: the inline `--notify-message` and the
+// shell-body-safe `--notify-message-file` a body naming a command or path must use (`followup.md`).
+const NOTIFY_OPTIONS = ['notify-message', 'notify-message-file'] as const
+const { BODY_FILE_OPTION, body_arguments } = run_ship_body_draft
+
+type NotifyValues = Partial<Record<(typeof NOTIFY_OPTIONS)[number], string>>
+
+const OPTIONS = {
+	[NOTIFY_OPTIONS[0]]: { type: 'string' },
+	[NOTIFY_OPTIONS[1]]: { type: 'string' },
+	[BODY_FILE_OPTION]: { type: 'string' },
+	review: { type: 'boolean' },
+	// Hand the region to a detached supervisor (`run-ship-detach.ts`), print the
+	// report a stopped supervisor left, and carry follow-up citations as options so the supervisor's
+	// command line still ends with its title.
+	detach: { type: 'boolean' },
+	log: { type: 'string' },
+	cite: { type: 'string', multiple: true },
+} as const
+
+type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number: string }
+
+// The notify tail `followup` takes — whichever body form the caller composed, forwarded unchanged so a
+// path-based body reaches `followup` exactly as passed.
+function notify_arguments(values: NotifyValues): ReadonlyArray<string> {
+	return NOTIFY_OPTIONS.flatMap((option) => {
+		const value = values[option]
+
+		return value === undefined ? [] : [`--${option}`, value]
+	})
+}
+
+function issue_number(title: string): string | undefined {
+	return TRAILING_ISSUE_PATTERN.exec(title)?.[NUMBER_GROUP]
+}
+
+interface ParsedValues extends NotifyValues {
+	[BODY_FILE_OPTION]?: string
+	review?: boolean
+	detach?: boolean
+	log?: string
+	cite?: Array<string>
+}
+
+// A follow-up citation passed as a trailing positional is a bare issue number, so a stray flag is
+// refused rather than forwarded to the wrong step.
+function ship_args(
+	title: string,
+	rest: ReadonlyArray<string>,
+	values: ParsedValues,
+): ShipArguments | undefined {
+	const number = issue_number(title)
+	const cites = [...rest, ...(values.cite ?? [])]
+
+	if (number === undefined || cites.some((token) => !issue_number_shape.is_issue_number(token))) {
+		return undefined
+	}
+
+	return {
+		title,
+		number,
+		notify: notify_arguments(values),
+		body: body_arguments(values[BODY_FILE_OPTION]),
+		body_path: values[BODY_FILE_OPTION],
+		cites,
+		is_review: values.review === true,
+		is_detach: values.detach === true,
+	}
+}
+
+// `--log <N>` stands alone: a bare issue number and nothing to ship.
+function log_command(number: string, positionals: ReadonlyArray<string>): ShipCommand | undefined {
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(number) && positionals.length === 0
+		? { kind: 'log', number }
+		: undefined
+}
+
+function command_of(
+	values: ParsedValues,
+	positionals: ReadonlyArray<string>,
+): ShipCommand | undefined {
+	if (values.log !== undefined) return log_command(values.log, positionals)
+
+	const title = positionals[FIRST]
+	const args =
+		title === undefined ? undefined : ship_args(title, positionals.slice(EXTRA_CITE_START), values)
+
+	return args === undefined ? undefined : { kind: 'ship', args }
+}
+
+// Numbers-only tail and a strict parse, so a title with no `#<N>` or a stray flag is refused rather
+// than shipped past the wrong step.
+function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	return parsed === undefined ? undefined : command_of(parsed.values, parsed.positionals)
+}
+
+const run_ship_args = { parse }
+
+export { run_ship_args }
+export type { ShipCommand }

package/scripts/run/ship/run-ship-body-draft.ts

@@ -0,0 +1,110 @@
+import { access, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { git_command } from '#scripts/git/git-command'
+import { acceptance_map } from '#scripts/review/acceptance-map'
+import { live_evidence } from '#scripts/review/live-evidence'
+import { removed_tests } from '#scripts/review/removed-tests'
+import type { ShipArguments } from './run-ship-steps'
+
+// **The pull-request body a run fills in before `josh ship`, written where ship reads it.** The
+// acceptance-map and live-evidence refusals stopped about one ship per merge: their rows were printed
+// at `run:prep`, long before the ship, and the lane child's ship carried no `--body-file` at all
+// (joshuafolkken/kit#4168). The rows now land in a file in the work tree's own git directory — outside
+// the tree, so no check sees it as a change — and `josh ship` reads it when `--body-file` is omitted,
+// handing it to the preflight, `git -y` and a detached supervisor alike (`with_draft`).
+// Nothing is satisfied for the run: each row still carries its pending ending and the evidence section is empty, so
+// the same refusals stand until the run writes them.
+
+// The PR body carrying the live-execution evidence `followup` gates the merge
+// on, forwarded to `git -y` as a path because it holds commands and their output.
+const BODY_FILE_OPTION = 'body-file' as const
+const DRAFT_PREFIX = 'josh-ship-body-'
+const DRAFT_SUFFIX = '.md'
+const EXISTS_CODE = 'EEXIST'
+const NO_GIT_DIRECTORY = 'no git directory to hold the ship body draft'
+
+async function path_of(issue_number: string): Promise<string> {
+	const [git_directory] = await git_command.git_directories()
+
+	if (git_directory === undefined) throw new Error(NO_GIT_DIRECTORY)
+
+	return path.join(git_directory, `${DRAFT_PREFIX}${issue_number}${DRAFT_SUFFIX}`)
+}
+
+function is_exists_error(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === EXISTS_CODE
+}
+
+// The formats the preflight refuses on, as comments a rendered body hides: lanes that wrote the rows and
+// the evidence in shapes of their own met them only at the refusal (joshuafolkken/kit#4478). They sit
+// above the evidence heading, so their backticks are never read as that section's command.
+const FORMAT_HINTS: ReadonlyArray<string> = [
+	acceptance_map.ROW_FORMAT,
+	live_evidence.EVIDENCE_FORMAT,
+	`when the change removes or renames a test, ${removed_tests.ROW_FORMAT}`,
+]
+
+function hint_line(format: string): string {
+	return `<!-- ${format} -->`
+}
+
+function draft_text(acceptance_rows: string): string {
+	const hints = FORMAT_HINTS.map((format) => hint_line(format)).join('\n')
+
+	return `${acceptance_rows}\n\n${hints}\n\n${live_evidence.EVIDENCE_HEADING}\n`
+}
+
+// Written once: a draft the run has already filled in is never replaced by pending rows.
+async function prepare(issue_number: string, acceptance_rows: string): Promise<string> {
+	const target = await path_of(issue_number)
+
+	try {
+		await writeFile(target, draft_text(acceptance_rows), { flag: 'wx' })
+	} catch (error) {
+		if (!is_exists_error(error)) throw error
+	}
+
+	return target
+}
+
+async function existing(issue_number: string): Promise<string | undefined> {
+	const target = await path_of(issue_number)
+
+	try {
+		await access(target)
+
+		return target
+	} catch {
+		return undefined
+	}
+}
+
+// Removed once the pull request merged: keyed by issue number alone, a draft left in a git directory
+// no lane close prunes (the main checkout's `.git`) would hand a reopened issue's ship the old body.
+async function remove(issue_number: string): Promise<void> {
+	await rm(await path_of(issue_number), { force: true })
+}
+
+function body_arguments(body_path: string | undefined): ReadonlyArray<string> {
+	return body_path === undefined ? [] : [`--${BODY_FILE_OPTION}`, body_path]
+}
+
+// The ship's `--body-file`, or the draft when it was omitted and one exists.
+async function with_draft(args: ShipArguments): Promise<ShipArguments> {
+	if (args.body_path !== undefined) return args
+	const draft = await existing(args.number)
+
+	return draft === undefined ? args : { ...args, body: body_arguments(draft), body_path: draft }
+}
+
+const run_ship_body_draft = {
+	BODY_FILE_OPTION,
+	body_arguments,
+	existing,
+	path_of,
+	prepare,
+	remove,
+	with_draft,
+}
+
+export { run_ship_body_draft }