@joshuafolkken/kit 1.872.0

package/scripts/git/git-pr-managed-config.ts

@@ -0,0 +1,69 @@
+import { managed_config_scope, type ManagedHit } from '#scripts/sync/managed-config-scope'
+import { changed_paths } from './changed-paths'
+import { git_command } from './git-command'
+
+// **The tracked diff against the merge base — untracked files excluded.**
+// `changed_paths.read_changed_paths(false)` appends the untracked files as well, and those are not in
+// the pull request: a stray untracked file under a distributed path would put a line in the report
+// asserting that *this pull request* changes a distributed file, which would be false.
+//
+// **What it compares is the merge base against the work tree, not against `HEAD`**, so an uncommitted
+// edit to a tracked file still counts. That is deliberate rather than overlooked: `followup` runs
+// straight after `josh git` has committed and pushed, so the two agree in the case this report is
+// for, and where they disagree the error falls on the side of naming a path that is about to be
+// committed rather than omitting one.
+//
+// The line splitting stays the shared helper's, so this answers from the same definition of a changed
+// path as the review level and the eval scope.
+async function read_branch_paths(): Promise<Array<string>> {
+	return changed_paths.to_paths(await git_command.diff_main_names())
+}
+
+const REPORT_HEADING =
+	'This pull request changes files that `josh sync` distributes to every consumer project.'
+const REPORT_PATHS_HEADING = 'Distributed paths in this diff:'
+
+function build_report(hits: ReadonlyArray<ManagedHit>): Array<string> {
+	return [REPORT_HEADING, REPORT_PATHS_HEADING, managed_config_scope.format_hits(hits)]
+}
+
+// **This reports; it does not stop the merge** (joshuafolkken/kit#1592). joshuafolkken/kit#1578 made
+// it a confirmation gate that exited non-zero ahead of the CI wait, and in kit the condition it tests
+// is nearly always true: kit is the distribution source, so every change to `CLAUDE.md`, to
+// `prompts/`, to `.claude/skills/` or to the distributed part of `docs/` is by definition a change to
+// a distributed path. Measured on `epicrun #1413`, **two of three children stopped here** — and in
+// both the distributed file was what the Issue's own acceptance criteria had ordered changed. The
+// gate was not catching an unintended edit; it was stopping the work.
+//
+// **There is deliberately no branch on which repository this is.** The alternative — stop in a
+// consumer, where editing a distributed file really is the mistake `CLAUDE.md` → "Route
+// distributed-doc / config changes upstream to kit" names, and stay quiet in kit — was weighed and
+// rejected on joshuafolkken/kit#1592: it needs a distribution-source test this package does not have,
+// no case is recorded of the gate saving a consumer's work, and the report below reaches a consumer's
+// reader just as well. `managed_config_scope` matches both ends of every mapping and distinguishes no
+// repository, and that property is kept rather than worked around.
+//
+// **What is left is the signal without the stop.** The claimed paths and the list that claimed each
+// one go into the completion notification and into the completion report on the Issue, so a
+// distributed change is still impossible to miss after the fact.
+async function handle_managed_config_changes(input: {
+	should_merge: boolean
+}): Promise<Array<string>> {
+	// **Nothing to report when nothing merges.** `--no-merge` ends with the pull request open for a
+	// person to look at, and the distribution has not happened yet; the report belongs to the run that
+	// actually lands the change on the default branch.
+	if (!input.should_merge) return []
+
+	const hits = managed_config_scope.find_managed_paths(await read_branch_paths())
+
+	if (hits.length === 0) return []
+
+	return build_report(hits)
+}
+
+const git_pr_managed_config = {
+	handle_managed_config_changes,
+	build_report,
+}
+
+export { git_pr_managed_config }

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

@@ -0,0 +1,37 @@
+// What `pnpm josh git` prints once the pull request is open. It no longer claims anything about the
+// checks: this command returns before they have run (joshuafolkken/kit#1232), and the old
+// "All checks passed successfully." was printed on the strength of a watch whose verdict decided
+// nothing. Naming `pnpm josh followup` here is the whole replacement — it is what waits, and what
+// merges.
+function display_pr_opened_message(): void {
+	console.info('')
+	console.info('✅ Pull request opened.')
+	console.info('')
+	console.info('`pnpm josh followup` waits for the checks and merges.')
+}
+
+function display_pr_url(pr_url: string): void {
+	console.info('')
+	console.info(`🔗 PR: ${pr_url}`)
+}
+
+function display_merged_pr_message(): void {
+	console.info('')
+	console.info('ℹ️  Existing PR is already merged. Creating a new PR...')
+	console.info('')
+}
+
+function display_pr_exists_message(): void {
+	console.info('')
+	console.info('ℹ️  Pull request already exists.')
+	console.info('')
+}
+
+const git_pr_messages = {
+	display_pr_opened_message,
+	display_merged_pr_message,
+	display_pr_exists_message,
+	display_pr_url,
+}
+
+export { git_pr_messages }

package/scripts/git/git-pr.ts

@@ -0,0 +1,181 @@
+import { animation_helpers, type AnimationOptions } from './animation-helpers'
+import { git_gh_command } from './git-gh-command'
+import type { IssueInfo } from './git-issue'
+import { git_pr_error } from './git-pr-error'
+import { git_pr_messages } from './git-pr-messages'
+import { pr_info_schema } from './schemas'
+
+// **Answers the new pull request's URL, and `undefined` when one already existed.** `pr_create`
+// filters its REST response to `.html_url`, so the address is in hand the moment the call returns —
+// which matters now that nothing waits before reporting it (joshuafolkken/kit#1232). `pr_get_url`
+// resolves the branch through the `?head=…` listing, and that listing is eventually consistent: read
+// in the same instant the pull request was created it can answer nothing, and `pr_get_url` folds
+// "not there yet" and "the read failed" into the same `undefined`. The five-second sleep used to
+// cover that gap incidentally.
+async function create_pr(title: string, body: string): Promise<string | undefined> {
+	const config: AnimationOptions<string> = {
+		icon_selector: () => '✅',
+		error_message: 'Failed to create PR',
+		result_formatter: () => 'PR created.',
+	}
+
+	try {
+		return await animation_helpers.execute_with_animation(
+			'Creating pull request...',
+			async () => await git_gh_command.pr_create(title, body),
+			config,
+		)
+	} catch (error) {
+		if (git_pr_error.is_pr_already_exists_error(error)) {
+			git_pr_messages.display_pr_exists_message()
+
+			return undefined
+		}
+
+		throw error
+	}
+}
+
+async function display_pr_url_if_available(branch_name: string): Promise<void> {
+	const pr_url = await git_gh_command.pr_get_url(branch_name)
+
+	if (pr_url !== undefined) {
+		git_pr_messages.display_pr_url(pr_url)
+	}
+}
+
+// **This command stops at "the pull request is open"; it does not wait for the checks**
+// (joshuafolkken/kit#1232). It used to sleep five seconds and then watch the rollup on a two-minute
+// budget — measured at 119.8 seconds of one 1555-second run, 7.7% of it — and the answer decided
+// nothing: only `timed_out` was read, and only to pick which message to print. What actually blocks
+// a merge is `pnpm josh followup`, whose `wait_for_pr_success` asks a stricter question (CLEAN merge
+// state, every required check green, no standing change request) and starts that wait from scratch
+// the moment this command returns. So the wait here was the same answer, paid for twice.
+//
+// **The conflict read went with it, and its replacement is not here.** `git-conflict.ts` read
+// `mergeStateStatus` right after the watch reported the checks settled, where `BLOCKED` genuinely
+// meant something. Called at *this* point it would fire on every healthy pull request instead:
+// GitHub reports `BLOCKED` as soon as a required check is queued. The conflict is caught in
+// `git-pr-checks-eval.ts` now, where `DIRTY` ends the wait on its first poll — about ten seconds,
+// against the two minutes this watch took to reach the same conclusion.
+async function report_open_pr(branch_name: string, created_url?: string): Promise<void> {
+	git_pr_messages.display_pr_opened_message()
+
+	if (created_url !== undefined && created_url.length > 0) {
+		git_pr_messages.display_pr_url(created_url)
+
+		return
+	}
+
+	await display_pr_url_if_available(branch_name)
+}
+
+const PR_STATE_MERGED = 'MERGED'
+
+async function create_and_report(title: string, body: string, branch_name: string): Promise<void> {
+	const created_url = await create_pr(title, body)
+
+	await report_open_pr(branch_name, created_url)
+}
+
+function parse_pr_state(pr_info_json: string): string | undefined {
+	try {
+		const result = pr_info_schema.safeParse(JSON.parse(pr_info_json))
+
+		return result.success ? result.data.state : undefined
+	} catch {
+		return undefined
+	}
+}
+
+async function get_pr_state_safe(branch_name: string): Promise<string | undefined> {
+	try {
+		const pr_info_json = await git_gh_command.pr_view(branch_name)
+
+		if (pr_info_json.length === 0) {
+			return undefined
+		}
+
+		return parse_pr_state(pr_info_json)
+	} catch {
+		return undefined
+	}
+}
+
+function is_pr_state_merged(pr_state: string | undefined): boolean {
+	return pr_state === PR_STATE_MERGED
+}
+
+// A body the caller supplied is written onto the pull request that is already open, rather than
+// dropped with the create that did not happen (joshuafolkken/kit#2446): a rerun carrying the
+// live-execution evidence is how a merge `followup` refused for lacking it is recovered.
+async function report_existing_pr(
+	body: string,
+	branch_name: string,
+	should_replace_body: boolean,
+): Promise<void> {
+	if (should_replace_body) await git_gh_command.pr_update_body(branch_name, body)
+
+	await report_open_pr(branch_name)
+}
+
+async function handle_existing_pr(
+	title: string,
+	body: string,
+	branch_name: string,
+	should_replace_body: boolean,
+): Promise<void> {
+	const pr_state_result = await get_pr_state_safe(branch_name)
+
+	if (is_pr_state_merged(pr_state_result)) {
+		git_pr_messages.display_merged_pr_message()
+		await create_and_report(title, body, branch_name)
+
+		return
+	}
+
+	await report_existing_pr(body, branch_name, should_replace_body)
+}
+
+async function create(
+	title: string,
+	body: string,
+	branch_name: string,
+	should_replace_body = false,
+): Promise<void> {
+	const has_pr = await git_gh_command.pr_exists(branch_name)
+
+	if (!has_pr) {
+		await create_and_report(title, body, branch_name)
+
+		return
+	}
+
+	await handle_existing_pr(title, body, branch_name, should_replace_body)
+}
+
+function build_title(issue_info: IssueInfo): string {
+	return `${issue_info.title} #${issue_info.number}`
+}
+
+function build_body(issue_info: IssueInfo, extra_body?: string): string {
+	const closes = `closes #${issue_info.number}`
+
+	if (extra_body === undefined) return closes
+
+	return `${closes}\n\n${extra_body}`
+}
+
+async function create_with_issue_info(issue_info: IssueInfo, extra_body?: string): Promise<void> {
+	const title = build_title(issue_info)
+	const body = build_body(issue_info, extra_body)
+
+	await create(title, body, issue_info.branch_name, extra_body !== undefined)
+}
+
+const git_pr = {
+	create,
+	create_with_issue_info,
+}
+
+export { git_pr }

package/scripts/git/git-prompt-display.ts

@@ -0,0 +1,22 @@
+import { SEPARATOR_LINE } from './constants'
+
+function display_start_separator(): void {
+	console.info('')
+	console.info(SEPARATOR_LINE)
+}
+
+function display_end_separator(): void {
+	console.info(SEPARATOR_LINE)
+}
+
+function display_invalid_answer_message(): void {
+	console.info('💡 Reply y / n.')
+}
+
+const git_prompt_display = {
+	display_start_separator,
+	display_end_separator,
+	display_invalid_answer_message,
+}
+
+export { git_prompt_display }

package/scripts/git/git-prompt.ts

@@ -0,0 +1,207 @@
+import { stdin as input, stdout as output } from 'node:process'
+import { createInterface, type Interface } from 'node:readline/promises'
+import { git_prompt_display } from './git-prompt-display'
+
+const OPERATION_CANCELLED_MESSAGE = '💡 Operation cancelled.'
+
+const PROMPT_MESSAGES = {
+	unstaged_files: '💬 Unstaged files found. Continue anyway? (y/n): ',
+	package_json_not_staged: '💬 package.json is not staged. Continue anyway? (y/n): ',
+	version_not_updated: '💬 package.json version is not updated. Continue anyway? (y/n): ',
+	commit: '💬 Commit staged changes now? (y/n): ',
+	push: '💬 Push changes to remote? (y/n): ',
+	pr: '💬 Create pull request? (y/n): ',
+} as const
+
+type PromptCallback<T> = (prompt: Interface) => Promise<T>
+
+interface AskOptions {
+	show_separators: boolean
+	is_first_call: boolean
+}
+
+function is_valid_yes_no_answer(answer: string): boolean {
+	return answer === 'y' || answer === 'n'
+}
+
+async function ask_yes_no_unified(
+	prompt: Interface,
+	question: string,
+	options: AskOptions,
+): Promise<boolean> {
+	if (options.show_separators && options.is_first_call) {
+		git_prompt_display.display_start_separator()
+	}
+
+	const raw_answer: unknown = await prompt.question(question)
+	// eslint-disable-next-line unicorn/no-useless-coercion -- raw_answer is unknown, String() coercion is required
+	const answer = String(raw_answer).trim().toLowerCase()
+
+	if (!is_valid_yes_no_answer(answer)) {
+		git_prompt_display.display_invalid_answer_message()
+
+		return await ask_yes_no_unified(prompt, question, { ...options, is_first_call: false })
+	}
+
+	if (options.show_separators) {
+		git_prompt_display.display_end_separator()
+	}
+
+	return answer === 'y'
+}
+
+async function ask_yes_no(prompt: Interface, question: string): Promise<boolean> {
+	return await ask_yes_no_unified(prompt, question, { show_separators: true, is_first_call: true })
+}
+
+async function ask_yes_no_simple(prompt: Interface, question: string): Promise<boolean> {
+	return await ask_yes_no_unified(prompt, question, { show_separators: false, is_first_call: true })
+}
+
+function create_prompt(): Interface | undefined {
+	return process.stdin.isTTY ? createInterface({ input, output }) : undefined
+}
+
+function handle_prompt_fallback<T>(fallback_value?: T): T {
+	if (fallback_value !== undefined) {
+		return fallback_value
+	}
+
+	throw new Error('TTY not available')
+}
+
+async function with_prompt<T>(callback: PromptCallback<T>, fallback_value?: T): Promise<T> {
+	const prompt = create_prompt()
+
+	if (prompt === undefined) {
+		return handle_prompt_fallback(fallback_value)
+	}
+
+	try {
+		// eslint-disable-next-line promise/prefer-await-to-callbacks
+		return await callback(prompt)
+	} finally {
+		prompt.close()
+	}
+}
+
+async function confirm_with_exit_on_cancel(should_continue: () => Promise<boolean>): Promise<void> {
+	const is_confirmed = await should_continue()
+
+	if (is_confirmed) {
+		return
+	}
+
+	console.info(OPERATION_CANCELLED_MESSAGE)
+	console.info('')
+	process.exit(1)
+}
+
+function create_confirm_function(message: string): () => Promise<boolean> {
+	return async (): Promise<boolean> => {
+		return await with_prompt(async (prompt) => await ask_yes_no(prompt, message), false)
+	}
+}
+
+async function confirm_continue(): Promise<boolean> {
+	return await create_confirm_function(PROMPT_MESSAGES.unstaged_files)()
+}
+
+async function confirm_without_package_json(): Promise<boolean> {
+	return await create_confirm_function(PROMPT_MESSAGES.package_json_not_staged)()
+}
+
+async function confirm_unstaged_files(): Promise<void> {
+	await confirm_with_exit_on_cancel(confirm_continue)
+}
+
+async function confirm_missing_package_json(): Promise<void> {
+	await confirm_with_exit_on_cancel(confirm_without_package_json)
+}
+
+async function confirm_version_not_updated(): Promise<boolean> {
+	return await create_confirm_function(PROMPT_MESSAGES.version_not_updated)()
+}
+
+async function confirm_without_version_update(): Promise<void> {
+	await confirm_with_exit_on_cancel(confirm_version_not_updated)
+}
+
+async function confirm_commit(): Promise<boolean> {
+	return await create_confirm_function(PROMPT_MESSAGES.commit)()
+}
+
+async function confirm_push(): Promise<boolean> {
+	return await create_confirm_function(PROMPT_MESSAGES.push)()
+}
+
+async function confirm_pr(): Promise<boolean> {
+	return await create_confirm_function(PROMPT_MESSAGES.pr)()
+}
+
+async function ask_issue_info(prompt: Interface, question: string): Promise<string> {
+	git_prompt_display.display_start_separator()
+	const raw_answer: unknown = await prompt.question(question)
+	// eslint-disable-next-line unicorn/no-useless-coercion -- raw_answer is unknown, String() coercion is required
+	const answer = String(raw_answer)
+
+	git_prompt_display.display_end_separator()
+
+	return answer.trim()
+}
+
+async function get_issue_info(): Promise<string> {
+	return await with_prompt(async (prompt) => {
+		const result: string = await ask_issue_info(
+			prompt,
+			'💬 Enter issue title and number (e.g., "title #52"): ',
+		)
+
+		return result
+	})
+}
+
+interface WorkflowConfirmations {
+	commit: boolean
+	push: boolean
+	pr: boolean
+}
+
+async function confirm_workflow_steps(): Promise<WorkflowConfirmations> {
+	const fallback: WorkflowConfirmations = { commit: false, push: false, pr: false }
+
+	return await with_prompt(async (prompt) => {
+		git_prompt_display.display_start_separator()
+		console.info('💬 Confirm workflow steps:')
+		console.info('')
+
+		const should_commit = await ask_yes_no_simple(prompt, PROMPT_MESSAGES.commit)
+		const should_push = await ask_yes_no_simple(prompt, PROMPT_MESSAGES.push)
+		const should_create_pr = await ask_yes_no_simple(prompt, PROMPT_MESSAGES.pr)
+
+		git_prompt_display.display_end_separator()
+
+		return {
+			commit: should_commit,
+			push: should_push,
+			pr: should_create_pr,
+		}
+	}, fallback)
+}
+
+const git_prompt = {
+	confirm_continue,
+	confirm_unstaged_files,
+	confirm_without_package_json,
+	confirm_missing_package_json,
+	confirm_version_not_updated,
+	confirm_without_version_update,
+	confirm_commit,
+	confirm_push,
+	confirm_pr,
+	get_issue_info,
+	confirm_workflow_steps,
+}
+
+export type { WorkflowConfirmations }
+export { git_prompt, ask_yes_no, ask_yes_no_simple }

package/scripts/git/git-push-transport.ts

@@ -0,0 +1,173 @@
+import { execa } from 'execa'
+import { git_utilities } from './constants'
+import { create_spawn_error, get_exit_code, has_timed_out } from './git-execa-error'
+
+const MS_PER_SECOND = 1000
+
+// The budget for one `git push`, and the reason a push can no longer wait without end
+// (joshuafolkken/kit#1251). Measured on PR #1244: the commit itself took 0.6 seconds and the push
+// then sat silent for 8 minutes 13 seconds before it was found by hand and killed — about 9 minutes
+// 50 seconds of a 72-minute run, with no way while waiting to tell a stalled push from a slow one.
+// `execa` has always accepted a `timeout`; the push path never passed one, which left it the single
+// unbounded network call in this directory beside `GH_REQUEST_TIMEOUT_MS`.
+//
+// **It sits at that same layer, and is deliberately larger.** That budget covers one REST request;
+// a push transfers objects, so this number is read off what a healthy push actually costs here — 22
+// seconds on the manual re-run that finally succeeded, 33 seconds on PR #1247. 120 is roughly four
+// times the slower of the two, which leaves room for a first push of a large branch while staying
+// far under the 6 minutes 45 seconds the hang had already reached when it was noticed.
+//
+// **It bounds one push, not one command.** A push killed on the budget is retried exactly once, and
+// `git_command.push` may then fall back to a `--set-upstream` push that is itself bounded and
+// retried — so a `josh git` that hits every one of those waits takes longer than two budgets.
+//
+// **Time spent at a credential prompt counts against it.** With `stdio: 'inherit'` an encrypted key
+// with no agent behind it prompts on the inherited terminal, and the budget does not know the
+// difference between waiting on a remote and waiting on a person. Two minutes is a generous window
+// for typing a passphrase you were just asked for, and the failure names the command to re-run.
+const PUSH_TIMEOUT_SECONDS = 120
+const PUSH_TIMEOUT_MS = PUSH_TIMEOUT_SECONDS * MS_PER_SECOND
+const PUSH_TIMEOUT_LABEL = `${String(PUSH_TIMEOUT_SECONDS)}s`
+
+// What a push killed on the budget is labelled with. "Nobody ever got an answer" and "the remote
+// said no" are different diagnoses, and only the first one is worth retrying.
+const PUSH_TIMEOUT_MESSAGE = 'git push timed out'
+
+// A timeout has no exit code — the process was killed rather than allowed to exit — so `cause` says
+// so in the slot every other git failure puts a number in. `is_upstream_not_set_error` compares
+// against '128', which this can never equal, so a timed-out bare push is never mistaken for a
+// missing upstream and retried as `--set-upstream`.
+const PUSH_TIMEOUT_EXIT_CODE = 'timeout'
+
+// SSH's own liveness probe: three unanswered checks 15 seconds apart, so a connection that dies
+// mid-transfer is noticed in about 45 seconds instead of waiting on the TCP default. The budget
+// above bounds the damage either way; this is what makes the common case fail in seconds rather
+// than sit out the whole budget.
+const SSH_KEEPALIVE_OPTIONS = '-o ServerAliveInterval=15 -o ServerAliveCountMax=3'
+const SSH_COMMAND_VARIABLE = 'GIT_SSH_COMMAND'
+const SSH_LEGACY_VARIABLE = 'GIT_SSH'
+const KEEPALIVE_SSH_COMMAND = `ssh ${SSH_KEEPALIVE_OPTIONS}`
+const SSH_COMMAND_CONFIG_KEY = 'core.sshCommand'
+const PUSH_SUBCOMMAND = 'push'
+
+// Whatever already decides how ssh is invoked, or an empty string when nothing does. git reads three
+// sources in this order — `GIT_SSH_COMMAND`, `core.sshCommand`, then the legacy `GIT_SSH` — and the
+// last one has to be asked as well precisely because it loses: setting `GIT_SSH_COMMAND` on top of a
+// `GIT_SSH=plink.exe` outranks it, so the push would run an ssh binary the user did not choose.
+function to_environment_value(name: string): string {
+	return process.env[name]?.trim() ?? ''
+}
+
+function to_configured_ssh_command(): string {
+	const from_command = to_environment_value(SSH_COMMAND_VARIABLE)
+
+	return from_command === '' ? to_environment_value(SSH_LEGACY_VARIABLE) : from_command
+}
+
+// Whether any of those three sources answered. **A hit means hands off entirely.**
+//
+// Appending the options to a command someone else chose is not safe, because they are OpenSSH's:
+// `plink` and `TortoiseGitPlink` are supported ssh commands on the platform `get_git_command_for_spawn`
+// goes out of its way to handle, and a wrapper script with a fixed argument list is common on any
+// platform — each of them exits on a usage error rather than pushing. Setting the variable while
+// `core.sshCommand` is configured is the same mistake from the other side: the environment wins, so
+// a per-repository key would be silently replaced by a plain `ssh`.
+//
+// What those users lose is the keepalive, not the fix: the budget above still bounds their push, and
+// `ServerAliveInterval` belongs in their own ssh config where it applies to every tool they run.
+async function has_configured_ssh_command(): Promise<boolean> {
+	if (to_configured_ssh_command() !== '') return true
+
+	try {
+		const git_command_bin = 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_command_bin, ['config', '--get', SSH_COMMAND_CONFIG_KEY]) // NOSONAR
+
+		return stdout.trim() !== ''
+	} catch {
+		// `git config --get` exits 1 when the key is unset, which is the answer rather than a failure.
+		return false
+	}
+}
+
+interface PushOptions {
+	stdio: 'inherit'
+	timeout: number
+	env: Record<string, string>
+}
+
+async function to_push_options(): Promise<PushOptions> {
+	const should_keep_alive = !(await has_configured_ssh_command())
+
+	return {
+		stdio: 'inherit',
+		timeout: PUSH_TIMEOUT_MS,
+		env: should_keep_alive ? { [SSH_COMMAND_VARIABLE]: KEEPALIVE_SSH_COMMAND } : {},
+	}
+}
+
+// One attempt. `true` means the budget killed it — the only failure worth trying again; every other
+// failure is git's own answer and is thrown here, so the caller below never sees it.
+async function did_push_time_out(arguments_list: Array<string>): Promise<boolean> {
+	const git_command_bin = git_utilities.get_git_command_for_spawn()
+	const options = await to_push_options()
+
+	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, [PUSH_SUBCOMMAND, ...arguments_list], options) // NOSONAR
+
+		return false
+	} catch (error) {
+		if (has_timed_out(error)) return true
+
+		throw create_spawn_error(PUSH_SUBCOMMAND, get_exit_code(error))
+	}
+}
+
+function to_manual_command(arguments_list: Array<string>): string {
+	return ['git', PUSH_SUBCOMMAND, ...arguments_list].join(' ')
+}
+
+function to_retry_notice(arguments_list: Array<string>): string {
+	return `${PUSH_TIMEOUT_MESSAGE} after ${PUSH_TIMEOUT_LABEL} — retrying once: ${to_manual_command(arguments_list)}`
+}
+
+// Both halves of the report matter. The count says the wait was bounded twice rather than once, and
+// the command is what makes the failure actionable without reconstructing the arguments — the
+// `--set-upstream` form in particular is not what a person would type from memory.
+function create_timeout_error(arguments_list: Array<string>): Error {
+	const message = `${PUSH_TIMEOUT_MESSAGE} twice (${PUSH_TIMEOUT_LABEL} each). Re-run it by hand: ${to_manual_command(arguments_list)}`
+
+	return new Error(message, { cause: { exit_code: PUSH_TIMEOUT_EXIT_CODE } })
+}
+
+// One push, bounded and retried once — and **only** on a timeout. A push the remote rejected (a
+// stale branch, a blocked hook, no upstream) answers the same way every time, so retrying it would
+// buy a second wait to reach an identical failure; a hang is the one outcome a second attempt has
+// been observed to clear, which is what the manual re-run on PR #1244 did in 22 seconds.
+async function push(arguments_list: Array<string>): Promise<void> {
+	if (!(await did_push_time_out(arguments_list))) return
+
+	console.warn(to_retry_notice(arguments_list))
+
+	if (!(await did_push_time_out(arguments_list))) return
+
+	throw create_timeout_error(arguments_list)
+}
+
+const git_push_transport = {
+	push,
+}
+
+export { git_push_transport }
+export {
+	KEEPALIVE_SSH_COMMAND,
+	PUSH_TIMEOUT_MESSAGE,
+	PUSH_TIMEOUT_MS,
+	SSH_COMMAND_VARIABLE,
+	SSH_LEGACY_VARIABLE,
+}