@joshuafolkken/kit 1.3044.0 → 1.3099.0

package/scripts/lane/lane-ledger-schema-ship.ts

@@ -6,13 +6,17 @@ import { lane_ledger_kind } from './lane-ledger-kind'
 
 const { KIND } = lane_ledger_kind
 
-// Every early-push decision, including a skip before a push process could start.
+// Every early-push decision, including a skip before a push process could start. `head` is the commit
+// it decided on and `slots` how many review slots the round opened (joshuafolkken/kit#7503), absent
+// where unknown and on a line recorded before it had them.
 const early_push_schema = z.object({
 	kind: z.literal(KIND.EARLY_PUSH),
 	at: z.string(),
 	issue: z.number().optional(),
 	source: z.enum(['review', 'ship']),
 	result: z.string(),
+	head: z.string().optional(),
+	slots: z.number().optional(),
 })
 
 // A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the

package/scripts/lane/lane-ledger-schema.ts

@@ -1,3 +1,4 @@
+import { run_startup_schema } from '#scripts/run/startup/run-startup-schema'
 import { z } from 'zod'
 import { lane_ledger_kind } from './lane-ledger-kind'
 import { lane_ledger_pinned_origin } from './lane-ledger-pinned-origin'
@@ -138,11 +139,23 @@ const offerable_schema = z.object({
 // command itself, so a wait inside a gate, a scoped check or a ship lands in one record. `issue` is the
 // lane the claim ran in, absent outside a lane (joshuafolkken/kit#4382).
 const core_wait_schema = z.object({
-	kind: z.literal(KIND.CORE_WAIT),
+	kind: z.enum([KIND.CORE_WAIT, KIND.CORE_ADMISSION]),
 	at: z.string(),
 	command: z.string(),
 	waited_ms: z.number(),
 	issue: z.number().optional(),
+	admission_reason: z.string().optional(),
+	overflow: z.boolean().optional(),
+	budget_cores: z.number().optional(),
+	budget_memory_mb: z.number().optional(),
+	available_mb: z.number().optional(),
+	busy_cores: z.number().optional(),
+	requested_cores: z.number().optional(),
+	granted_cores: z.number().optional(),
+	memory_mb: z.number().optional(),
+	wait_reason: z.string().optional(),
+	admission_waited_ms: z.number().optional(),
+	memory_pressured: z.boolean().optional(),
 })
 // One vitest run's slowest test files, each with its wall time from environment setup to its last
 // test, so a unit run whose wall time far outran its CPU names the file it stalled on
@@ -247,6 +260,7 @@ const push_miss_schema = z.object({
 const limit_schema = z.object({ kind: z.literal(KIND.LIMIT), at: z.string(), limit: z.number() })
 const entry_schema = z.discriminatedUnion('kind', [
 	early_push_schema,
+	run_startup_schema.entry_schema,
 	merge_schema,
 	gate_schema,
 	load_schema,

package/scripts/lane/lane-ledger-write.ts

@@ -192,7 +192,10 @@ async function record_round_two(round_two: RoundTwoRecord, path?: string): Promi
 }
 
 async function record_core_wait(wait: CoreWaitRecord, path?: string): Promise<void> {
-	await record({ kind: KIND.CORE_WAIT, at: now_iso(), ...wait }, path)
+	const is_immediate = wait.admission_reason !== undefined && wait.wait_reason === undefined
+	const kind = is_immediate ? KIND.CORE_ADMISSION : KIND.CORE_WAIT
+
+	await record({ kind, at: now_iso(), ...wait }, path)
 }
 
 async function record_unit_files(

package/scripts/lane/lane-relaunch.ts

@@ -5,6 +5,7 @@ import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch
 import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
+import { lane_dispatch_dependency } from './lane-dispatch-dependency'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
 import { lane_seat_start } from './lane-seat-start'
@@ -25,7 +26,11 @@ const OPENAI_PROVIDER = 'openai'
 type RelaunchResult = LaunchResult | { kind: 'rejected'; note: string }
 type Prepared = Exclude<Awaited<ReturnType<typeof agent_argv.resume_argv>>, { kind: 'rejected' }>
 
-function launch(lane: LaneInfo, built: Prepared, on_note: (note: string) => void): RelaunchResult {
+function launch_ready(
+	lane: LaneInfo,
+	built: Prepared,
+	on_note: (note: string) => void,
+): RelaunchResult {
 	return detached_launch.launch(
 		{
 			argv: built.argv,
@@ -48,6 +53,24 @@ function launch(lane: LaneInfo, built: Prepared, on_note: (note: string) => void
 	)
 }
 
+async function launch(
+	lane: LaneInfo,
+	built: Prepared,
+	on_note: (note: string) => void,
+): Promise<RelaunchResult> {
+	const wait = await lane_dispatch_dependency.check(lane.issue)
+
+	if (wait !== undefined) {
+		await lane_dispatch_dependency.defer(lane.issue)
+
+		return { kind: 'rejected', note: wait.reason }
+	}
+
+	await lane_dispatch_dependency.begin(lane.issue)
+
+	return launch_ready(lane, built, on_note)
+}
+
 async function relaunch(
 	lane: LaneInfo,
 	invocation: string,
@@ -62,7 +85,7 @@ async function relaunch(
 		})
 		if (built.kind === 'rejected') return built
 
-		return await lane_seat_start.start(lane, async (seated) => launch(seated, built, on_note))
+		return await lane_seat_start.start(lane, async (seated) => await launch(seated, built, on_note))
 	} catch (error) {
 		return { kind: 'failed', note: error_text.message_of(error) }
 	}

package/scripts/lane/lane-state-record.ts

@@ -9,6 +9,7 @@ import { z } from 'zod'
 // lanes out of the worker share (`unit-run-marker.ts`, joshuafolkken/kit#6916).
 
 const STATE_SUFFIX = '.json'
+const DEPENDENCY_WAIT_COMMAND = 'lane:dependency-wait'
 // `as const` so the literal type survives export on `lane_state_record` (a bare const widens there).
 const HUMAN_REVIEW = 'human-review' as const
 const LANE_STATES = ['open', 'running', 'paused', HUMAN_REVIEW, 'ended'] as const
@@ -62,6 +63,7 @@ function is_idle(state_root: string, common: string, issue: string): boolean {
 }
 
 const lane_state_record = {
+	DEPENDENCY_WAIT_COMMAND,
 	HUMAN_REVIEW,
 	LANE_STATES,
 	STATE_SUFFIX,

package/scripts/lane/lane-state.ts

@@ -46,7 +46,7 @@ type LaneRecords = ReadonlyMap<string, LaneStateRecord>
 // The states each one moves to. A lane with no record yet (opened before the record existed) moves to
 // any of them.
 const TRANSITIONS: Record<LaneState, ReadonlyArray<LaneState>> = {
-	open: ['open', 'running', HUMAN_REVIEW, 'ended'],
+	open: ['open', 'running', 'paused', HUMAN_REVIEW, 'ended'],
 	running: ['running', 'paused', HUMAN_REVIEW, 'ended'],
 	paused: ['paused', 'running', 'ended'],
 	[HUMAN_REVIEW]: [HUMAN_REVIEW, 'running', 'ended'],
@@ -110,6 +110,13 @@ function next_record(
 	directory: string,
 	now: Date,
 ): LaneStateRecord {
+	if (
+		previous?.changed_by === lane_state_record.DEPENDENCY_WAIT_COMMAND &&
+		change.is_launch === true
+	) {
+		return previous
+	}
+
 	return {
 		// An open starts a fresh life: a reopened lane keeps nothing of the run that launched it before.
 		...(change.state !== 'open' && previous),

package/scripts/lane/lane-stats-tables.ts

@@ -6,6 +6,7 @@ import { lane_claim_stats } from './lane-claim-stats'
 import { lane_concurrency_stats } from './lane-concurrency-stats'
 import { lane_core_wait_stats } from './lane-core-wait-stats'
 import { lane_cut_stats } from './lane-cut-stats'
+import { lane_dispatch_wait_stats } from './lane-dispatch-wait-stats'
 import { lane_early_push_stats } from './lane-early-push-stats'
 import { lane_gap_stats } from './lane-gap-stats'
 import { lane_held_stats } from './lane-held-stats'
@@ -85,6 +86,7 @@ function tables_of({ entries, events, calls }: PeriodRecords, window: StatsWindo
 		lane_size_stats.table(entries, window),
 		lane_implement_rate.table(entries, window),
 		lane_held_stats.table(entries, window),
+		lane_dispatch_wait_stats.table(entries, window, events),
 		lane_core_wait_stats.table(entries, window),
 		lane_process_stats.table(entries, window),
 		lane_check_stats.table(entries, window),

package/scripts/lane/openai-lane-supervisor.ts

@@ -10,6 +10,7 @@ import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { ts_entry_loader } from '#scripts/run/ts-entry-loader'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
+import { lane_dispatch_dependency } from './lane-dispatch-dependency'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
 import { lane_session_broker } from './lane-session-broker'
@@ -118,7 +119,7 @@ async function prepare_generation(generation: Generation): Promise<Generation |
 	return { ...generation, resume_cut }
 }
 
-async function launch_child(generation: Generation): Promise<ChildResult> {
+async function launch_ready_child(generation: Generation): Promise<ChildResult> {
 	const { lane, profile, is_resume } = generation
 
 	update(lane.directory, generation.owner, {
@@ -146,6 +147,20 @@ async function launch_child(generation: Generation): Promise<ChildResult> {
 	return child_result(result)
 }
 
+async function launch_child(generation: Generation): Promise<ChildResult> {
+	const wait = await lane_dispatch_dependency.check(generation.lane.issue)
+
+	if (wait !== undefined) {
+		await lane_dispatch_dependency.defer(generation.lane.issue)
+
+		return { kind: LAUNCH_FAILED_KIND, note: wait.reason }
+	}
+
+	await lane_dispatch_dependency.begin(generation.lane.issue)
+
+	return await launch_ready_child(generation)
+}
+
 async function stop_invocation(issue: string): Promise<string> {
 	const current = await openai_lane_ship.current(issue)
 

package/scripts/lib/inherited-scope.ts

@@ -0,0 +1,48 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { z } from 'zod'
+import { json_value } from './json-value'
+
+interface InheritedScope<T> {
+	current: () => T | undefined
+	local: () => T | undefined
+	within: <R>(value: T, run: () => Promise<R>) => Promise<R>
+	environment: () => Record<string, string>
+}
+
+function storage(key: string): AsyncLocalStorage<unknown> {
+	const symbol = Symbol.for(key)
+	const existing: unknown = Reflect.get(globalThis, symbol)
+	const scope = existing instanceof AsyncLocalStorage ? existing : new AsyncLocalStorage<unknown>()
+
+	Reflect.set(globalThis, symbol, scope)
+
+	return scope
+}
+
+// Ship laps and startup telemetry share inheritance; bundled command copies share the symbol.
+function create<T>(key: string, schema: z.ZodType<T>): InheritedScope<T> {
+	const scope = storage(key)
+
+	function local(): T | undefined {
+		return schema.safeParse(scope.getStore()).data
+	}
+
+	function current(): T | undefined {
+		return local() ?? json_value.parse_with(process.env[key] ?? '', schema)
+	}
+
+	async function within<R>(value: T, run: () => Promise<R>): Promise<R> {
+		return await scope.run(value, run)
+	}
+
+	function environment(): Record<string, string> {
+		const value = current()
+
+		return value === undefined ? {} : { [key]: JSON.stringify(value) }
+	}
+
+	return { current, local, within, environment }
+}
+
+const inherited_scope = { create }
+export { inherited_scope }

package/scripts/lint/format-steps.ts

@@ -0,0 +1,93 @@
+import { direct_launch } from '#scripts/build/local-bin'
+import { project_checks } from '#scripts/gate/project-checks'
+import type { ChangedFileScope } from '#scripts/git/changed-file-scope'
+import { execa } from 'execa'
+import { eslint_cache_dependencies } from './eslint-cache-dependencies'
+import { eslint_heap } from './eslint-heap'
+import { lint_related_scope } from './lint-related-scope'
+import { lint_shard } from './lint-shard'
+
+interface FormatStep {
+	check: string
+	args: ReadonlyArray<string>
+}
+
+// Every formatter finishes before the next starts, even when it reports unfixed problems.
+async function in_order<T, R>(
+	steps: ReadonlyArray<T>,
+	execute: (step: T) => Promise<R>,
+): Promise<Array<R>> {
+	const results: Array<R> = []
+
+	for (const step of steps) {
+		// eslint-disable-next-line no-await-in-loop -- formatters rewrite the same files in order
+		results.push(await execute(step))
+	}
+
+	return results
+}
+
+async function run_step(step: FormatStep, directory: string): Promise<number> {
+	const environment =
+		step.check === 'eslint' ? { env: eslint_heap.environment(), extendEnv: false } : {}
+	const launch = direct_launch(directory, step.args)
+	const result = await execa(launch.file, [...launch.args], {
+		cwd: directory,
+		stdio: 'inherit',
+		reject: false,
+		...environment,
+	})
+
+	return result.exitCode ?? 1
+}
+
+async function run_unless_skipped(step: FormatStep, directory: string): Promise<number> {
+	const reason =
+		step.check === 'eslint'
+			? project_checks.eslint_skip_reason(directory)
+			: project_checks.prettier_skip_reason(directory)
+	if (reason === undefined) return await run_step(step, directory)
+	console.info(project_checks.skip_notice(step.check, reason))
+
+	return 0
+}
+
+async function run(
+	steps: ReadonlyArray<FormatStep>,
+	cache_file: string,
+	directory: string,
+): Promise<number> {
+	const results = await in_order(steps, async (step) => {
+		if (step.check !== 'eslint') return await run_unless_skipped(step, directory)
+
+		return await eslint_cache_dependencies.guard(
+			cache_file,
+			async () => await run_unless_skipped(step, directory),
+			directory,
+		)
+	})
+
+	return results.find((code) => code !== 0) ?? 0
+}
+
+// The resolved lint scope is authoritative; never replace a file list with the whole tree.
+async function run_scoped(scope: ChangedFileScope, directory: string): Promise<number> {
+	const files = scope.mode === 'all' ? [lint_shard.WHOLE_TREE] : scope.files
+	const eslint = [...lint_related_scope.eslint_arguments(files), '--fix']
+	const prettier = lint_related_scope.prettier_arguments(files, undefined, directory)
+	const steps: Array<FormatStep> = [{ check: 'eslint', args: eslint }]
+
+	// Basic read-only lint expands a non-Web list; scoped writers must omit that fallback.
+	if (scope.mode === 'all' || !prettier.includes(project_checks.WEB_FILES)) {
+		steps.push({
+			check: 'prettier',
+			args: prettier.map((argument) => (argument === '--check' ? '--write' : argument)),
+		})
+	}
+
+	return await run(steps, lint_related_scope.RELATED_CACHES.eslint_file, directory)
+}
+
+const format_steps = { in_order, run, run_scoped }
+
+export { format_steps }

package/scripts/lint/format.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { direct_launch } from '#scripts/build/local-bin'
 import { project_checks } from '#scripts/gate/project-checks'
 import {
 	ESLINT_CACHE_FILE,
@@ -8,14 +7,11 @@ import {
 	PRETTIER_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
-import { execa } from 'execa'
-import { eslint_cache_dependencies } from './eslint-cache-dependencies'
-import { eslint_heap } from './eslint-heap'
+import { format_steps } from './format-steps'
 import { lint_shard } from './lint-shard'
 
 const COMMAND_NAME = 'format'
 const ARGV_OFFSET = 2
-const FAIL_EXIT_CODE = 1
 
 function prettier_write_args_of(targets: ReadonlyArray<string>): ReadonlyArray<string> {
 	return ['exec', 'prettier', '--write', ...targets, ...PRETTIER_CACHE_FLAGS]
@@ -30,52 +26,13 @@ function prettier_write_args(directory: string): ReadonlyArray<string> {
 
 const ESLINT_FIX_ARGS = ['exec', 'eslint', '.', '--fix', ...ESLINT_CACHE_FLAGS] as const
 
-async function run_step(
-	check: string,
-	args: ReadonlyArray<string>,
-	directory: string,
-): Promise<number> {
-	const environment = check === 'eslint' ? { env: eslint_heap.environment(), extendEnv: false } : {}
-	const launch = direct_launch(directory, args)
-	const result = await execa(launch.file, [...launch.args], {
-		cwd: directory,
-		stdio: 'inherit',
-		reject: false,
-		...environment,
-	})
-
-	return result.exitCode ?? FAIL_EXIT_CODE
-}
-
-// prettier first, deliberately: `eslint --fix` exits 1 whenever a non-autofixable error remains, so
-// putting it first would mean one unused variable anywhere in the tree stops prettier from running.
-// A basic project without Prettier or ESLint is skipped with the same reason `josh lint` prints.
-async function run_unless_skipped(
-	check: string,
-	reason: string | undefined,
-	args: ReadonlyArray<string>,
-	directory: string,
-): Promise<number> {
-	if (reason === undefined) return await run_step(check, args, directory)
-	console.info(project_checks.skip_notice(check, reason))
-
-	return 0
-}
-
 async function run_format(directory: string): Promise<number> {
-	const prettier_reason = project_checks.prettier_skip_reason(directory)
-	const prettier_exit_code = await run_unless_skipped(
-		'prettier',
-		prettier_reason,
-		prettier_write_args(directory),
-		directory,
-	)
-	if (prettier_exit_code !== 0) return prettier_exit_code
-	const eslint_reason = project_checks.eslint_skip_reason(directory)
-
-	return await eslint_cache_dependencies.guard(
+	return await format_steps.run(
+		[
+			{ check: 'eslint', args: ESLINT_FIX_ARGS },
+			{ check: 'prettier', args: prettier_write_args(directory) },
+		],
 		ESLINT_CACHE_FILE,
-		async () => await run_unless_skipped('eslint', eslint_reason, ESLINT_FIX_ARGS, directory),
 		directory,
 	)
 }

package/scripts/lint/lint-related-fix.ts

@@ -0,0 +1,35 @@
+import type { GateTree } from '#scripts/gate/gate-tree'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-file-scope'
+import { format_steps } from './format-steps'
+import { lint_related_scope } from './lint-related-scope'
+
+function report_scope(argv: ReadonlyArray<string>, scope: ChangedFileScope, root: string): void {
+	changed_file_scope.report_unusable_arguments(argv, scope, lint_related_scope.COMMAND_LABEL)
+	const flags = changed_file_scope.flags_of(argv)
+
+	if (flags.length > 0) {
+		process.stdout.write(
+			`${lint_related_scope.COMMAND_LABEL}: ignored — prettier and eslint take different flags: ${flags.join(' ')}\n`,
+		)
+	}
+
+	process.stdout.write(`${lint_related_scope.describe_scope(scope, root)}\n`)
+}
+
+// The verification snapshot is taken after every writer finishes. The checks that follow read
+// that tree; their normal before/after guard still rejects concurrent edits during verification.
+async function prepare(
+	argv: ReadonlyArray<string>,
+	scope: ChangedFileScope,
+	root: string,
+): Promise<GateTree | undefined> {
+	report_scope(argv, scope, root)
+	await format_steps.run_scoped(scope, root)
+
+	return await scoped_green.read_before(argv)
+}
+
+const lint_related_fix = { prepare }
+
+export { lint_related_fix }

package/scripts/lint/lint-related.ts

@@ -17,6 +17,7 @@ import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-
 import { review_stamps } from '#scripts/review/review-stamps'
 import { eslint_daemon_calls } from './eslint-daemon-calls'
 import { lint_parallel, type LintRunTiming } from './lint-parallel'
+import { lint_related_fix } from './lint-related-fix'
 import { lint_related_scope } from './lint-related-scope'
 
 // `josh lint:related` — the lint check an implementation loop runs between edits.
@@ -29,16 +30,6 @@ import { lint_related_scope } from './lint-related-scope'
 // eslint and nothing to `prettier --check`. Sending a flag to both would fail the run over the
 // argument list, and dropping it silently would run a check the caller did not ask for, so the run
 // says which arguments it ignored.
-function report_ignored_flags(command_arguments: ReadonlyArray<string>): void {
-	const flags = changed_file_scope.flags_of(command_arguments)
-
-	if (flags.length === 0) return
-
-	process.stdout.write(
-		`${lint_related_scope.COMMAND_LABEL}: ignored — prettier and eslint take different flags: ${flags.join(' ')}\n`,
-	)
-}
-
 // The timing line names what the run read, so a slow first run is told apart from a wide one
 // (joshuafolkken/kit#5712).
 function timing_of(targets: string): LintRunTiming {
@@ -202,23 +193,6 @@ async function outcome_with_notice(
 	return { ...outcome, notice: await metrics_totals.growth_notice(root) }
 }
 
-// The narrowing line is printed before either child starts, so a scoped run is never read as a
-// whole one, and a fallback says which of the two it was rather than looking like a narrow run
-// that found nothing.
-function report_scope(
-	command_arguments: ReadonlyArray<string>,
-	scope: ChangedFileScope,
-	root: string,
-): void {
-	changed_file_scope.report_unusable_arguments(
-		command_arguments,
-		scope,
-		lint_related_scope.COMMAND_LABEL,
-	)
-	report_ignored_flags(command_arguments)
-	process.stdout.write(`${lint_related_scope.describe_scope(scope, root)}\n`)
-}
-
 // **Nothing moved since the last green run lints nothing** (joshuafolkken/kit#4593), as
 // `josh test:related` runs no test.
 function report_unmoved(): LintOutcome {
@@ -233,14 +207,18 @@ async function checked_outcome(
 	command_arguments: ReadonlyArray<string>,
 	root: string,
 	moved: ReadonlyArray<string> | undefined,
-): Promise<LintOutcome> {
-	if (moved?.length === 0) return report_unmoved()
+	before: GateTree | undefined,
+): Promise<{ outcome: LintOutcome; before: GateTree | undefined }> {
+	if (moved?.length === 0) return { outcome: report_unmoved(), before }
 
 	const scope = await resolve_lint_scope(command_arguments, root, moved)
+	const verified = await lint_related_fix.prepare(command_arguments, scope, root)
+	const outcome = await outcome_with_notice(command_arguments, scope, root)
 
-	report_scope(command_arguments, scope, root)
-
-	return await outcome_with_notice(command_arguments, scope, root)
+	return {
+		outcome,
+		before: verified,
+	}
 }
 
 // The run's last line names the stage that failed, or says it passed; the console is the only copy of
@@ -266,13 +244,22 @@ async function fresh_exit_code(
 	before: GateTree | undefined,
 ): Promise<number> {
 	const moved = await read_since_green(before)
-	const outcome = await checked_outcome(command_arguments, root, moved)
+	const { outcome, before: verified } = await checked_outcome(
+		command_arguments,
+		root,
+		moved,
+		before,
+	)
 	const { exit_code } = outcome
 	const tail = verdict_tail(outcome)
+	const entry = { before: verified, exit_code, tail }
 
 	process.stdout.write(tail)
-	await scoped_green.record_if_green(review_stamps.lint_related_stamp, { before, exit_code })
-	await tree_verdict.record({ before, exit_code, tail }, gate_tree.read_gate_tree, VERDICT_RECORD)
+	await scoped_green.record_if_green(review_stamps.lint_related_stamp, {
+		before: verified,
+		exit_code,
+	})
+	await tree_verdict.record(entry, gate_tree.read_gate_tree, VERDICT_RECORD)
 
 	return exit_code
 }

package/scripts/propagate/propagate-steps.ts

@@ -64,10 +64,11 @@ function sync_command(bin_name: string): ReadonlyArray<string> {
 function upgrade_command(
 	package_name: string,
 	version: string,
+	root: string = process.cwd(),
 ): ReadonlyArray<ReadonlyArray<string>> {
 	const config = create_version_command_config({ package_name })
 
-	return build_upgrade_command(version, true, config).steps
+	return build_upgrade_command(version, true, config, root).steps
 }
 
 const PROPAGATE_ORIGIN =
@@ -392,9 +393,12 @@ function run_each(
 }
 
 // One entry per step, so `run_each` stops a toolkit's lockfile repair after its failed install.
-function upgrade_commands(plan: ReleasePlan): ReadonlyArray<ToolkitCommand> {
+function upgrade_commands(
+	plan: ReleasePlan,
+	root: string = process.cwd(),
+): ReadonlyArray<ToolkitCommand> {
 	return plan.releases.flatMap((release) =>
-		upgrade_command(release.package_name, release.version).map((command) => ({
+		upgrade_command(release.package_name, release.version, root).map((command) => ({
 			package_name: release.package_name,
 			command,
 		})),
@@ -414,7 +418,8 @@ function create_step_runner(plan: ReleasePlan): RunStep {
 	const issue_numbers = new Map<string, string>()
 	const handlers: Record<string, (target: PropagateTarget, step: string) => StepResult> = {
 		[propagate_run.STEP_PRECHECK]: precheck_step,
-		[propagate_run.STEP_UPGRADE]: (target, step) => run_each(target, step, upgrade_commands(plan)),
+		[propagate_run.STEP_UPGRADE]: (target, step) =>
+			run_each(target, step, upgrade_commands(plan, target.path)),
 		[propagate_run.STEP_SYNC]: (target, step) => run_each(target, step, sync_commands(plan)),
 		[propagate_run.STEP_ISSUE]: (target, step) => issue_step(target, step, plan, issue_numbers),
 		[propagate_run.STEP_PR]: (target, step) => pull_request_step(target, step, plan, issue_numbers),

package/scripts/registry-migration/migrate-cli.ts

@@ -0,0 +1,50 @@
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
+import { migrate } from './migrate'
+
+const USAGE = 'Usage: node registry-migrate.mjs <exact-kit-version> [--dry-run]'
+const ARGUMENT_OFFSET = 2
+
+function parse(args: ReadonlyArray<string>): { version: string; is_dry_run: boolean } {
+	const [version, ...flags] = args
+	if (version === undefined || flags.some((flag) => flag !== '--dry-run')) throw new Error(USAGE)
+
+	return { version, is_dry_run: flags.includes('--dry-run') }
+}
+
+async function main(args: ReadonlyArray<string>): Promise<void> {
+	const { version, is_dry_run } = parse(args)
+	const changes = await migrate(process.cwd(), version, is_dry_run)
+
+	console.info(`${is_dry_run ? 'Planned' : 'Changed'}: ${changes.join(', ') || 'none'}`)
+	console.info(
+		'Next: install the target kit from npm, then run its josh sync. User npmrc and node_modules were not changed.',
+	)
+}
+
+async function run(
+	args: ReadonlyArray<string> = process.argv.slice(ARGUMENT_OFFSET),
+): Promise<void> {
+	try {
+		if (args.includes('--help')) {
+			console.info(USAGE)
+
+			return
+		}
+
+		await main(args)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+		process.exit(1)
+	}
+}
+
+if (
+	process.argv[1] !== undefined &&
+	realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+	await run()
+}
+
+export { main, run }