@joshuafolkken/kit 1.1471.0 → 1.1784.0

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-cli.ts

@@ -14,15 +14,16 @@ import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
 import { run_step, type ParentInput, type StepInput } from './run-step'
+import { run_step_section } from './run-step-section'
 
-// `josh run:step [<N>]` — print the run's next single action, computed from the event stream, the carry
+// `josh run:step [<N>]` — print the run's next single action, followed by the section that governs it
+// (`run-step-section.ts`), computed from the event stream, the carry
 // record and the issue state. It reads exactly those three, never the
 // conversation: the issue facts through `run:prep`'s own gather (so this and `run:next` never answer
 // from different reads), the newest event off the stream, and the carry record's kind. The reader runs
 // the printed line, returns the result through `run:event`, and asks again — the loop `run:step`
 // exists to close.
 
-const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
@@ -154,16 +155,31 @@ function parent_input(directory: string | undefined): ParentInput {
 // `unknown` is the one answer with nothing to run — no record this session drives — so it exits non-zero
 // with the usage, exactly as a position missing its issue state does.
 async function run_parent(): Promise<number> {
-	const { line } = run_step.parent_action(parent_input(await run_carry.repository_directory()))
+	const action = run_step.parent_action(parent_input(await run_carry.repository_directory()))
 
-	console.info(line)
-	if (line !== run_step.UNKNOWN) return SUCCESS_EXIT_CODE
+	console.info(action.line)
+	if (action.line !== run_step.UNKNOWN) return run_step_section.print_for(action)
 
 	console.error(USAGE)
 
 	return FAILURE_EXIT_CODE
 }
 
+function report({ input, ship_problems }: Gathered): number {
+	const action = run_step.next_action(input)
+
+	console.info(action.line)
+	// On stderr, so stdout stays the action line and its rule: what `josh ship` would
+	// refuse on is said at every step, while it is still cheap to meet.
+	if (ship_problems.length > 0) console.error(run_prep.ship_body(ship_problems))
+
+	// A state that could not be read exits non-zero, exactly as `run:prep` and `run:next` exit on the
+	// same failure, so a position missing its issue state is never read as a confident next step.
+	if (input.state === undefined) return FAILURE_EXIT_CODE
+
+	return run_step_section.print_for(action)
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	if (argv.length === 0) return await run_parent()
 
@@ -175,16 +191,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	const { input, ship_problems } = await gather(issue_number)
-
-	console.info(run_step.next_action(input).line)
-	// On stderr, so stdout stays the one action line: what `josh ship` would
-	// refuse on is said at every step, while it is still cheap to meet.
-	if (ship_problems.length > 0) console.error(run_prep.ship_body(ship_problems))
-
-	// A state that could not be read exits non-zero, exactly as `run:prep` and `run:next` exit on the
-	// same failure, so a position missing its issue state is never read as a confident next step.
-	return input.state === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	return report(await gather(issue_number))
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/run/run-step-section.ts

@@ -0,0 +1,85 @@
+import { document_section_cli } from '#scripts/document/document-section-cli'
+import { run_step, type StepAction } from './run-step'
+
+// The section that governs each action `run:step` and `run:entry` print — the one table the action →
+// rule mapping lives in, so the manifests no longer carry a route table the reader walks to find it.
+// The command prints the section after its action line, which saves the `doc:section` turn the reader
+// would otherwise spend fetching a section the action already determined.
+//
+// **A heading that does not resolve fails the command**, exactly as `doc:section` refuses it: a pointer
+// renamed away would otherwise print the action without its rule, and the reader would act unread.
+
+const JOSH_PREFIX = 'pnpm josh '
+const COMMAND_SEPARATOR = ' '
+const SUCCESS_EXIT_CODE = 0
+
+// The key `run:entry` prints under — not a `run:step` action, but the entry's own read, kept in the
+// same table so every mechanically-chosen section has one home.
+const ENTRY = 'entry'
+
+interface SectionReference {
+	document: string
+	heading: string
+}
+
+function reference(document: string, heading: string): SectionReference {
+	return { document, heading }
+}
+
+// The gate's chain governs both the implementation it follows and a stopped ship's report.
+const CHAIN = reference('chain-rule.md', 'Run the review-to-merge chain')
+const PROGRESS = 'backlogrun-progress.md'
+
+// Keyed on a verdict token, or on the josh subcommand a command action runs. An action with no row —
+// `wait`, `stop`, a `decide:` line — has no rule to read beyond its own line.
+const GOVERNING_SECTIONS: ReadonlyMap<string, SectionReference> = new Map([
+	[ENTRY, reference('split-assessment.md', 'The question')],
+	[run_step.IMPLEMENT, CHAIN],
+	[run_step.HUMAN_REVIEW, reference('needs-human-review.md', '`needs-human-review`')],
+	[run_step.UPDATE_DEPS, reference('latest-gate.md', 'The dependency update')],
+	['followup', reference('followup.md', 'Run `pnpm josh followup`')],
+	['review:round2', reference('prompts/review.md', 'Review round cap')],
+	['run:merge', reference(PROGRESS, "Running a named epic's children")],
+	['backlog:next', reference('backlogrun-steps.md', 'The loop')],
+	['run:cut', reference('pre-gate-cut.md', 'Resuming')],
+	['ship', CHAIN],
+	['retrospective', reference('retrospective.md', 'The end-of-run retrospective')],
+	['run:carry', reference(PROGRESS, 'The hand-off')],
+])
+
+function key_of(action: StepAction): string {
+	if (action.kind !== 'command') return action.line
+
+	const [subcommand = ''] = action.line.slice(JOSH_PREFIX.length).split(COMMAND_SEPARATOR)
+
+	return subcommand
+}
+
+function section_for(key: string): SectionReference | undefined {
+	return GOVERNING_SECTIONS.get(key)
+}
+
+// Printed through `doc:section` itself, so the extent, the Bash-cap split and the refusal of an
+// unresolved heading are that command's, never a second copy of them.
+function print_section(key: string, root: string = process.cwd()): number {
+	const found = section_for(key)
+
+	if (found === undefined) return SUCCESS_EXIT_CODE
+
+	return document_section_cli.run([found.document, found.heading], root)
+}
+
+function print_for(action: StepAction, root: string = process.cwd()): number {
+	return print_section(key_of(action), root)
+}
+
+const run_step_section = {
+	ENTRY,
+	GOVERNING_SECTIONS,
+	key_of,
+	print_for,
+	print_section,
+}
+
+export type { SectionReference }
+export { run_step_section }

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 }