@joshuafolkken/kit 1.1094.0 → 1.1128.0

package/scripts/lane/lane-await.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
+import { run_liveness } from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
 
@@ -22,15 +23,20 @@ const MS_PER_SECOND = 1000
 const ISSUE_PATTERN = /^[1-9]\d*$/u
 const PROCESS_FOUND = 0
 
+// `is_settled` is read once, when the wait starts: a child that ended between two `lane:await` calls
+// never appears in the second one, and only its settled issue tells it apart from one not yet
+// launched (joshuafolkken/kit#3133).
 interface AwaitState {
 	appeared: boolean
 	disappeared_at: number | undefined
 	first_polled_at: number | undefined
+	is_settled?: boolean
 }
 
 // Injectable for testing -- the CLI never overrides these.
 interface AwaitOptions {
 	is_running?: (issue: string) => boolean
+	is_settled?: (issue: string) => Promise<boolean>
 	poll_ms?: number
 	reconfirm_ms?: number
 	never_appeared_timeout_ms?: number
@@ -43,6 +49,7 @@ interface CheckConfig {
 }
 
 interface RunConfig extends CheckConfig {
+	is_settled: (issue: string) => Promise<boolean>
 	poll_ms: number
 }
 
@@ -55,23 +62,42 @@ function is_process_running_default(issue: string): boolean {
 	return lane_handoff.is_ship_running(issue, process.cwd())
 }
 
-function make_initial_state(): AwaitState {
-	return { appeared: false, disappeared_at: undefined, first_polled_at: undefined }
+// The same positive evidence `run:liveness` answers `settled` on: the issue closed, or it was parked.
+async function is_settled_default(issue: string): Promise<boolean> {
+	return (await run_liveness.read_child_settled(issue)) === true
 }
 
-function make_states(issues: ReadonlyArray<string>): Map<string, AwaitState> {
-	return new Map(issues.map((issue) => [issue, make_initial_state()]))
+function make_initial_state(is_settled: boolean): AwaitState {
+	return { appeared: false, disappeared_at: undefined, first_polled_at: undefined, is_settled }
 }
 
-function resolve_options(options: AwaitOptions): RunConfig {
+async function make_states(
+	issues: ReadonlyArray<string>,
+	is_settled: (issue: string) => Promise<boolean>,
+): Promise<Map<string, AwaitState>> {
+	const settled = await Promise.all(issues.map(async (issue) => await is_settled(issue)))
+
+	return new Map(issues.map((issue, index) => [issue, make_initial_state(settled[index] === true)]))
+}
+
+function resolve_timing(
+	options: AwaitOptions,
+): Pick<RunConfig, 'never_appeared_timeout_ms' | 'poll_ms' | 'reconfirm_ms'> {
 	return {
-		is_running: options.is_running ?? is_process_running_default,
 		poll_ms: options.poll_ms ?? DEFAULT_POLL_MS,
 		reconfirm_ms: options.reconfirm_ms ?? RECONFIRM_MS,
 		never_appeared_timeout_ms: options.never_appeared_timeout_ms ?? NEVER_APPEARED_TIMEOUT_MS,
 	}
 }
 
+function resolve_options(options: AwaitOptions): RunConfig {
+	return {
+		is_running: options.is_running ?? is_process_running_default,
+		is_settled: options.is_settled ?? is_settled_default,
+		...resolve_timing(options),
+	}
+}
+
 function update_liveness(state: AwaitState, is_live: boolean): void {
 	if (!is_live) return
 
@@ -79,13 +105,16 @@ function update_liveness(state: AwaitState, is_live: boolean): void {
 	state.disappeared_at = undefined
 }
 
-// Throws if the issue never appeared within the timeout window; otherwise records the first-seen time.
+// Returns the issue when it had already settled before the wait started — it ended and will never
+// appear. Otherwise throws if it never appeared within the timeout window, and records the first-seen time.
 function check_not_appeared(
 	issue: string,
 	state: AwaitState,
 	now_ms: number,
 	timeout_ms: number,
-): void {
+): string | undefined {
+	if (state.is_settled === true) return issue
+
 	state.first_polled_at ??= now_ms
 	const elapsed_ms = now_ms - state.first_polled_at
 
@@ -94,10 +123,13 @@ function check_not_appeared(
 			`lane child ${issue} never appeared within ${String(timeout_ms / MS_PER_SECOND)}s`,
 		)
 	}
+
+	return undefined
 }
 
 // Returns the issue that has confirmed-completed this tick, `undefined` if none yet.
-// The `appeared` guard prevents a process that never showed up from being declared done.
+// The `appeared` guard prevents a process that never showed up from being declared done, unless its
+// issue had already settled when the wait started.
 function check_issue(
 	issue: string,
 	state: AwaitState,
@@ -111,9 +143,7 @@ function check_issue(
 	if (is_live) return undefined
 
 	if (!state.appeared) {
-		check_not_appeared(issue, state, now_ms, config.never_appeared_timeout_ms)
-
-		return undefined
+		return check_not_appeared(issue, state, now_ms, config.never_appeared_timeout_ms)
 	}
 
 	if (state.disappeared_at === undefined) {
@@ -144,7 +174,7 @@ async function wait_for_any(
 	options: AwaitOptions = {},
 ): Promise<string> {
 	const config = resolve_options(options)
-	const states = make_states(issues)
+	const states = await make_states(issues, config.is_settled)
 
 	for (;;) {
 		const completed = check_any(states, Date.now(), config)

package/scripts/lane/lane-close.ts

@@ -1,6 +1,7 @@
 import { existsSync, rmSync } from 'node:fs'
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { error_text } from '#scripts/lib/error-message'
 import { lane_paths } from './lane-paths'
 import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
@@ -147,7 +148,9 @@ async function try_close(issue: string): Promise<boolean> {
 		const outcome = await close_lane(issue)
 
 		return outcome.kind !== 'incomplete'
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('lane_close.try_close', error)
+
 		return false
 	}
 }

package/scripts/lane/lane-launch-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { josh_command } from '#scripts/josh/josh-run'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
@@ -35,21 +35,15 @@ interface LaunchContext {
 }
 
 function read_context(argv: ReadonlyArray<string>): LaunchContext | undefined {
-	try {
-		const parsed = parseArgs({
-			args: [...argv],
-			options: OPTIONS,
-			strict: true,
-			allowPositionals: true,
-		})
-		const [issue, ...rest] = parsed.positionals
-
-		if (issue === undefined || rest.length > 0 || !ISSUE_PATTERN.test(issue)) return undefined
-
-		return { issue, stash: parsed.values.stash }
-	} catch {
-		return undefined
-	}
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined) return undefined
+
+	const [issue, ...rest] = parsed.positionals
+
+	if (issue === undefined || rest.length > 0 || !ISSUE_PATTERN.test(issue)) return undefined
+
+	return { issue, stash: parsed.values.stash }
 }
 
 // The pop brought in the `pnpm-lock.yaml` `josh latest` rewrote, so this one lane installs a second

package/scripts/lane/openai-review-broker.ts

@@ -6,6 +6,7 @@ import { agent_argv } from '#scripts/agent/agent-argv'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review } from '#scripts/run/run-ship-review'
 import { z } from 'zod'
@@ -102,7 +103,9 @@ function write_response(target: string, body: z.infer<typeof response_schema>):
 async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
 	try {
 		return await launch_review(lane, round)
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('openai_review_broker.launched', error)
+
 		return false
 	}
 }

package/scripts/lib/cli-flags.ts

@@ -1,4 +1,4 @@
-import { parseArgs, type ParseArgsConfig } from 'node:util'
+import { parseArgs, type ParseArgsConfig, type ParseArgsOptionsConfig } from 'node:util'
 
 // Argument reading for the commands under `scripts/`.
 //
@@ -32,6 +32,35 @@ function parse_or_undefined<T extends ParseArgsConfig>(
 	}
 }
 
-const cli_flags = { refuse_unknown_flags, parse_or_undefined }
+// The two shapes every command reads `argv` in: flags alone, or flags beside positionals. Both are
+// strict, so an unknown flag is `undefined` rather than a silently ignored typo; the commands had each
+// carried a one-line wrapper spelling these out (joshuafolkken/kit#3072).
+type FlagsOnly<T extends ParseArgsOptionsConfig> = ReturnType<
+	typeof parseArgs<{ args: Array<string>; options: T }>
+>
+type WithPositionals<T extends ParseArgsOptionsConfig> = ReturnType<
+	typeof parseArgs<{ args: Array<string>; options: T; allowPositionals: true }>
+>
+
+function values_of<T extends ParseArgsOptionsConfig>(
+	argv: ReadonlyArray<string>,
+	options: T,
+): FlagsOnly<T>['values'] | undefined {
+	return parse_or_undefined({ args: [...argv], options })?.values
+}
+
+function arguments_of<T extends ParseArgsOptionsConfig>(
+	argv: ReadonlyArray<string>,
+	options: T,
+): WithPositionals<T> | undefined {
+	return parse_or_undefined({ args: [...argv], options, allowPositionals: true })
+}
+
+// A string option's value, or `undefined` where the flag was absent or parsed as anything else.
+function string_of(value: unknown): string | undefined {
+	return typeof value === 'string' ? value : undefined
+}
+
+const cli_flags = { refuse_unknown_flags, parse_or_undefined, values_of, arguments_of, string_of }
 
 export { cli_flags }

package/scripts/lib/error-message.ts

@@ -4,6 +4,17 @@ function message_of(error: unknown): string {
 	return error instanceof Error ? error.message : String(error)
 }
 
-const error_text = { message_of }
+const DEBUG_ENV_KEY = 'JOSH_DEBUG'
+
+// A catch that folds a failure into a state verdict — "dirty", "not merged", "not written" — leaves no
+// trace of why by default, so a wrong verdict cannot be followed back to its cause (joshuafolkken/kit#3067).
+// `JOSH_DEBUG` set to any non-blank value writes the swallowed reason to stderr; unset, nothing changes.
+function trace_swallowed(where: string, error: unknown): void {
+	if ((process.env[DEBUG_ENV_KEY] ?? '').trim() === '') return
+
+	process.stderr.write(`josh debug: ${where}: ${message_of(error)}\n`)
+}
+
+const error_text = { message_of, trace_swallowed }
 
 export { error_text }

package/scripts/lines/line-targets.ts

@@ -40,10 +40,6 @@ const LS_FILES_FLAGS: ReadonlyArray<string> = [
 	'-z',
 ]
 const NUL = '\0'
-// `--show-toplevel` prints the absolute repository (or worktree) root from anywhere inside it, so the
-// root-relative names `--full-name` returns resolve to the right absolute paths wherever the command
-// was invoked.
-const SHOW_TOPLEVEL: ReadonlyArray<string> = ['rev-parse', '--show-toplevel']
 
 function is_lint_target(relative_path: string): boolean {
 	return LINT_EXTENSIONS.has(path.extname(relative_path))
@@ -53,12 +49,6 @@ function split_names(output: string): ReadonlyArray<string> {
 	return output.split(NUL).filter((name) => name.length > 0)
 }
 
-// `git_spawn.read` is the one place ordinary git commands are spawned from, so this reuses it rather
-// than growing a second spawn site (joshuafolkken/kit#1640).
-async function repo_root(): Promise<string> {
-	return await git_spawn.read([...SHOW_TOPLEVEL])
-}
-
 // The names resolve against the repository `root`, never the process cwd: `--full-name` prints them
 // relative to the root wherever the command runs, so resolving against cwd would double the prefix
 // and drop every file when the command is invoked from a subdirectory.
@@ -73,7 +63,6 @@ async function lint_target_files(root: string): Promise<ReadonlyArray<string>> {
 const line_targets = {
 	is_lint_target,
 	lint_target_files,
-	repo_root,
 	split_names,
 }
 

package/scripts/lines/lines-command.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
 import { line_budget, type FileBudget, type LineBudget } from './line-budget'
 import { line_targets } from './line-targets'
 
@@ -122,10 +123,11 @@ function render(budgets: ReadonlyArray<FileBudget>, project_root: string): strin
 	return [header(budgets), ...rows_for(budgets, project_root)].join('\n')
 }
 
-// The scan resolves the repository root first — `budgets_for` and the row display both key off it — so
-// a run started from a subdirectory reports the same files as one started from the root.
+// The scan resolves the repository root first — `budgets_for` and the row display both key off it, and
+// `git ls-files --full-name` names files relative to it — so a run started from a subdirectory reports
+// the same files as one started from the root.
 async function run_scan(): Promise<number> {
-	const root = await line_targets.repo_root()
+	const root = await git_command.repository_root()
 	const budgets = await scan_budgets(root)
 
 	process.stdout.write(`${render(budgets, root)}\n`)

package/scripts/propagate/propagate-git.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { git_location_environment } from '#scripts/git/git-location-environment'
 import { ls_remote_branch_arguments } from '#scripts/git/git-ls-remote'
-import { execaSync } from 'execa'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 
 // The git probes propagation needs before it writes anything into a working tree.
 //
@@ -16,7 +16,6 @@ const GIT_TIMEOUT_MS = 10_000
 // `rev-parse` and tight for an ssh handshake, and a probe that times out answers "no" — which for
 // the two below would report a push that never reached origin as a push nobody attempted.
 const REMOTE_TIMEOUT_MS = 60_000
-const SUCCESS_EXIT_CODE = 0
 const DEFAULT_BRANCH_REF = 'refs/remotes/origin/HEAD'
 const FALLBACK_DEFAULT_BRANCH = 'main'
 const ORIGIN_PREFIX = 'refs/remotes/origin/'
@@ -54,15 +53,11 @@ function run_git(
 	args: ReadonlyArray<string>,
 	timeout_ms: number = GIT_TIMEOUT_MS,
 ): string | undefined {
-	const result = execaSync('git', args, {
+	return git_spawn_sync.read(args, {
 		cwd: repository_path,
-		reject: false,
 		timeout: timeout_ms,
-		env: { LC_ALL: 'C', LANGUAGE: 'C', ...git_location_environment.location_free_environment() },
-		extendEnv: true,
+		env: { ...git_spawn_sync.C_LOCALE, ...git_location_environment.location_free_environment() },
 	})
-
-	return result.exitCode === SUCCESS_EXIT_CODE ? result.stdout.trim() : undefined
 }
 
 // The repository's default branch, from the remote's own HEAD. Falls back to `main` when the ref is

package/scripts/refactor/refactor-scan.ts

@@ -1,3 +1,4 @@
+import { git_command } from '#scripts/git/git-command'
 import { line_targets } from '#scripts/lines/line-targets'
 import { import_graph } from './import-graph'
 import { refactor_lint, type CategoryResult } from './refactor-lint'
@@ -97,7 +98,7 @@ async function scan(root: string): Promise<ScanResult> {
 }
 
 async function run_scan(): Promise<number> {
-	const root = await line_targets.repo_root()
+	const root = await git_command.repository_root()
 	const result = await scan(root)
 
 	process.stdout.write(`${render_result(result)}\n`)

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

@@ -99,25 +99,33 @@ function is_github_tarball_line(line: string): boolean {
 	return line.trimStart().startsWith('tarball: https://npm.pkg.github.com/')
 }
 
-function clean_kit_line(
+// Integrities are keyed by `name@version`, so two scoped packages sharing a version never collide.
+function package_id(key: string): string {
+	const name = fix_gh_packages_logic.package_path_from_key(key)
+
+	return `${name}@${fix_gh_packages_logic.package_version_from_key(key)}`
+}
+
+function clean_scoped_line(
 	line: string,
-	version: string,
+	id: string,
 	integrities: ReadonlyMap<string, IntegrityPair>,
 ): string | undefined {
-	if (!version) return line
+	if (!id) return line
 	if (is_github_tarball_line(line)) return undefined
 	const cleaned = remove_flow_tarball(line)
-	const pair = integrities.get(version)
+	const pair = integrities.get(id)
 	if (pair === undefined) return cleaned
 
 	return cleaned.split(`integrity: ${pair[0]}`).join(`integrity: ${pair[1]}`)
 }
 
-function next_kit_version(line: string, version: string): string {
-	if (!is_package_entry(line)) return version
-	const prefix = "  '@joshuafolkken/kit@"
+function next_scoped_id(line: string, id: string): string {
+	if (!is_package_entry(line)) return id
+	const prefix = `  '${SCOPE}/`
+	if (!line.startsWith(prefix)) return ''
 
-	return line.startsWith(prefix) ? (line.slice(prefix.length).split("'", 1)[0] ?? '') : ''
+	return package_id(line.slice("  '".length).split("'", 1)[0] ?? '')
 }
 
 function integrity_pair(
@@ -135,12 +143,12 @@ function lock_integrities(
 ): Map<string, IntegrityPair> {
 	const packages = fix_gh_packages_logic.parse_lockfile_packages(lockfile)
 	const pairs = new Map<string, IntegrityPair>()
-	const kit_entries = Object.entries(packages).filter(([key]) => key.startsWith(`${SCOPE}/kit@`))
+	const scoped_entries = Object.entries(packages).filter(([key]) => key.startsWith(`${SCOPE}/`))
 
-	for (const [key, entry] of kit_entries) {
-		const version = fix_gh_packages_logic.package_version_from_key(key)
-		const pair = integrity_pair(entry.resolution?.integrity, npm_integrities.get(version))
-		if (pair !== undefined) pairs.set(version, pair)
+	for (const [key, entry] of scoped_entries) {
+		const id = package_id(key)
+		const pair = integrity_pair(entry.resolution?.integrity, npm_integrities.get(id))
+		if (pair !== undefined) pairs.set(id, pair)
 	}
 
 	return pairs
@@ -150,17 +158,17 @@ function push_if_defined(lines: Array<string>, cleaned: string | undefined): voi
 	if (cleaned !== undefined) lines.push(cleaned)
 }
 
-function rewrite_kit_lockfile(
+function rewrite_scoped_lockfile(
 	lockfile: string,
 	npm_integrities: ReadonlyMap<string, string>,
 ): string {
-	let kit_version = ''
+	let id = ''
 	const lines: Array<string> = []
 	const integrities = lock_integrities(lockfile, npm_integrities)
 
 	for (const line of lockfile.split('\n')) {
-		kit_version = next_kit_version(line, kit_version)
-		const cleaned = clean_kit_line(line, kit_version, integrities)
+		id = next_scoped_id(line, id)
+		const cleaned = clean_scoped_line(line, id, integrities)
 
 		push_if_defined(lines, cleaned)
 	}
@@ -206,7 +214,8 @@ function previous_registry(project_npmrc: string, user_npmrc: string): string {
 
 function plan(project_npmrc: string, user_npmrc: string, lockfile: string): MigrationPlan {
 	const packages = scoped_packages(lockfile)
-	const blocked = packages.filter((name) => name !== `${SCOPE}/kit`)
+	// Every scoped package may migrate; `migrate` blocks any whose locked version is not on public npm.
+	const blocked: Array<string> = []
 	if (has_duplicate_mapping(project_npmrc, user_npmrc)) blocked.push('duplicate registry mappings')
 	const unsupported = unsupported_registry(project_npmrc)
 	if (unsupported !== undefined) blocked.push(unsupported)
@@ -220,7 +229,7 @@ const migrate_logic = {
 	plan,
 	github_tarballs,
 	is_github_tarball,
-	rewrite_kit_lockfile,
+	rewrite_scoped_lockfile,
 	scoped_versions,
 }
 

package/scripts/registry-migration/migrate.ts

@@ -115,8 +115,9 @@ async function verify_public_versions(
 
 	for (const [index, [name, version]] of versions.entries()) {
 		const integrity = probed[index]
-		if (integrity === undefined) missing.push(`${name}@${version}`)
-		else integrities.set(version, integrity)
+		const id = `${name}@${version}`
+		if (integrity === undefined) missing.push(id)
+		else integrities.set(id, integrity)
 	}
 
 	return { missing, integrities }
@@ -183,7 +184,7 @@ async function verify_resolution(
 	const old_tarballs = migrate_logic.github_tarballs(lockfile)
 	if (old_tarballs.length > 0) throw new Error(`GitHub tarballs remain: ${old_tarballs.join(', ')}`)
 
-	if (migrate_logic.rewrite_kit_lockfile(lockfile, integrities) !== lockfile) {
+	if (migrate_logic.rewrite_scoped_lockfile(lockfile, integrities) !== lockfile) {
 		throw new Error('lockfile integrity does not match public npm')
 	}
 }
@@ -197,7 +198,7 @@ async function apply(
 		writeFileSync(context.npmrc_path, context.plan.content)
 		writeFileSync(
 			context.lockfile_path,
-			migrate_logic.rewrite_kit_lockfile(context.original_lockfile, integrities),
+			migrate_logic.rewrite_scoped_lockfile(context.original_lockfile, integrities),
 		)
 		await verify_resolution(context, dependencies, integrities)
 	} catch (error) {
@@ -215,7 +216,7 @@ function is_already_migrated(
 ): boolean {
 	return (
 		context.plan.content === context.original_npmrc &&
-		migrate_logic.rewrite_kit_lockfile(context.original_lockfile, integrities) ===
+		migrate_logic.rewrite_scoped_lockfile(context.original_lockfile, integrities) ===
 			context.original_lockfile
 	)
 }

package/scripts/release/github-release-cli.ts

@@ -1,13 +1,24 @@
-import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { github_release } from './github-release'
 import { github_release_environment } from './github-release-environment'
 
+// A release published without the tag list would pick its previous tag from nothing, so a failed
+// `git tag` stops the run rather than reading as "no tags".
+function local_tags(): Array<string> {
+	const output = git_spawn_sync.read(['tag', '--list'])
+	if (output === undefined) throw new Error('git tag --list failed')
+
+	return output.split('\n')
+}
+
 async function main(): Promise<void> {
 	const { token, tag, settings } = github_release_environment.read_release_input(process.env)
-	const tags = execFileSync('git', ['tag', '--list'], { encoding: 'utf8' }).trim().split('\n')
 
-	console.info(await github_release.publish(fetch, token, tag, { ...settings, tags }))
+	console.info(await github_release.publish(fetch, token, tag, { ...settings, tags: local_tags() }))
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+const github_release_cli = { local_tags }
+export { github_release_cli }

package/scripts/release/release-publish.ts

@@ -2,6 +2,7 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_pr_checks } from '#scripts/gh/git-pr-checks'
 import { git_command } from '#scripts/git/git-command'
 import { git_remote_branch } from '#scripts/git/git-remote-branch'
+import { repository_lock } from '#scripts/git/repository-lock'
 import { write_version } from '#scripts/version/bump-version'
 import { version_targets } from '#scripts/version/version-targets'
 import type { ReleasePlan } from './release-plan'
@@ -20,6 +21,9 @@ const { PACKAGE_JSON } = version_targets
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const IGNORE_FOR_RELEASE_LABEL = 'ignore-for-release'
+const RELEASE_LOCK_PREFIX = 'josh-release-lock-'
+// A release waits on CI for minutes, so a second run refuses rather than queueing behind it.
+const RELEASE_LOCK_MAX_WAIT_MS = 0
 
 function branch_name_for(version: string): string {
 	return `release/v${version}`
@@ -87,6 +91,14 @@ async function refuse_existing_branch(branch_name: string): Promise<void> {
 	throw new Error(existing_branch_message(branch_name))
 }
 
+// **The leftovers go before the guard asks** (joshuafolkken/kit#3058). A run cut off before its
+// `finally`, or a `worktree add` that failed after creating its branch, leaves a local
+// `release/v<version>` that the guard would otherwise refuse as a release already opened.
+async function clear_the_way(branch_name: string): Promise<void> {
+	await release_worktree.clear_leftover()
+	await refuse_existing_branch(branch_name)
+}
+
 // **No `checkout -b` and no branch guard here** (joshuafolkken/kit#2411). The work tree is already
 // sitting on the release branch — `release_worktree.create` cut it that way — and the guard ran
 // before that creation, because `worktree_add` makes the branch local and `branch_exists` would then
@@ -121,10 +133,10 @@ async function merge_and_tag(plan: ReleasePlan, branch_name: string): Promise<nu
 // branch guard runs before the tree exists, `process.chdir` points the version write and the git
 // commands at the tree, and the `finally` returns to the root and removes the tree — whichever way
 // the wait ended, so a failed tag watch cleans up rather than leaving debris behind.
-async function publish(plan: ReleasePlan): Promise<number> {
+async function publish_locked(plan: ReleasePlan): Promise<number> {
 	const branch_name = branch_name_for(plan.next_version)
 
-	await refuse_existing_branch(branch_name)
+	await clear_the_way(branch_name)
 
 	const directory = await release_worktree.create(branch_name)
 	const previous_cwd = process.cwd()
@@ -140,6 +152,28 @@ async function publish(plan: ReleasePlan): Promise<number> {
 	}
 }
 
+function release_running_message(target: string): string {
+	return `Another \`pnpm josh release\` is running in this repository (lock \`${target}\`); wait for it to finish, then run it again.`
+}
+
+// **One release at a time per repository, held for the whole run** (joshuafolkken/kit#3058).
+// `clear_leftover` removes an unpushed, commit-less release branch, which is also what a live run
+// looks like while it installs dependencies — so it may only run once no other release is alive. The
+// lock answers that: a run cut off before its `finally` leaves a record whose owner is gone, which
+// `repository_lock` clears on the next claim, while a live owner makes this run refuse at once.
+async function publish(plan: ReleasePlan): Promise<number> {
+	const target = repository_lock.lock_path(RELEASE_LOCK_PREFIX)
+	const exit_code = await repository_lock.with_lock(
+		async () => await publish_locked(plan),
+		target,
+		RELEASE_LOCK_MAX_WAIT_MS,
+	)
+
+	if (exit_code === undefined) throw new Error(release_running_message(target))
+
+	return exit_code
+}
+
 const release_publish = {
 	branch_name_for,
 	commit_message,