@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/git/issue-labels.ts

@@ -19,6 +19,11 @@ const RUN_SOLO_LABEL = 'run:solo'
 // (joshuafolkken/kit#2779). Without it an issue lacking `run:solo` could mean "judged parallel" or
 // "never judged", and `backlog:next` withholds the second (`epic-triage.ts`).
 const RUN_LANE_LABEL = 'run:lane'
+// Puts an issue at the head of the backlog's ranking (joshuafolkken/kit#2928). A person or a run may
+// apply it — a run only where it can cite a deadline or a stated urgency, or a policy a person wrote
+// (`backlogrun-steps.md`) — and **only a person removes it**: a run that could clear it could undo
+// the person's ordering. Read by `issue-rank.ts`, the one place the ranking keys are decided.
+const PRIORITY_HIGH_LABEL = 'priority:high'
 // Opts one issue outside any epic into unattended execution (joshuafolkken/kit#906). **Only a
 // person applies it.** `epicrun #<E>` approves the merges inside `#<E>`; this label is the only way
 // a person extends that approval past the epic's edge, so a label an AI could apply to itself would
@@ -212,6 +217,11 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: '0e8a16',
 		description: 'Judged safe to run beside others in a backlogrun',
 	},
+	{
+		name: PRIORITY_HIGH_LABEL,
+		color: 'e99695',
+		description: 'Offered first in a backlogrun; only a person removes it',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -282,7 +292,7 @@ function label_name_of(labels: ReadonlyArray<string>, wanted: string): string |
 
 // The same comparison for a caller holding label *names* rather than listing rows. `EpicChild.labels`
 // is an array of strings (`scripts/epic/epic-graph.ts`), which is the one shape `has_any_label` cannot
-// take — so `epic-classify.ts` and `git-epic-validate.ts` each grew a raw case-sensitive
+// take — so `epic-classify.ts` and `epic-validate.ts` each grew a raw case-sensitive
 // `Array.includes` instead, and an `Epic`-cased label walked past both. Kept here beside the rule it
 // implements rather than at either call site, for the reason the comment above gives.
 //
@@ -322,6 +332,7 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	AUTO_OK_LABEL,
 	NEEDS_HUMAN_REVIEW_LABEL,
 	ALREADY_DONE_LABEL,
+	PRIORITY_HIGH_LABEL,
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
@@ -364,6 +375,7 @@ export {
 	NEEDS_HUMAN_REVIEW_LABEL,
 	NOT_DIRECTLY_RUNNABLE_LABELS,
 	OTHER_CHANGE_LABEL,
+	PRIORITY_HIGH_LABEL,
 	RELEASE_CLASSIFICATION_LABELS,
 	RELEASE_CLASSIFICATION_NAMES,
 	REPOSITORY_LABELS,

package/scripts/git/issue-rank.ts

@@ -0,0 +1,89 @@
+import {
+	BUG_LABEL,
+	has_label_name,
+	INTERRUPT_ROUTE_LABEL,
+	PRIORITY_HIGH_LABEL,
+	RUN_SOLO_LABEL,
+} from './issue-labels'
+
+// The keys that decide which open issue is offered first (joshuafolkken/kit#2928), defined once for
+// every ranking that asks: the `🗒 Next issues` display, the `auto-ok` pickup and `backlog:next`.
+//
+// In order: `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or
+// `route:interrupt`), then how many other open issues wait on it. Below those, the caller's own order
+// stands — the sort is stable, so recency and the defect-rate adjustment survive as the last key.
+//
+// **`run:solo` alone is not a key.** It means "runs alone", not "runs first": tidying that only touches
+// the verification path carries it too, and a low-priority one is not owed a place ahead of the queue.
+// Only a defect on that path is, because `wip-cap.md` holds a batch until it has merged.
+
+interface RankRow {
+	labels: ReadonlyArray<string>
+	dependents: number
+}
+
+// One open issue as its key and the keys of the issues it is blocked by. The caller names the key
+// format, so a ranking over listing rows and one over graph children each count in their own terms.
+interface DependencyRow {
+	key: string
+	blockers: ReadonlyArray<string>
+}
+
+const NO_DEPENDENTS = 0
+
+function flag(is_set: boolean): number {
+	return is_set ? 1 : 0
+}
+
+function is_priority(labels: ReadonlyArray<string>): boolean {
+	return has_label_name(labels, PRIORITY_HIGH_LABEL)
+}
+
+function is_verification_defect(labels: ReadonlyArray<string>): boolean {
+	if (has_label_name(labels, INTERRUPT_ROUTE_LABEL)) return true
+
+	return has_label_name(labels, BUG_LABEL) && has_label_name(labels, RUN_SOLO_LABEL)
+}
+
+// Negated so that the larger value sorts first under an ascending comparison.
+function keys_of(row: RankRow): ReadonlyArray<number> {
+	return [
+		-flag(is_priority(row.labels)),
+		-flag(is_verification_defect(row.labels)),
+		-row.dependents,
+	]
+}
+
+function compare(first: RankRow, second: RankRow): number {
+	const second_keys = keys_of(second)
+	const differences = keys_of(first).map((key, index) => key - (second_keys[index] ?? 0))
+
+	return differences.find((difference) => difference !== 0) ?? 0
+}
+
+// How many of the rows wait on each key. A blocker outside the rows counts nothing, because only an
+// open issue in the same pool can be held back by it.
+function count_dependents(rows: ReadonlyArray<DependencyRow>): ReadonlyMap<string, number> {
+	const counts = new Map<string, number>()
+
+	for (const row of rows) {
+		const blockers = new Set(row.blockers)
+
+		for (const blocker of blockers) counts.set(blocker, (counts.get(blocker) ?? NO_DEPENDENTS) + 1)
+	}
+
+	return counts
+}
+
+// The items in rank order, ties kept in the order they arrived.
+function rank<T>(items: ReadonlyArray<T>, row_of: (item: T) => RankRow): Array<T> {
+	return items
+		.map((item) => ({ item, row: row_of(item) }))
+		.toSorted((first, second) => compare(first.row, second.row))
+		.map((entry) => entry.item)
+}
+
+const issue_rank = { compare, count_dependents, is_priority, is_verification_defect, rank }
+
+export { issue_rank }
+export type { DependencyRow, RankRow }

package/scripts/git/issue-reference.ts

@@ -0,0 +1,19 @@
+// An issue named from outside any one graph — a task-list row, a citation in prose, a blocker
+// relation, a child that could not be read. Repository **and** number, because a number alone cannot
+// identify one: issue numbers are unique per repository, so the same `#40` names two different issues
+// depending on who wrote it (joshuafolkken/kit#1014).
+//
+// It lives in the git layer because the `blocked-by` relations are read here and carry a repository
+// of their own (joshuafolkken/kit#1126); the epic domain builds on this layer, never the other way
+// round (joshuafolkken/kit#2904). `epic-reference` re-exports it, so every epic importer is unchanged.
+//
+// `state` is present only on a reference read from a `blocked-by` relation whose response carried it
+// (joshuafolkken/kit#1943). The classifier needs it for a blocker no named graph tracks, where there is
+// no child record to read the state from; every other reference leaves it out.
+interface IssueReference {
+	repo: string
+	number: number
+	state?: 'OPEN' | 'CLOSED'
+}
+
+export type { IssueReference }

package/scripts/git/main-merge.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { extract_issue_number } from '#scripts/hooks/check-commit-message'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
 import { main_merge_guard } from './main-merge-guard'
 
@@ -103,7 +104,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return await dispatch(argv)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/git/main-sync.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
 import { gone_branch, type PruneResult } from './gone-branch'
 
@@ -65,7 +66,7 @@ async function prune_quietly(default_branch: string): Promise<void> {
 	try {
 		report_prune(await gone_branch.prune(default_branch))
 	} catch (error) {
-		console.error(`branch prune skipped: ${error instanceof Error ? error.message : String(error)}`)
+		console.error(`branch prune skipped: ${error_text.message_of(error)}`)
 	}
 }
 
@@ -104,7 +105,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return await dispatch(argv)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/git/schemas.ts

@@ -111,7 +111,7 @@ const rest_comment_schema = z.looseObject({
 // Labels come back as objects, so the name is picked out here rather than at every call site.
 const issue_label_schema = z.object({ name: z.string() })
 
-// `state` is optional because most readers ignore it — only `git-epic-add.ts` consults it, to refuse
+// `state` is optional because most readers ignore it — only `epic-add.ts` consults it, to refuse
 // adding a child to a closed epic (joshuafolkken/kit#2337). A reader that never asks the state field
 // still parses cleanly.
 const epic_subject_schema = z.object({

package/scripts/git/stash-pop-args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 
 // `josh stash:pop` turns its `argv` into a single request: the message of the stash to pop. Parsing
 // lives here, acting on the stack lives in `stash-pop-cli.ts`, and a malformed command line is
@@ -21,18 +21,12 @@ interface Request {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		const parsed = parseArgs({
-			args: [...argv],
-			options: OPTIONS,
-			strict: true,
-			allowPositionals: true,
-		})
-
-		return { values: parsed.values, positionals: parsed.positionals }
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({
+		args: [...argv],
+		options: OPTIONS,
+		strict: true,
+		allowPositionals: true,
+	})
 }
 
 // The message is the sole positional and must be a non-empty string: an empty message matches every

package/scripts/git/stash-pop-cli.ts

@@ -1,4 +1,5 @@
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { git_stash } from './git-stash'
 import { stash_pop_args, type Request } from './stash-pop-args'
 
@@ -66,7 +67,7 @@ async function answer(request: Request): Promise<number> {
 }
 
 function report_unknown(error: unknown): number {
-	console.error(error instanceof Error ? error.message : String(error))
+	console.error(error_text.message_of(error))
 
 	return FAILURE_EXIT_CODE
 }

package/{scripts-ai → scripts/git}/telegram-test-logic.ts

@@ -1,5 +1,5 @@
-import type { TelegramSendInput, TelegramTaskType } from '../scripts/git/telegram-notify'
-import { cli_body } from '../scripts/josh/cli-body'
+import { cli_body } from '#scripts/josh/cli-body'
+import type { TelegramSendInput, TelegramTaskType } from './telegram-notify'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 interface CliValues {

package/{scripts-ai → scripts/git}/telegram-test.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
-import { git_error } from '../scripts/git/git-error'
-import { git_gh_issue_read } from '../scripts/git/git-gh-issue-read'
-import { git_gh_repo } from '../scripts/git/git-gh-repo'
-import { github_issue_url, type IssueUrlTarget } from '../scripts/git/github-issue-url'
-import { telegram_notify } from '../scripts/git/telegram-notify'
-import { load_optional_environment } from './environment-loader'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { git_error } from './git-error'
+import { git_gh_issue_read } from './git-gh-issue-read'
+import { git_gh_repo } from './git-gh-repo'
+import { github_issue_url, type IssueUrlTarget } from './github-issue-url'
+import { telegram_notify } from './telegram-notify'
 import { telegram_test_logic, type CliValues, type ResolvedContext } from './telegram-test-logic'
 
 const REPO_NAME_SEPARATOR = '/'
@@ -97,7 +97,7 @@ async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 }
 
 async function main(): Promise<void> {
-	load_optional_environment()
+	josh_environment_file.load_environment_file()
 	const values = parse_cli_arguments()
 	const context = await resolve_context(values)
 	const input = telegram_test_logic.build_input({ values, context })

package/scripts/hooks/format-edited-cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { report_no_payload, run_hook } from './format-edited-file'
+
+// The `PostToolUse` hook's entry, kept apart from `format-edited-file.ts` for the reason
+// `pretool-guard-cli.ts` gives (joshuafolkken/kit#2922): `codex-hook-adapter.ts` imports that module,
+// so a self-invoke left in it lands in a shared chunk and the bundled hook never runs.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) {
+		report_no_payload()
+	} else {
+		await run_hook(await text(process.stdin))
+	}
+}

package/scripts/hooks/format-edited-file.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
 import { ESLINT_EDIT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
@@ -482,14 +481,6 @@ async function run_hook(payload: string): Promise<void> {
 	if (context !== undefined) process.stdout.write(`${build_envelope(context)}\n`)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) {
-		report_no_payload()
-	} else {
-		await run_hook(await text(process.stdin))
-	}
-}
-
 export {
 	build_envelope,
 	compose_context,
@@ -501,7 +492,9 @@ export {
 	plan_commands,
 	plan_daemon_restart,
 	relative_to_root,
+	report_no_payload,
 	resolve_invocations,
+	run_hook,
 	select_invocation,
 	ESLINT_DAEMON,
 	MAX_DIAGNOSTIC_CHARS,

package/scripts/hooks/format-rewrite-notice.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { file_reader } from '#scripts/lib/read-file'
 
 // The rewrite half of the edit hook (joshuafolkken/kit#2314). The format hook runs prettier and
 // `eslint --fix` in place after every edit, so a file the model just wrote can be rewritten out from
@@ -85,13 +85,7 @@ function build(before: string, after: string): string | undefined {
 // handed nothing for, or one gone by the time it reads, compares as an empty string rather than
 // throwing — the hook runs after the write already succeeded and must never turn it into a failure.
 function read_text(file_path: string | undefined): string {
-	if (file_path === undefined) return ''
-
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_path === undefined ? '' : (file_reader.read_if_readable(file_path) ?? '')
 }
 
 const rewrite_notice = { build, read_text }

package/scripts/hooks/pretool-guard-cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { pretool_outcome_async } from './pretool-guard'
+
+// The `PreToolUse` hook's entry, kept apart from the composition in `pretool-guard.ts`
+// (joshuafolkken/kit#2922). The hook bundles are built with `splitting: true`, which moves a module
+// imported by two entries into a shared chunk — and `codex-hook-adapter.ts` imports `pretool-guard.ts`.
+// Its self-invoke went into that chunk, whose `import.meta.url` never equals the launched
+// `dist/hooks/pretool-guard.js`, so the bundled hook ran no guard at all and every refusal failed open.
+// An entry nothing imports keeps the self-invoke in the file that is actually launched.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
+	else {
+		const raw_payload = await text(process.stdin)
+
+		hook_decision.load_environment_file()
+		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
+	}
+}

package/scripts/hooks/pretool-guard.ts

@@ -1,10 +1,8 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
-import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
+import type { GuardOutcome } from '#scripts/josh/hook-decision'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
 import { batch_outcome } from './batch-guard'
 
@@ -71,26 +69,27 @@ function pretool_outcome(raw_payload: string): GuardOutcome {
 // as `combine_outcomes` orders them, and the watcher's refusal fills a clear verdict rather than
 // overriding one. It fires once per run itself (`run-watcher-hook.ts`), so a stale watcher refuses the
 // first call but not the `pnpm josh run:progress --wait` that fixes it.
+//
+// **The parent hand-off guard is the second asynchronous rule, asked after the watcher's**
+// (joshuafolkken/kit#2947). It reads the carry record to tell the `backlogrun` parent apart, so it sits
+// beside the watcher rather than among the synchronous rows; a stale watcher is the cheaper fix and is
+// surfaced first.
+async function async_reason(raw_payload: string): Promise<string | undefined> {
+	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
+
+	return watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+}
+
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {
 	const base = pretool_outcome(raw_payload)
 
 	if (!is_clear(base)) return base
 
-	const reason = await run_watcher_hook.watcher_hook_reason(raw_payload)
+	const reason = await async_reason(raw_payload)
 
 	return reason === undefined ? base : { reason, notice: undefined, fault: undefined }
 }
 
 const pretool_guard = { combine_outcomes, pretool_outcome, pretool_outcome_async }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
-	else {
-		const raw_payload = await text(process.stdin)
-
-		hook_decision.load_environment_file()
-		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
-	}
-}
-
 export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/init/init-ai-copy.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { is_workflow_destination } from '#scripts/claude/workflow-destination'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { file_reader } from '#scripts/lib/read-file'
 import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
 import {
 	classify_path,
@@ -238,11 +239,7 @@ function did_skip_ai_directory_copy(directory_name: string): boolean {
 // moved onto the basic path — only that kit-written line, never the consumer's additions.
 // An unreadable file is left as it is and reported as skipped, as it was before the migration.
 function read_if_readable(destination_path: string): string | undefined {
-	try {
-		return readFileSync(destination_path, 'utf8')
-	} catch {
-		return undefined
-	}
+	return file_reader.read_if_readable(destination_path)
 }
 
 function report_existing_claude_md(destination_path: string): void {

package/scripts/init/init.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin } from '#scripts/build/local-bin'
 import { doctor_io } from '#scripts/doctor/doctor-io'
+import { error_text } from '#scripts/lib/error-message'
 import { package_version_schema, with_package_manager_schema } from '#scripts/lib/schemas'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { project_config } from '#scripts/safe-chain/project-config'
@@ -45,8 +46,11 @@ function show_sample(action: FileAction): void {
 	console.info(action.create().replaceAll(/^/gmu, () => SAMPLE_INDENT))
 }
 
-function report_unchanged(action: FileAction): void {
-	if (action.should_show_sample_when_unchanged === true) show_sample(action)
+// A file that already holds the sample needs nothing added, so only one that differs gets it shown.
+function report_unchanged(action: FileAction, existing: string): void {
+	const is_sample_missing = existing !== action.create()
+
+	if (is_sample_missing && action.should_show_sample_when_unchanged === true) show_sample(action)
 	else console.info(`  ✔ unchanged ${action.dest}`)
 }
 
@@ -59,7 +63,7 @@ function merge_existing_file(
 	const merged = merge_function(existing)
 
 	if (merged === existing) {
-		report_unchanged(action)
+		report_unchanged(action, existing)
 
 		return
 	}
@@ -375,7 +379,7 @@ function run_cli(args: ReadonlyArray<string>): void {
 	try {
 		if (main(args)) print_start_hint()
 	} catch (error) {
-		console.error(`\n✖ ${error instanceof Error ? error.message : String(error)}\n`)
+		console.error(`\n✖ ${error_text.message_of(error)}\n`)
 		process.exitCode = 1
 	}
 }

package/scripts/init/start-exec.ts

@@ -23,6 +23,12 @@ function run(command: string, args: ReadonlyArray<string>, root: string): void {
 	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
 }
 
-const start_exec = { succeeds, read_output, run }
+// A caller's own initialize command stands in for the in-process `josh init`, so it keeps the
+// environment that setup would have had — its install goes through a scanner's proxy as usual.
+function run_local(command: string, args: ReadonlyArray<string>, root: string): void {
+	execaSync(command, args, { cwd: root, stdio: 'inherit' })
+}
+
+const start_exec = { succeeds, read_output, run, run_local }
 
 export { start_exec }

package/scripts/init/start-plan.ts

@@ -8,6 +8,7 @@ interface StartOptions {
 	is_yes: boolean
 	is_github: boolean
 	visibility: Visibility
+	init_command: string | undefined
 }
 
 type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels' | 'setup_pr'
@@ -137,20 +138,31 @@ function github_consent(
 	}
 }
 
+// A run whose initialize step was handed to a caller's command names that command wherever the step
+// is printed, so the plan, the progress and a failure all say what actually runs (#2872).
+function step_labels(init_command: string | undefined): Readonly<Record<StartStep, string>> {
+	if (init_command === undefined) return STEP_LABELS
+
+	return { ...STEP_LABELS, initialize: `Initialize with ${init_command}` }
+}
+
 // What a failed run prints, so the user can tell how far it got before deciding how to resume.
 function progress_report(
 	failed: StartStep,
 	completed: ReadonlyArray<StartStep>,
 	cause: string,
+	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
 ): string {
-	const done =
-		completed.length === 0 ? 'nothing' : completed.map((step) => STEP_LABELS[step]).join('; ')
+	const done = completed.length === 0 ? 'nothing' : completed.map((step) => labels[step]).join('; ')
 
-	return `josh start stopped at: ${STEP_LABELS[failed]}\nCompleted: ${done}\nCause: ${cause}`
+	return `josh start stopped at: ${labels[failed]}\nCompleted: ${done}\nCause: ${cause}`
 }
 
-function plan_summary(steps: ReadonlyArray<StartStep>): string {
-	const lines = steps.map((step, index) => `  ${String(index + 1)}. ${STEP_LABELS[step]}`)
+function plan_summary(
+	steps: ReadonlyArray<StartStep>,
+	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
+): string {
+	const lines = steps.map((step, index) => `  ${String(index + 1)}. ${labels[step]}`)
 
 	return ['josh start will:', ...lines].join('\n')
 }
@@ -161,6 +173,7 @@ const start_plan = {
 	github_consent,
 	progress_report,
 	plan_summary,
+	step_labels,
 	STEP_LABELS,
 }
 export { start_plan }