@joshuafolkken/kit 1.872.0

package/scripts/git/git-gh-pr.ts

@@ -0,0 +1,219 @@
+import { poll } from '#scripts/lib/poll'
+import { git_command } from './git-command'
+import { git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+import { git_gh_helpers } from './git-gh-helpers'
+import { git_gh_issue_write } from './git-gh-issue-write'
+import { forget_pr_numbers, git_gh_pr_read, read_pull, require_pr_number } from './git-gh-pr-read'
+import { git_gh_pr_rest } from './git-gh-pr-rest'
+import { git_gh_pr_snapshot } from './git-gh-pr-snapshot'
+
+// The pull-request writes, through REST.
+//
+// `gh pr create` / `comment` / `merge` / `checkout` all go through GraphQL, which a cloud session is
+// answered 403 for while the REST endpoints are served normally (joshuafolkken/kit#1022). The reads
+// converted first — the ones `gh pr view` served in `git-gh-pr-read.ts` (joshuafolkken/kit#1027) and
+// the merge gate's snapshot in `git-gh-pr-snapshot.ts` (joshuafolkken/kit#1028) — and these are the
+// last four calls, plus the one whose API use the epic left unconfirmed.
+//
+// **Every path here was measured against the live API before it was written**, on a throwaway pull
+// request opened between two throwaway branches so that neither `main` nor any real pull request was
+// touched. Two of the four did not behave as reading the documentation would suggest: see
+// `pr_create` for the duplicate-head response and `pr_checkout` for what `gh` actually does.
+//
+// `pr_checks` — a `gh pr checks <branch>` wrapper — is gone rather than converted. Nothing called it:
+// the merge gate reads the rollup out of the snapshot and `git-pr-checks-watch.ts` runs the watching
+// variant, so rebuilding it on REST would have added a second, unread path to the same data.
+
+// The browser URL of the pull request, which is what `gh pr create` printed and what `git-pr.ts`
+// displays. REST answers the whole object, so the same value is unwrapped out of it.
+const HTML_URL_FILTER = '.html_url'
+const PUT_METHOD = 'PUT'
+const PATCH_METHOD = 'PATCH'
+// `gh pr merge --merge` produced a merge commit, and this repository allows nothing else
+// (`allow_squash_merge` and `allow_rebase_merge` are both false). Sent explicitly rather than left to
+// the endpoint's default, so a change to either would fail loudly instead of silently squashing.
+const MERGE_COMMIT_METHOD = 'merge'
+// The one write worth waiting longer for, and the only per-request override in this file. It is the
+// least idempotent request the layer makes, so the failure the shared 60-second budget produces is
+// the expensive one: a merge that landed while the request was already being abandoned. Three
+// minutes lowers how often that happens without leaving the request unbounded — the recovery below
+// is what actually removes the failure mode, and this only makes it rarer (joshuafolkken/kit#1077).
+const MERGE_REQUEST_TIMEOUT_MS = 180_000
+// What a failed merge whose outcome could not be read back is reported as. Deliberately neither
+// "merged" nor "not merged": nobody read it.
+const MERGE_UNCONFIRMED_MESSAGE =
+	'gh api could not read the pull request back after the merge request failed'
+const MERGE_READ_BACK_ATTEMPTS = 3
+const MERGE_READ_BACK_INTERVAL_MS = 1000
+
+// **`head` is required and `gh pr create` never asked for it.** The CLI inferred it from the current
+// branch; REST does not, and a request without it is a 422. The branch is read from git rather than
+// from the pull request the run is about to create.
+//
+// A branch whose previous pull request merged gets a second one, so the branch → number resolution
+// the reads memoize is stale from here on. Clearing it is what keeps `pr_get_url` from answering
+// with the merged pull request afterwards.
+//
+// **The duplicate-head answer is the trap.** `gh pr create` wrote `a pull request for branch … into
+// branch … already exists` to stderr, and `handle_pr_create_error` turns any `already exists` into
+// the `PR_ALREADY_EXISTS` that `git-pr.ts` recovers from. REST answers 422 with
+// `{"message":"Validation Failed","errors":[{"resource":"PullRequest","code":"custom","message":"A
+// pull request already exists for <owner>:<branch>."}]}` — which `gh` writes to **stdout**, putting
+// only `gh: Validation Failed (HTTP 422)` on stderr. The body reaches the thrown Error because
+// `to_gh_error` appends stdout (joshuafolkken/kit#1029); the `already exists` match itself is
+// unchanged, because both wordings contain it and the 422 carries no machine-readable code for the
+// case (`"code":"custom"`).
+async function pr_create(title: string, body: string): Promise<string> {
+	const base = await git_command.get_default_branch()
+	const head = await git_command.branch()
+
+	forget_pr_numbers()
+
+	try {
+		return await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.pulls_api_path(),
+			body: JSON.stringify({ title, body, head, base }),
+			jq_filter: HTML_URL_FILTER,
+		})
+	} catch (error) {
+		return git_gh_helpers.handle_pr_create_error(error)
+	}
+}
+
+// **`gh pr checkout` does use GraphQL** — one `POST /graphql` to resolve the pull request, measured
+// with `GH_DEBUG=api` on the throwaway pull request (joshuafolkken/kit#1029). Everything after that
+// is git, so only the resolution had to move: `pr_head_reference` is the REST read that already
+// replaced it for this file's one caller, `sync-dependabot-pins.ts`.
+//
+// `fetch_branch` updates `refs/remotes/origin/<branch>`, which is what lets the plain `checkout`
+// resolve a branch that exists only on the remote — the tracking branch `gh` left behind, by the
+// operations `git-command.ts` already owns rather than a new wrapper. The fast-forward is the third
+// thing the CLI did and the one a fetch-and-checkout pair silently drops: a branch that is already
+// local is checked out at whatever commit the last run left it on.
+//
+// A fork's head is refused by `pr_head_reference` rather than fetched from `origin` under a name
+// that repository may use for something else.
+async function pr_checkout(pr_number: number): Promise<void> {
+	const branch_name = await git_gh_pr_read.pr_head_reference(pr_number)
+
+	await git_command.fetch_branch(branch_name)
+	await git_command.checkout(branch_name)
+	await git_command.merge_fast_forward(branch_name)
+}
+
+// A pull request's conversation comment is an **issue** comment: `POST issues/{N}/comments` is the
+// endpoint, and it answers the same `html_url` for a pull request as for an issue (measured on the
+// throwaway pull request). `git-gh-issue-write.ts` already posts to it, so this resolves the number
+// and reuses that writer rather than adding a second call site for one endpoint.
+async function pr_comment(branch_name: string, body: string): Promise<string> {
+	const pr_number = await require_pr_number(branch_name)
+
+	return await git_gh_issue_write.issue_comment(String(pr_number), body)
+}
+
+// Replaces the body of the branch's open pull request. `git -y` opens a pull request once, so a
+// body supplied on a later run — the live-execution evidence `followup` gates the merge on
+// (joshuafolkken/kit#2446) — reaches an already-open one only through this write.
+async function pr_update_body(branch_name: string, body: string): Promise<void> {
+	const pr_number = await require_pr_number(branch_name)
+
+	await git_gh_exec.exec_gh_api({
+		path: git_gh_api_path.pull_api_path(String(pr_number)),
+		method: PATCH_METHOD,
+		body: JSON.stringify({ body }),
+	})
+}
+
+async function put_merge(pr_number: number): Promise<void> {
+	await git_gh_exec.exec_gh_api({
+		path: git_gh_api_path.pull_merge_api_path(String(pr_number)),
+		method: PUT_METHOD,
+		body: JSON.stringify({ merge_method: MERGE_COMMIT_METHOD }),
+		timeout_ms: MERGE_REQUEST_TIMEOUT_MS,
+	})
+}
+
+// `undefined` is "nobody read it", kept apart from the `false` that means "the pull request is not
+// merged". Folding the two is the misread joshuafolkken/kit#925 / #950 / #973 / #1048 all refuse.
+async function read_merge_state(pr_number: number): Promise<boolean | undefined> {
+	try {
+		return git_gh_pr_rest.is_merged(await read_pull(pr_number))
+	} catch (error) {
+		// The reason goes in the line, for the same reason the poll loop's warning carries one: the
+		// failure this throws below names the *merge* request as its cause, so without this an operator
+		// is told the pull request could not be read back and never why.
+		console.warn(`Could not read the pull request back: ${String(error)}`)
+
+		return undefined
+	}
+}
+
+// The wait goes **between** attempts and never after the last one — the convention `poll.wait_between`
+// and `git-pr-checks.ts`'s own `sleep_before_next_attempt` both hold to. Without the guard a merge
+// whose read-back never succeeds delays its own failure report by a whole interval.
+async function sleep_between_read_backs(attempt: number): Promise<void> {
+	if (attempt < MERGE_READ_BACK_ATTEMPTS - 1) await poll.sleep(MERGE_READ_BACK_INTERVAL_MS)
+}
+
+// Whether the merge is actually there, asked only after the request failed.
+//
+// **The read-back is retried, because the outage that killed the merge request is the one most
+// likely to kill the read that follows it** — the same rate limit, the same dropped connection. One
+// unretried request would therefore fail hardest in exactly the case this recovery exists for. Three
+// attempts a second apart get past a dropped connection; a real outage still ends below, and a
+// re-run of `followup` recovers from that.
+//
+// **A read that failed is still not an answer.** Out of attempts it throws rather than reporting
+// `false`, carrying the merge failure as its `cause`, so no run ever concludes "the merge did not
+// happen" from a read nobody got.
+async function has_merge_landed(pr_number: number, merge_error: unknown): Promise<boolean> {
+	for (let attempt = 0; attempt < MERGE_READ_BACK_ATTEMPTS; attempt += 1) {
+		const is_merged = await read_merge_state(pr_number)
+		if (is_merged !== undefined) return is_merged
+
+		await sleep_between_read_backs(attempt)
+	}
+
+	throw new Error(MERGE_UNCONFIRMED_MESSAGE, { cause: merge_error })
+}
+
+// **The least idempotent write in this layer, made re-entrant** (joshuafolkken/kit#1077).
+//
+// The request carries a budget like everything else since joshuafolkken/kit#1065, and a merge that
+// lands server-side but overruns it used to throw: `followup` then skipped its completion
+// notification and the epic auto-close, and a re-run answered 405 on a pull request that was already
+// merged. The budget did not create that — before it the same request hung forever, with no
+// notification either and no end to the run — it only turned a silent hang into a loud failure.
+//
+// **A failed merge request is not proof the merge did not happen**, so the pull request's own state
+// settles it: merged, and this returns as if the request had succeeded, which is what lets
+// `followup` carry on to the notification and the epic close, and what makes re-running it recover
+// instead of failing on the 405. Not merged, and the original failure is rethrown unchanged.
+//
+// **The question is "is this pull request merged", not "did my request merge it"**, and that is
+// deliberate: the state the recovery has to act on is whether the branch is in, and a merge someone
+// made by hand between the failure and the read leaves `followup` with exactly the same work to
+// finish. REST offers nothing that would tell the two apart without keeping the merge commit's SHA
+// across a request that never answered.
+async function pr_merge(branch_name: string): Promise<void> {
+	const pr_number = await require_pr_number(branch_name)
+
+	try {
+		await put_merge(pr_number)
+	} catch (error) {
+		if (!(await has_merge_landed(pr_number, error))) throw error
+	}
+}
+
+const git_gh_pr = {
+	...git_gh_pr_read,
+	...git_gh_pr_snapshot,
+	pr_create,
+	pr_checkout,
+	pr_comment,
+	pr_merge,
+	pr_update_body,
+}
+
+export { git_gh_pr, MERGE_COMMIT_METHOD, MERGE_REQUEST_TIMEOUT_MS, MERGE_UNCONFIRMED_MESSAGE }

package/scripts/git/git-gh-reachability.ts

@@ -0,0 +1,56 @@
+// Whether GitHub answered at all — the question a failed read has to ask before it calls itself a
+// structural failure (joshuafolkken/kit#1663).
+//
+// **The question is now asked of the failed request itself, not of a later one**
+// (joshuafolkken/kit#1690). `probe()` used to fire one request at `rate_limit` after the reads were
+// over and the answer otherwise final; a connection that dropped for a few hundred milliseconds
+// failed a read at t=0 and answered that probe `reachable`, so the run kept the verdict the probe
+// gave it rather than the one the read had. What remains here is the classification — status to
+// retryable-or-not — which `git-gh-issue-read.ts` applies to the status the failed request carried
+// on its own error document.
+//
+// A dropped connection, a name that would not resolve, a rate limit and a 5xx are **retryable**: the
+// same request a moment later can succeed, and nothing about the repository has to change first. A
+// 404 or a 401 is not — the issue is absent or the credentials are wrong, and asking again answers
+// the same. Callers that cannot tell the two apart have to choose one meaning for both, and
+// joshuafolkken/kit#1663 measured what that costs: an unattended run reported thirteen runnable
+// issues as an unresolvable dependency graph because DNS hiccuped once.
+//
+// **It classifies by status code and not by gh's wording**, which is the same argument
+// `issue_view_json_classified` records for separating 404 from the rest: a message is prose that can
+// be reworded between releases, while the status is the protocol. The transport case is the one the
+// protocol expresses by *absence* — no status line at all — which is exactly what
+// `exec_gh_api_status` already answers `undefined` for.
+
+// **403 is deliberately not retryable.** GitHub does spell some secondary rate limits that way, but
+// it is equally how a SAML-SSO-unauthorized token, an IP allowlist and an org policy each answer —
+// all permanent, and all diagnosed correctly by the `gh auth status` advice the unusable-graph
+// report already carries. Reading one of those as a connection problem would be this Issue's own
+// misdirection pointed the other way, so the ambiguous status is left with the permanent meaning and
+// only the unambiguous ones — 429, 5xx, and no answer at all — are treated as worth asking again.
+const RATE_LIMITED_STATUS = 429
+const SERVER_ERROR_FLOOR = 500
+
+// `unreachable` is a statement about the transport, never about the caller's own request: it says
+// the probe could not get an answer out of GitHub, and deliberately not that any particular read
+// would have succeeded had it.
+type GhReachability = 'reachable' | 'unreachable'
+
+function is_retryable_status(status: number): boolean {
+	if (status >= SERVER_ERROR_FLOOR) return true
+
+	return status === RATE_LIMITED_STATUS
+}
+
+// `undefined` is the transport case rather than an unknown one: a failed `gh api` request that wrote
+// no response body has no status to report, which a request that never arrived is exactly — the same
+// meaning `exec_gh_api_status` gives it when no status line was reached.
+function classify_status(status: number | undefined): GhReachability {
+	if (status === undefined) return 'unreachable'
+
+	return is_retryable_status(status) ? 'unreachable' : 'reachable'
+}
+
+const gh_reachability = { classify_status }
+
+export { gh_reachability }

package/scripts/git/git-gh-repo.ts

@@ -0,0 +1,37 @@
+import { git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+import { git_gh_helpers } from './git-gh-helpers'
+
+// `owner/repo` for the repository the session runs in.
+//
+// Read through REST rather than `gh repo view --json nameWithOwner`: the `gh <noun> <verb>` form
+// goes through GraphQL, which a cloud session is refused outright (403), so this read answered
+// `undefined` there and every caller needing the name inherited that answer
+// (joshuafolkken/kit#1023).
+//
+// The pull-request reads no longer go through it at all: they address `repos/{owner}/{repo}` and
+// name the head filter's owner as `{owner}` too, which `gh api` expands inside a query string as
+// readily as inside a path. That keeps six branch-keyed reads from gaining a second way to fail, and
+// it is what makes `pr_get_review_comments` REST end to end (joshuafolkken/kit#1027). The remaining
+// caller is the completion notification, which puts the name in its Telegram body.
+//
+// The failure contract is unchanged: `undefined` when the read fails, for a caller that has nothing
+// better to do with the error than treat the name as unknown.
+async function repo_get_name_with_owner(): Promise<string | undefined> {
+	try {
+		const result: string = await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.repo_api_path(),
+			jq_filter: '.full_name',
+		})
+
+		return git_gh_helpers.parse_pr_state_string(result)
+	} catch {
+		return undefined
+	}
+}
+
+const git_gh_repo = {
+	repo_get_name_with_owner,
+}
+
+export { git_gh_repo }

package/scripts/git/git-gh-rest-state.ts

@@ -0,0 +1,14 @@
+// The casing rule between REST and `gh --json`, and the one spelling of a merged pull request.
+//
+// REST answers `open` / `closed` in lower case and reports a merge as a *separate* field, while `gh`
+// answered `OPEN` / `CLOSED` / `MERGED` and every reader downstream compares against that spelling.
+// Two endpoints have to recompose the third value from different fields — the issue endpoint from
+// `pull_request.merged_at`, the pulls endpoint from `merged` — so the rule they share is named here
+// rather than in either of them (joshuafolkken/kit#1027).
+const MERGED_STATE = 'MERGED'
+
+function to_gh_state(state: string | undefined): string | undefined {
+	return state?.toUpperCase()
+}
+
+export { MERGED_STATE, to_gh_state }

package/scripts/git/git-issue.ts

@@ -0,0 +1,168 @@
+import { lane_paths } from '#scripts/lane/lane-paths'
+import { SEPARATOR_LINE } from './constants'
+import { git_gh_issue_read } from './git-gh-issue-read'
+import { git_prompt } from './git-prompt'
+
+interface IssueInfo {
+	title: string
+	number: string
+	branch_name: string
+	commit_message: string
+}
+
+const ISSUE_NUMBER_PATTERN = /#(\d+)$/u
+
+function extract_issue_number(input: string): string {
+	const match = ISSUE_NUMBER_PATTERN.exec(input)
+
+	if (match === null) {
+		throw new Error('Invalid format: Issue number not found (e.g., "title #52")')
+	}
+
+	return match[1] ?? ''
+}
+
+function extract_issue_title(input: string): string {
+	const title = input.replace(/#\d+$/u, '').trim()
+
+	if (title.length === 0) {
+		throw new Error('Invalid format: Issue title is required')
+	}
+
+	return title
+}
+
+function normalize_title_for_branch(title: string): string {
+	const replaced = title
+		.toLowerCase()
+		.normalize('NFKD')
+		.replaceAll(/[^a-z0-9]+/gu, '-')
+		.replaceAll(/-+/gu, '-')
+		.replaceAll(/(^-)|(-$)/gu, '')
+
+	return replaced.length === 0 ? 'update' : replaced
+}
+
+function create_branch_name(issue_number: string, title: string): string {
+	return `${issue_number}-${normalize_title_for_branch(title)}`
+}
+
+function parse_issue_input(input: string): IssueInfo {
+	const trimmed_input = input.trim()
+	const issue_number = extract_issue_number(trimmed_input)
+	const title = extract_issue_title(trimmed_input)
+	const branch_name = create_branch_name(issue_number, title)
+	const commit_message = `${title} #${issue_number}`
+
+	return {
+		title,
+		number: issue_number,
+		branch_name,
+		commit_message,
+	}
+}
+
+const BRANCH_NUMBER_PATTERN = /^(\d+)-(.+)$/u
+
+// A lane's branch is `<N>-lane` (joshuafolkken/kit#1490), so its second segment is the fixed word
+// `lane` rather than a slug of the title — de-slugging it produced commit messages like `lane #1465`
+// on joshuafolkken/kit#1586. The shape is recognized through `lane_paths.lane_branch` rather than a
+// second copy of the suffix, so the two ends cannot drift apart (joshuafolkken/kit#1590).
+function is_lane_branch(branch_name: string, issue_number: string): boolean {
+	return branch_name === lane_paths.lane_branch(issue_number)
+}
+
+const EXAMPLE_ISSUE_NUMBER = '42'
+
+function argument_hint(issue_number: string): string {
+	return `Provide an issue argument like "title #${issue_number}".`
+}
+
+// Never falls back to the branch's own word: `lane` is not a title, and a commit message cannot be
+// rewritten once it is on the default branch. Failing loudly leaves the caller one argument away.
+async function lane_issue_title(branch_name: string, issue_number: string): Promise<string> {
+	const title = await git_gh_issue_read.issue_get_title(issue_number)
+
+	if (title === undefined) {
+		throw new Error(
+			`Cannot read the title of issue #${issue_number} for lane branch "${branch_name}". ${argument_hint(issue_number)}`,
+		)
+	}
+
+	return title
+}
+
+async function derive_issue_input_from_branch(branch_name: string): Promise<string> {
+	const match = BRANCH_NUMBER_PATTERN.exec(branch_name)
+
+	if (match === null) {
+		throw new Error(
+			`Cannot derive issue info from branch "${branch_name}" in non-interactive mode. ${argument_hint(EXAMPLE_ISSUE_NUMBER)}`,
+		)
+	}
+
+	const [, number = '', slug = ''] = match
+	const title = is_lane_branch(branch_name, number)
+		? await lane_issue_title(branch_name, number)
+		: slug.replaceAll('-', ' ').trim()
+
+	return `${title} #${number}`
+}
+
+async function derive_from_branch(branch_name: string): Promise<IssueInfo> {
+	const parsed = parse_issue_input(await derive_issue_input_from_branch(branch_name))
+
+	// Pin to the actual branch so a non-round-tripping slug never triggers a branch switch.
+	return { ...parsed, branch_name }
+}
+
+function display_issue_info(issue_info: IssueInfo): void {
+	console.info('')
+	console.info('📋 Issue Information')
+	console.info(SEPARATOR_LINE)
+	console.info(`  Issue Title: ${issue_info.title}`)
+	console.info(`  Issue Number: ${issue_info.number}`)
+	console.info(`  Branch Name: ${issue_info.branch_name}`)
+	console.info(`  Commit Message: ${issue_info.commit_message}`)
+	console.info(SEPARATOR_LINE)
+}
+
+async function get_and_display(cli_input?: string): Promise<IssueInfo> {
+	const input = cli_input ?? (await git_prompt.get_issue_info())
+	const issue_info = parse_issue_input(input)
+
+	display_issue_info(issue_info)
+
+	return issue_info
+}
+
+interface ResolveIssueInput {
+	cli_input: string | undefined
+	current_branch: string
+	is_non_interactive: boolean
+}
+
+// In non-interactive mode (e.g. `josh pr` / `-y` with no issue arg, or no TTY) the issue
+// info is derived from the current branch instead of prompting, so headless runs never throw.
+async function resolve_and_display(input: ResolveIssueInput): Promise<IssueInfo> {
+	if (input.cli_input !== undefined) return await get_and_display(input.cli_input)
+
+	if (input.is_non_interactive) {
+		const issue_info = await derive_from_branch(input.current_branch)
+
+		display_issue_info(issue_info)
+
+		return issue_info
+	}
+
+	return await get_and_display()
+}
+
+const git_issue = {
+	get_and_display,
+	resolve_and_display,
+	derive_from_branch,
+}
+
+export type { IssueInfo }
+export { git_issue }

package/scripts/git/git-location-environment.ts

@@ -0,0 +1,62 @@
+// The `GIT_*` variables that decide **which** repository, work tree, index or object store a `git`
+// command acts on — and every one of them beats `cwd` outright.
+//
+// git exports them to every hook it runs, so a child process spawned from inside `pre-commit` or
+// `pre-push` inherits a pointer at the repository the hook is firing in. A helper that passes
+// `{ cwd: fixture_directory }` and nothing else therefore writes into the **real** checkout, with no
+// error anywhere: joshuafolkken/kit#1515 found it in `propagate-git`'s probes, and
+// joshuafolkken/kit#1530 found the same shape in `lane-change-base.test.ts`, where it committed a
+// test fixture's own commits onto a lane's live branch during the pre-push gate.
+//
+// The list is single-sourced here because it now has three consumers that must not drift apart: the
+// probes that clear it, the fixture that clears it, and the unit-suite guard that refuses a write
+// while any of it is set (`scripts/test/test-repository-guard.ts`).
+//
+// **Only the variables that redirect where git writes are listed.** `GIT_PREFIX`, `GIT_EDITOR` and
+// the `GIT_CONFIG_*` family are exported to hooks too and are deliberately absent: clearing them
+// buys nothing, and the guard refuses on the presence of any name on this list, so a name that does
+// not redirect a write would only manufacture false positives.
+const GIT_LOCATION_VARIABLES: ReadonlyArray<string> = [
+	'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+	'GIT_COMMON_DIR',
+	'GIT_DIR',
+	'GIT_INDEX_FILE',
+	'GIT_NAMESPACE',
+	'GIT_OBJECT_DIRECTORY',
+	'GIT_WORK_TREE',
+]
+
+// The `env` overlay that makes `cwd` mean what it says. Spread into an execa call alongside
+// `extendEnv: true`, each `undefined` removes that name from the child's environment rather than
+// setting it to the string `"undefined"`.
+function location_free_environment(): Record<string, undefined> {
+	return Object.fromEntries(GIT_LOCATION_VARIABLES.map((name) => [name, undefined]))
+}
+
+// `Reflect.deleteProperty` rather than `delete`: assigning `undefined` to a `process.env` key stores
+// the string `"undefined"`, which git reads as a request rather than as an absence.
+function forget(name: string): void {
+	Reflect.deleteProperty(process.env, name)
+}
+
+function restore_one(name: string, value: string | undefined): void {
+	if (value === undefined) forget(name)
+	else process.env[name] = value
+}
+
+// The same clearing applied to **this** process, answering with the restore. A child's environment
+// is not the whole exposure: a helper that spawns `git` with no `env` of its own inherits
+// `process.env`, so a test file driving such a helper has to clear the variables where they are.
+function clear_git_location_variables(): () => void {
+	const previous = GIT_LOCATION_VARIABLES.map((name) => [name, process.env[name]] as const)
+
+	for (const [name] of previous) forget(name)
+
+	return (): void => {
+		for (const [name, value] of previous) restore_one(name, value)
+	}
+}
+
+const git_location_environment = { clear_git_location_variables, location_free_environment }
+
+export { GIT_LOCATION_VARIABLES, git_location_environment }

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

@@ -0,0 +1,28 @@
+// How origin is asked whether it carries a branch — the one place that says it
+// (joshuafolkken/kit#1732).
+//
+// **The pattern is the full ref path, because `ls-remote` matches a pattern against the *tail* of a
+// ref at a slash boundary** (joshuafolkken/kit#1709). A bare name therefore answers for any branch
+// ending in it: `1641-lane` matches `refs/heads/wip/1641-lane`, and `release/v1.2.0` matches
+// `refs/heads/foo/release/v1.2.0`. **`--heads` does not close it** — that limits which refs are
+// considered, not where inside one the pattern may match. Anchored at `refs/heads/`, only the exact
+// branch is left, since no shorter tail of `refs/heads/wip/1641-lane` starts with `refs/heads/`.
+// Callers pass a bare branch name, so the prefix goes on once even for a name that already carries a
+// slash.
+//
+// **It is the arguments that are shared, not the spawn.** `git_worktree.ls_remote_branch` runs this
+// asynchronously against the process's own cwd with no timeout, while
+// `propagate_git.has_remote_branch` runs it synchronously against a consumer's path under a remote
+// budget — three differences that belong to those callers. What was duplicated is the knowledge
+// above, and joshuafolkken/kit#1709 fixed it in only one of the two places, which is the defect
+// joshuafolkken/kit#1732 was filed for. Kept in one module, the next such fix reaches both.
+const LS_REMOTE_COMMAND = 'ls-remote'
+const HEADS_FLAG = '--heads'
+const ORIGIN_REMOTE = 'origin'
+const HEADS_REF_PREFIX = 'refs/heads/'
+
+function ls_remote_branch_arguments(branch_name: string): Array<string> {
+	return [LS_REMOTE_COMMAND, HEADS_FLAG, ORIGIN_REMOTE, `${HEADS_REF_PREFIX}${branch_name}`]
+}
+
+export { ls_remote_branch_arguments }