@joshuafolkken/kit 1.872.0

package/scripts/git/git-push.ts

@@ -0,0 +1,27 @@
+import { animation_helpers, create_git_operation_config } from './animation-helpers'
+import { git_command } from './git-command'
+
+async function push(): Promise<void> {
+	const config = create_git_operation_config('')
+
+	console.info('')
+	await animation_helpers.execute_with_animation(
+		'Pushing changes to remote...',
+		async (pause_animation: (() => void) | undefined) => {
+			if (pause_animation !== undefined) {
+				pause_animation()
+			}
+
+			await git_command.push()
+
+			return 'Push completed.'
+		},
+		config,
+	)
+}
+
+const git_push = {
+	push,
+}
+
+export { git_push }

package/scripts/git/git-remote-branch.ts

@@ -0,0 +1,40 @@
+import { git_worktree } from './git-worktree'
+
+// Does origin still have this branch, and could we even tell? (joshuafolkken/kit#1641; lifted out of
+// `scripts/lane/lane-start-point.ts`, which asked the question first.)
+//
+// **The remote-tracking ref is not evidence that the remote still has the branch.** Nothing here
+// prunes it — `lane:close` removes the work tree and the local branch, GitHub deletes the remote
+// branch at the merge, and the ref survives both — so reading one as "origin has it" answers about
+// whatever this checkout last fetched. `ls-remote` is asked instead, because it separates the two
+// answers a `fetch` failure runs together: a branch that is gone, from a remote that cannot be
+// reached.
+//
+// **Two callers need that same three-way answer, which is why it lives here rather than inside
+// either of them.** `lane-start-point.ts` decides which ref a reopened lane is cut from, and
+// `release-publish.ts` decides whether a release branch name is already taken. What each of them
+// *does* with an answer differs — a lane degrades to the tracking ref and says so, a release refuses
+// outright — so the shared part is the asking alone, and copying it into the second caller would be
+// the clone `CLAUDE.md` prohibits.
+type RemoteAnswer = 'absent' | 'present' | 'unreachable'
+
+// Empty output on a zero exit is `absent`; any output is `present`; a rejection — `ls-remote` exits
+// non-zero when the transport fails, and `git_spawn.read` turns that into a throw — is
+// `unreachable`, **never folded into `absent`**. Folding them is what makes a guard answer "nothing
+// there" to a question it could not ask.
+async function ask(branch_name: string): Promise<RemoteAnswer> {
+	try {
+		const heads = await git_worktree.ls_remote_branch(branch_name)
+
+		return heads.trim() === '' ? 'absent' : 'present'
+	} catch {
+		return 'unreachable'
+	}
+}
+
+const git_remote_branch = {
+	ask,
+}
+
+export { git_remote_branch }
+export type { RemoteAnswer }

package/scripts/git/git-spawn.ts

@@ -0,0 +1,47 @@
+import { execa } from 'execa'
+import { git_utilities } from './constants'
+import { create_spawn_error, get_exit_code } from './git-execa-error'
+
+// The one place the ordinary git commands are spawned from (joshuafolkken/kit#1640). It sits in a
+// module of its own rather than inside `git-command.ts` so that a second command module —
+// `git-worktree.ts` — can read it without importing the first. `read` is what resolves the git binary
+// and turns a non-zero exit into an error, and a second spawn helper beside it would be the clone
+// `CLAUDE.md` prohibits, so a new caller imports this one instead of growing its own.
+//
+// **`git-push-transport.ts` is the one deliberate exception among the command modules** and is not a
+// second helper of this kind: a push needs a timeout and a transport-fault retry that no other
+// command has, so it spawns git itself. Those two files are the spawn sites of the ordinary command
+// modules — the claim stops there. Other parts of this package spawn git for their own purposes
+// (`scripts/run/run-progress-clock.ts`, `scripts/propagate/propagate-git.ts`,
+// `scripts/doctor/doctor-io.ts`, `scripts/git/git-fixture-workspace.ts`), and an audit of how the git
+// binary is resolved has to read those too.
+
+async function read(arguments_: Array<string>): Promise<string> {
+	const git_cmd = git_utilities.get_git_command_for_spawn()
+	// execa runs the binary directly with an argument array and no `shell` option, so CLI
+	// args cannot break out of a shell sandbox; the git command and args are internally
+	// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
+	const { stdout } = await execa(git_cmd, arguments_) // NOSONAR
+
+	return stdout.trimEnd()
+}
+
+async function with_output(command: string, arguments_list: Array<string>): Promise<void> {
+	const git_command_bin = git_utilities.get_git_command_for_spawn()
+
+	try {
+		// execa runs the binary directly with an argument array and no `shell` option, so CLI
+		// args cannot break out of a shell sandbox; the git command and args are internally
+		// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
+		await execa(git_command_bin, [command, ...arguments_list], { stdio: 'inherit' }) // NOSONAR
+	} catch (error) {
+		throw create_spawn_error(command, get_exit_code(error))
+	}
+}
+
+const git_spawn = {
+	read,
+	with_output,
+}
+
+export { git_spawn }

package/scripts/git/git-staging.ts

@@ -0,0 +1,128 @@
+import {
+	observation_ledger,
+	OBSERVATION_LEDGER_PATH,
+} from '#scripts/observations/observation-ledger'
+import { git_command } from './git-command'
+import { git_prompt } from './git-prompt'
+import { git_status } from './git-status'
+
+async function confirm_package_json_staged(should_force = false): Promise<boolean> {
+	const is_package_json_staged = await git_status.check_package_json_staged()
+
+	if (!is_package_json_staged) {
+		if (should_force) {
+			console.info('💡 Skipping package.json staging check (force).')
+
+			return false
+		}
+
+		await git_prompt.confirm_missing_package_json()
+
+		return false
+	}
+
+	return true
+}
+
+async function confirm_package_json_version(should_force = false): Promise<void> {
+	const is_version_updated = await git_status.check_package_json_version()
+
+	if (is_version_updated) {
+		return
+	}
+
+	if (should_force) {
+		console.info('💡 Skipping package.json version check (force).')
+
+		return
+	}
+
+	await git_prompt.confirm_without_version_update()
+}
+
+async function check_and_confirm_package_json(should_force = false): Promise<void> {
+	const is_already_updated = await git_status.check_branch_version()
+
+	if (is_already_updated) {
+		console.info('💡 Version already updated on this branch. Skipping package.json check.')
+
+		return
+	}
+
+	const is_staged = await confirm_package_json_staged(should_force)
+
+	if (is_staged) {
+		await confirm_package_json_version(should_force)
+	}
+}
+
+async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void> {
+	if (files.length === 0) return
+
+	for (const file of files) {
+		await git_command.add_path(file)
+	}
+
+	console.info(`💡 Auto-staged ${String(files.length)} untracked non-ignored file(s):`)
+	for (const file of files) console.info(`   + ${file}`)
+}
+
+// **The observation ledger is never staged by an ordinary commit** (joshuafolkken/kit#1756). A
+// parent session appends to it in the primary checkout and nothing there commits it, so the next
+// `pnpm josh git` run in that checkout swept the line into a pull request about something else
+// entirely — a diff a reviewer has no reason to question. Excluding it here covers every entry
+// point, because this is the one staging step all of them go through;
+// `pnpm josh observations:flush` is what commits it, on a branch of its own.
+const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = [OBSERVATION_LEDGER_PATH]
+
+function is_stageable(file_path: string): boolean {
+	return !PATHS_EXCLUDED_FROM_STAGING.includes(file_path)
+}
+
+// **Said out loud, because the alternative is an unexplained failure.** With the ledger the only
+// thing changed, `git_status.check_unstaged` still answers true, nothing is staged, and the commit
+// step dies on git's empty index with `Failed to commit changes` — a message naming nothing that
+// caused it. This line is what turns that into a diagnosis.
+//
+// **The paths are parsed rather than matched as substrings**: `docs/observations.md.bak` contains the
+// ledger's path, and a hint naming a file the exclusion never touched is a hint that teaches the
+// reader to ignore it.
+function report_excluded_paths(status_output: string): void {
+	const excluded = status_output
+		.split('\n')
+		.filter((line) => line.trim().length > 0)
+		.map((line) => observation_ledger.status_path(line))
+		.filter((file_path) => !is_stageable(file_path))
+
+	for (const file_path of excluded) {
+		console.info(`💡 ${file_path} is not staged; commit it with \`pnpm josh observations:flush\`.`)
+	}
+}
+
+async function stage_tracked_files(): Promise<void> {
+	const status_output = await git_command.status()
+	const untracked = git_status
+		.list_untracked_files(status_output)
+		.filter((file_path) => is_stageable(file_path))
+
+	await git_command.add_tracked(PATHS_EXCLUDED_FROM_STAGING)
+	console.info('💡 Auto-staged tracked modified files (git add -u).')
+	report_excluded_paths(status_output)
+	await stage_untracked_files(untracked)
+}
+
+async function check_and_confirm_staging(should_force = false): Promise<void> {
+	const has_unstaged = await git_status.check_unstaged()
+
+	if (has_unstaged) {
+		await (should_force ? stage_tracked_files() : git_prompt.confirm_unstaged_files())
+	}
+
+	await check_and_confirm_package_json(should_force)
+}
+
+const git_staging = {
+	check_and_confirm_staging,
+}
+
+export { git_staging }

package/scripts/git/git-stash.ts

@@ -0,0 +1,124 @@
+import { git_spawn } from './git-spawn'
+
+// The one place a sanctioned `git stash pop` is targeted by its message rather than its stack
+// position (joshuafolkken/kit#2050). The stash is a single repository-wide stack shared by every
+// working tree of the repository, so a bare `git stash pop` — or a positional `stash@{n}` read
+// before another lane pushed — pops whatever now sits on top, which is how one lane's parked work
+// ended up in another lane's tree. Resolving the selector from the message the stash was pushed
+// with, immediately before the pop, targets the entry itself rather than a position that moves.
+
+const ENTRY_SEPARATOR = '\n'
+// A NUL between the two fields, because the subject carries the spaces and colons a message repeats.
+const FIELD_SEPARATOR = '\u{0}'
+// `%gd` is the selector (`stash@{0}`), `%gs` the reflog subject (`On <branch>: <message>` for a
+// stash pushed with `-m`); `%x00` emits the NUL the fields are split on.
+const LIST_FORMAT = '--format=%gd%x00%gs'
+const SUBJECT_MESSAGE_SEPARATOR = ': '
+
+interface StashEntry {
+	selector: string
+	subject: string
+}
+
+type Selection =
+	| { kind: 'match'; selector: string }
+	| { kind: 'none' }
+	| { kind: 'ambiguous'; selectors: ReadonlyArray<string> }
+
+function to_entry(line: string): StashEntry | undefined {
+	const [selector, subject] = line.split(FIELD_SEPARATOR)
+
+	if (selector === undefined || subject === undefined) return undefined
+
+	return { selector, subject }
+}
+
+function parse_entries(raw: string): Array<StashEntry> {
+	if (raw === '') return []
+
+	return raw
+		.split(ENTRY_SEPARATOR)
+		.map((line) => to_entry(line))
+		.filter((entry): entry is StashEntry => entry !== undefined)
+}
+
+// A stash pushed with `-m "<message>"` lists as `On <branch>: <message>`, and one pushed by a step
+// that gave no branch context lists as `<message>` verbatim. Both are matched, and the `: ` suffix
+// test keeps `#20` from matching a message that merely ends in `#200`.
+function matches(subject: string, message: string): boolean {
+	return subject === message || subject.endsWith(`${SUBJECT_MESSAGE_SEPARATOR}${message}`)
+}
+
+function select(entries: ReadonlyArray<StashEntry>, message: string): Selection {
+	const found = entries.filter((entry) => matches(entry.subject, message))
+
+	const [first] = found
+
+	if (first === undefined) return { kind: 'none' }
+
+	if (found.length > 1) {
+		return { kind: 'ambiguous', selectors: found.map((entry) => entry.selector) }
+	}
+
+	return { kind: 'match', selector: first.selector }
+}
+
+// The stash is a repository-level stack every work tree shares, so the list reads the same wherever
+// it runs; `dir` is what makes the pop land in the lane's tree rather than the primary checkout —
+// the `git -C <dir>` a lane child used to write by hand.
+function git_args(directory: string | undefined, args: Array<string>): Array<string> {
+	return directory === undefined ? args : ['-C', directory, ...args]
+}
+
+async function list(directory?: string): Promise<Array<StashEntry>> {
+	return parse_entries(await git_spawn.read(git_args(directory, ['stash', 'list', LIST_FORMAT])))
+}
+
+async function pop(selector: string, directory?: string): Promise<void> {
+	await git_spawn.read(git_args(directory, ['stash', 'pop', selector]))
+}
+
+// `git stash pop` on a content conflict applies the entry, keeps it on the stack, and exits non-zero
+// — the resume path documented in `backlogrun-park.md` ("expect to resolve conflicts"). The non-zero
+// exit is indistinguishable from a real failure by its code alone, so a conflicted pop is told apart
+// by the unmerged paths it leaves: `--diff-filter=U` lists exactly those, empty on any other failure.
+async function has_conflict(directory?: string): Promise<boolean> {
+	const unmerged = await git_spawn.read(
+		git_args(directory, ['diff', '--name-only', '--diff-filter=U']),
+	)
+
+	return unmerged !== ''
+}
+
+// Uncommitted work is anything `git status --porcelain` lists — untracked files included, which is what
+// `push` below carries with `-u`, so the two agree on what "work" means (joshuafolkken/kit#2476).
+async function has_changes(directory?: string): Promise<boolean> {
+	return (await git_spawn.read(git_args(directory, ['status', '--porcelain']))) !== ''
+}
+
+// Push with a message `josh stash:pop` can later target — the stack is shared by every work tree, so an
+// entry pushed from a lane outlives the lane's own tree.
+async function push(message: string, directory?: string): Promise<void> {
+	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message]))
+}
+
+// The message uncommitted work is pushed with, keyed on the issue so `josh stash:pop` can target it and
+// on the occasion so two pushes for one issue — a lane close and an `already-done` read — stay apart.
+function work_message(issue: string, occasion: string): string {
+	return `${issue}: uncommitted work at ${occasion}`
+}
+
+const git_stash = {
+	has_changes,
+	has_conflict,
+	list,
+	matches,
+	parse_entries,
+	pop,
+	push,
+	select,
+	work_message,
+}
+
+export type { Selection, StashEntry }
+export { git_stash }

package/scripts/git/git-status.ts

@@ -0,0 +1,198 @@
+import { animation_helpers, type AnimationOptions } from './animation-helpers'
+import { REQUIRED_STATUS_LENGTH, STAGED_STATUS_INDEX, UNTRACKED_FILE_PREFIX } from './constants'
+import { git_command } from './git-command'
+
+const WARNING_ICON = '🔔'
+const PACKAGE_JSON_FILE = 'package.json'
+const STATUS_PREFIX_LENGTH = 2
+const VERSION_NOT_UPDATED = 'Not updated'
+
+function is_untracked_file(line: string): boolean {
+	return line.startsWith(UNTRACKED_FILE_PREFIX)
+}
+
+function is_unstaged_file(line: string): boolean {
+	return line.length >= REQUIRED_STATUS_LENGTH && line[STAGED_STATUS_INDEX] !== ' '
+}
+
+function parse_status_lines(status_output: string): Array<string> {
+	return status_output
+		.split(/\r?\n/u)
+		.map((line) => line.trimEnd())
+		.filter((line) => line.length > 0)
+}
+
+function has_unstaged_files(status_output: string): boolean {
+	const lines = parse_status_lines(status_output)
+	const has_untracked = lines.some((line) => is_untracked_file(line))
+	const has_unstaged = lines.some((line) => is_unstaged_file(line))
+
+	return has_untracked || has_unstaged
+}
+
+function is_staged_file(line: string): boolean {
+	if (line.length < REQUIRED_STATUS_LENGTH || is_untracked_file(line)) {
+		return false
+	}
+
+	const [staged_status] = line
+
+	return staged_status !== ' '
+}
+
+function has_unstaged_changes(line: string): boolean {
+	return line.length >= REQUIRED_STATUS_LENGTH && line[STAGED_STATUS_INDEX] !== ' '
+}
+
+function has_all_files_staged(status_output: string): boolean {
+	const lines = parse_status_lines(status_output)
+
+	if (lines.length === 0) {
+		return true
+	}
+
+	return lines.every((line) => !has_unstaged_changes(line))
+}
+
+function extract_filename(line: string): string {
+	return line.slice(STATUS_PREFIX_LENGTH).trim()
+}
+
+function is_package_json_staged(status_output: string): boolean {
+	const lines = parse_status_lines(status_output)
+
+	return lines.some((line) => {
+		if (!is_staged_file(line)) {
+			return false
+		}
+
+		const filename = extract_filename(line)
+
+		return filename === PACKAGE_JSON_FILE
+	})
+}
+
+function create_status_check_config(
+	has_warning: (is_check_passing: boolean) => boolean,
+	error_message: string,
+	result_formatter: (is_check_passing: boolean) => string,
+): AnimationOptions<boolean> {
+	return {
+		icon_selector: (is_check_passing) => (has_warning(is_check_passing) ? WARNING_ICON : undefined),
+		error_message,
+		result_formatter,
+	}
+}
+
+function is_version_updated_in_diff(diff_output: string): boolean {
+	const version_pattern = /^[+-].*"version"\s*:/u
+
+	return diff_output.split(/\r?\n/u).some((line) => version_pattern.test(line))
+}
+
+async function check_unstaged(): Promise<boolean> {
+	const config = create_status_check_config(
+		(has_unstaged) => has_unstaged,
+		'Failed to check unstaged files',
+		(has_unstaged) => (has_unstaged ? 'Found' : 'None'),
+	)
+
+	return await animation_helpers.execute_with_animation(
+		'Checking unstaged files...',
+		async () => {
+			const status_output = await git_command.status()
+
+			return has_unstaged_files(status_output)
+		},
+		config,
+	)
+}
+
+async function check_all_staged(): Promise<boolean> {
+	const config = create_status_check_config(
+		(all_staged) => !all_staged,
+		'Failed to check staged files',
+		(all_staged) => (all_staged ? 'All staged' : 'Not all staged'),
+	)
+
+	return await animation_helpers.execute_with_animation(
+		'Checking if all files are staged...',
+		async () => {
+			const status_output = await git_command.status()
+
+			return has_all_files_staged(status_output)
+		},
+		config,
+	)
+}
+
+async function check_package_json_staged(): Promise<boolean> {
+	const config = create_status_check_config(
+		(is_staged) => !is_staged,
+		'Failed to check package.json staging status',
+		(is_staged) => (is_staged ? 'Staged' : 'Not staged'),
+	)
+
+	return await animation_helpers.execute_with_animation(
+		'Checking if package.json is staged...',
+		async () => {
+			const status_output = await git_command.status()
+
+			return is_package_json_staged(status_output)
+		},
+		config,
+	)
+}
+
+async function check_package_json_version(): Promise<boolean> {
+	const config = create_status_check_config(
+		(is_updated) => !is_updated,
+		'Failed to check package.json version update',
+		(is_updated) => (is_updated ? 'Updated' : VERSION_NOT_UPDATED),
+	)
+
+	return await animation_helpers.execute_with_animation(
+		'Checking if package.json version is updated...',
+		async () => {
+			const diff_output: string = await git_command.diff_cached(PACKAGE_JSON_FILE)
+
+			return is_version_updated_in_diff(diff_output)
+		},
+		config,
+	)
+}
+
+async function check_branch_version(): Promise<boolean> {
+	const config = create_status_check_config(
+		(is_updated) => !is_updated,
+		'Failed to check branch version update',
+		(is_updated) => (is_updated ? 'Already updated' : VERSION_NOT_UPDATED),
+	)
+
+	return await animation_helpers.execute_with_animation(
+		'Checking if version is already updated on this branch...',
+		async () => {
+			const diff_output: string = await git_command.diff_main(PACKAGE_JSON_FILE)
+
+			return is_version_updated_in_diff(diff_output)
+		},
+		config,
+	)
+}
+
+function list_untracked_files(status_output: string): Array<string> {
+	return parse_status_lines(status_output)
+		.filter((line) => is_untracked_file(line))
+		.map((line) => extract_filename(line))
+}
+
+const git_status = {
+	check_unstaged,
+	check_all_staged,
+	check_package_json_staged,
+	check_package_json_version,
+	check_branch_version,
+	list_untracked_files,
+}
+
+export { git_status }

package/scripts/git/git-worktree.ts

@@ -0,0 +1,110 @@
+import { PORCELAIN_FLAG } from './constants'
+import { ls_remote_branch_arguments } from './git-ls-remote'
+import { git_spawn } from './git-spawn'
+
+// The four worktree reads and writes a lane's lifecycle needs, plus the branch deletion that ends it
+// (joshuafolkken/kit#1490; split out of `git-command.ts` under joshuafolkken/kit#1640). They live
+// beside the other git commands rather than in `scripts/lane/` because `git_spawn.read` is what
+// resolves the git binary and turns a non-zero exit into an error — a second spawn helper next to it
+// would be the clone `CLAUDE.md` prohibits, so this module imports the shared one.
+//
+// **`ls_remote_branch` is here for the same reason, though it registers no work tree**: it is the
+// asynchronous `git ls-remote` spawn, and a second spawn helper beside it would be that same clone.
+// **It is not the only one in this package** — `propagate_git.has_remote_branch` runs the same query
+// synchronously against a consumer's path, and the two share their arguments through
+// `git-ls-remote.ts` rather than the spawn (joshuafolkken/kit#1732). Its sole
+// caller is now `git-remote-branch.ts`, which turns the raw output into the three-way answer
+// (`absent` / `present` / `unreachable`) that `lane-start-point.ts` and `release-publish.ts` both act
+// on — so this module stops at "what git printed" and the meaning of it is decided there
+// (joshuafolkken/kit#1641; before it, `lane-start-point.ts` was the only reader and did both).
+const WORKTREE = 'worktree'
+
+// Every registered work tree of this repository, in git's own machine-readable form: one `worktree
+// <path>` / `HEAD <sha>` / `branch <ref>` block per tree, blocks separated by a blank line. Parsing
+// it is the caller's, so this module keeps one shape for every reader.
+async function worktree_list(): Promise<string> {
+	return await git_spawn.read([WORKTREE, 'list', PORCELAIN_FLAG])
+}
+
+// `-b` creates the branch as part of the add, so there is no window in which the directory exists on
+// a detached HEAD; `start_point` is passed explicitly rather than left to `HEAD`, because a lane is
+// branched from the default branch whatever the checkout that opened it happens to be sitting on.
+//
+// **`--no-track` is load-bearing now that the start point is a remote-tracking ref**
+// (joshuafolkken/kit#1535). Branching from `refs/remotes/origin/<default>` makes git's default
+// `branch.autoSetupMerge` set `branch.<lane>.merge=refs/heads/<default>`, and a bare `git push` from
+// the lane then fails with "the upstream branch of your current branch does not match the name of
+// your current branch" — which is *not* the missing-upstream error `push()` retries as
+// `--set-upstream`, so every lane's `pnpm josh git` would stop there. Measured against git 2.x.
+//
+// **An absent `start_point` attaches the tree to the branch that is already there, and neither flag
+// is passed then** (joshuafolkken/kit#1627). `-b` refuses a branch that exists, so a lane whose child
+// had already pushed could not be reopened at all; deleting the branch first to get `-b` back would
+// discard those commits and orphan the pull request. `--no-track` cannot ride along either — git
+// answers `--[no-]track can only be used if a new branch is created` — and it has nothing to do here:
+// whatever upstream the branch was given when it was created is still on it.
+async function worktree_add(
+	directory: string,
+	branch_name: string,
+	start_point: string | undefined,
+): Promise<string> {
+	const flags = start_point === undefined ? ['add'] : ['add', '--no-track', '-b', branch_name]
+
+	return await git_spawn.read([WORKTREE, ...flags, directory, start_point ?? branch_name])
+}
+
+// A throwaway tree at one commit, on no branch — `josh test:red` checks the merge-base out here, so
+// the pre-fix tree is built without creating a branch or touching the caller's tree and index
+// (joshuafolkken/kit#2448).
+async function worktree_add_detached(directory: string, commit: string): Promise<string> {
+	return await git_spawn.read([WORKTREE, 'add', '--detach', directory, commit])
+}
+
+// **`--force` is the point, not a convenience.** A lane is closed after a park, a failure or an
+// interruption as readily as after a success, and in each of those the tree still holds uncommitted
+// or untracked work. Refusing to remove it there would leave exactly the debris the close exists to
+// prevent.
+async function worktree_remove(directory: string): Promise<string> {
+	return await git_spawn.read([WORKTREE, 'remove', '--force', directory])
+}
+
+// Drops the registrations whose directories are already gone — what makes a lane whose directory was
+// deleted by hand recoverable rather than a permanent `worktree add` refusal on that path.
+async function worktree_prune(): Promise<string> {
+	return await git_spawn.read([WORKTREE, 'prune'])
+}
+
+// **Asked of the remote itself, because nothing prunes the remote-tracking refs**
+// (joshuafolkken/kit#1627). `lane:close` deletes the local branch, GitHub deletes the remote one at
+// the merge, and `refs/remotes/origin/<N>-lane` outlives both: this repository carried sixteen of
+// them for branches the remote no longer had. Empty output on a zero exit is therefore "not on the
+// remote", which a stale ref cannot say, and a non-zero exit is "could not ask" — a different answer
+// again, and the reason the caller cannot use `fetch` for this: `fetch` fails identically for a
+// branch that is gone and for a network that is down, and prunes neither (measured on git 2.x).
+//
+// **The arguments come from `git-ls-remote.ts`, which is the single source of the full ref path**
+// (joshuafolkken/kit#1709 for the anchoring, joshuafolkken/kit#1732 for the sharing). What broke
+// here was the truthfulness of the message rather than the safety of the answer: `lane:open` was
+// told origin has the lane branch and then stopped naming a branch nobody could find there, and the
+// release guard refused a name that was free.
+async function ls_remote_branch(branch_name: string): Promise<string> {
+	return await git_spawn.read(ls_remote_branch_arguments(branch_name))
+}
+
+// `-D` rather than `-d`: a lane branch is deleted whatever state its work reached, and `-d` refuses
+// one that was never merged — which is every lane closed after a park or a failure.
+async function branch_delete(branch_name: string): Promise<string> {
+	return await git_spawn.read(['branch', '-D', branch_name])
+}
+
+const git_worktree = {
+	branch_delete,
+	ls_remote_branch,
+	worktree_add,
+	worktree_add_detached,
+	worktree_list,
+	worktree_prune,
+	worktree_remove,
+}
+
+export { git_worktree }