@joshuafolkken/kit 1.1010.0 → 1.1050.0

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

@@ -21,7 +21,8 @@ import { git_gh_pr_snapshot } from './git-gh-pr-snapshot'
 // **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_create` for the duplicate-head response. The other, `pr_checkout`, is gone with its one caller,
+// `sync-dependabot-pins` (joshuafolkken/kit#2887).
 //
 // `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
@@ -139,27 +140,6 @@ async function pr_create(
 	return url
 }
 
-// **`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
@@ -270,7 +250,6 @@ const git_gh_pr = {
 	pr_create,
 	pr_get_classification,
 	pr_ensure_classification,
-	pr_checkout,
 	pr_comment,
 	pr_merge,
 	pr_update_body,

package/scripts/git/git-next-issues.ts

@@ -1,12 +1,14 @@
 import { git_gh_command } from './git-gh-command'
 import { has_any_label, NOT_DIRECTLY_RUNNABLE_LABELS } from './issue-labels'
+import { issue_rank, type DependencyRow } from './issue-rank'
 import { parse_json_array_safe } from './parse-json-array'
 import { open_issue_schema, type OpenIssueData } from './schemas'
 
 // The next-issues display printed when a workflow completes (#821): up to five open issues in
 // priority order, so the user picks the next run from the completion output instead of opening the
 // issue list. Priority is recency — a newer issue usually encodes the most current understanding
-// of the backlog — with the label-based exclusions below.
+// of the backlog — with the label-based exclusions below, under the ranking keys `issue-rank.ts`
+// defines (joshuafolkken/kit#2928).
 //
 // `prioritize` is also the order `epicrun` picks up `auto-ok` issues in (joshuafolkken/kit#906).
 // The two ask one question — which open issue outside an epic is run next — so they share one
@@ -37,6 +39,34 @@ function compare_newest_first(first: OpenIssueData, second: OpenIssueData): numb
 	return first.createdAt < second.createdAt ? 1 : -1
 }
 
+// A row's blockers by number. **Lossy across repositories**: a blocker elsewhere sharing a number
+// with a row here counts as one of its dependents. The listings this ranks are one repository's own,
+// and `backlog:next` re-ranks its offer from the qualified graph (`backlog-rank.ts`), so the cost is a
+// display row placed one slot off rather than a run started early.
+function dependency_row(issue: OpenIssueData): DependencyRow {
+	return {
+		key: String(issue.number),
+		blockers: (issue.blockedBy?.nodes ?? []).map((blocker) => String(blocker.number)),
+	}
+}
+
+// Every candidate in rank order, uncapped. `backlog:next` takes this rather than `prioritize`, so the
+// `run:solo` gate sees the whole ranking before anything is cut (joshuafolkken/kit#2928).
+function order(
+	issues: ReadonlyArray<OpenIssueData>,
+	completed_issue_number?: number,
+): Array<OpenIssueData> {
+	const candidates = issues
+		.filter((issue) => is_candidate(issue, completed_issue_number))
+		.toSorted(compare_newest_first)
+	const dependents = issue_rank.count_dependents(candidates.map((issue) => dependency_row(issue)))
+
+	return issue_rank.rank(candidates, (issue) => ({
+		labels: (issue.labels ?? []).map((label) => label.name),
+		dependents: dependents.get(String(issue.number)) ?? 0,
+	}))
+}
+
 // **This display deliberately does not drop a blocked issue, and the `auto-ok` pickup deliberately
 // does.** They share this ordering and differ on the set, which reads as an inconsistency and is not
 // one (joshuafolkken/kit#1005).
@@ -50,10 +80,7 @@ function prioritize(
 	issues: ReadonlyArray<OpenIssueData>,
 	completed_issue_number?: number,
 ): Array<OpenIssueData> {
-	return issues
-		.filter((issue) => is_candidate(issue, completed_issue_number))
-		.toSorted(compare_newest_first)
-		.slice(0, DISPLAY_LIMIT)
+	return order(issues, completed_issue_number).slice(0, DISPLAY_LIMIT)
 }
 
 // Empty input yields no lines at all — a bare header with nothing under it reads as an error.
@@ -90,6 +117,8 @@ async function fetch_next_issue_lines(completed_issue_number?: number): Promise<
 }
 
 const git_next_issues = {
+	DISPLAY_LIMIT,
+	order,
 	prioritize,
 	format_lines,
 	fetch_next_issue_lines,

package/scripts/git/git-pr-followup-wrapup.ts

@@ -1,6 +1,5 @@
-import { git_epic_close } from './git-epic-close'
+import { epic_close } from '#scripts/epic/epic-close'
 import { git_followup_cleanup } from './git-followup-cleanup'
-import { git_followup_flush } from './git-followup-flush'
 import { git_followup_issue_close } from './git-followup-issue-close'
 import { git_followup_label } from './git-followup-label'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
@@ -137,7 +136,7 @@ async function epic_close_step(input: WrapupInput): Promise<void> {
 		label: 'The epic auto-close',
 		recovery: undefined,
 		run: async () => {
-			await git_epic_close.close_completed_epics({
+			await epic_close.close_completed_epics({
 				issue_number: input.issue_number,
 				is_merged: input.should_merge,
 			})
@@ -234,9 +233,6 @@ async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {
 	}
 
 	await run_tail_steps(input)
-	// After the merge tail and before the hold is released (`git-followup-finish.ts`): the ledger
-	// flush switches branches, so it must land while this run still holds the tree (kit#1810).
-	await git_followup_flush.flush_ledger_step(input.should_merge)
 
 	lap(log, STAGE.completion_and_epic_close)
 }

package/scripts/git/git-preflight.ts

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { live_evidence } from '#scripts/review/live-evidence'
 import { changed_paths } from './changed-paths'
 import { git_branch } from './git-branch'
@@ -28,10 +29,6 @@ interface Resolution {
 	problems: Array<string>
 }
 
-function error_message(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 function resolve_from_branch(current_branch: string): Resolution {
 	const number = git_issue.branch_number(current_branch)
 
@@ -71,7 +68,7 @@ function resolve_from_title(
 	try {
 		return resolve_parsed(git_issue.parse(cli_input), current_branch, default_branch)
 	} catch (error) {
-		return { target: undefined, problems: [error_message(error)] }
+		return { target: undefined, problems: [error_text.message_of(error)] }
 	}
 }
 
@@ -89,7 +86,7 @@ async function classification_problems(target: Target): Promise<Array<string>> {
 
 		return []
 	} catch (error) {
-		return [error_message(error)]
+		return [error_text.message_of(error)]
 	}
 }
 
@@ -120,19 +117,37 @@ function refusal(problems: ReadonlyArray<string>): Error {
 	)
 }
 
-async function check(input: PreflightInput): Promise<void> {
+interface PreflightAnswer {
+	pr_target: Target | undefined
+	problems: Array<string>
+}
+
+async function answer(input: PreflightInput): Promise<PreflightAnswer> {
 	const { target, problems } = await resolve_target(input.cli_input)
 	// The classification and the evidence belong to the pull request, so a `--skip-pr` run asks neither.
 	const pr_target = input.will_open_pr ? target : undefined
 	const pr_problems = pr_target === undefined ? [] : await classification_problems(pr_target)
-	const all_problems = [...problems, ...pr_problems]
 
-	if (all_problems.length > 0) throw refusal(all_problems)
+	return { pr_target, problems: [...problems, ...pr_problems] }
+}
+
+// joshuafolkken/kit#2946: the unmet preconditions as a list, so `josh ship` can ask them before its
+// review and gate start instead of meeting the refusal at the commit stage.
+async function problems_of(input: PreflightInput): Promise<Array<string>> {
+	const { problems } = await answer(input)
+
+	return problems
+}
+
+async function check(input: PreflightInput): Promise<void> {
+	const { pr_target, problems } = await answer(input)
+
+	if (problems.length > 0) throw refusal(problems)
 
 	if (pr_target !== undefined) await announce_evidence(pr_target.branch_name)
 }
 
-const git_preflight = { check }
+const git_preflight = { check, problems_of }
 
 export type { PreflightInput }
 export { git_preflight }

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

@@ -1,6 +1,12 @@
 import { execa } from 'execa'
 import { git_utilities } from './constants'
-import { create_spawn_error, get_exit_code, has_timed_out } from './git-execa-error'
+import {
+	create_spawn_error,
+	get_exit_code,
+	has_timed_out,
+	TIMEOUT_EXIT_CODE,
+} from './git-execa-error'
+import { git_ssh_keepalive } from './git-ssh-keepalive'
 
 const MS_PER_SECOND = 1000
 
@@ -33,65 +39,10 @@ const PUSH_TIMEOUT_LABEL = `${String(PUSH_TIMEOUT_SECONDS)}s`
 // 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'
+// `TIMEOUT_EXIT_CODE` is never '128', which `is_upstream_not_set_error` compares against, so a
+// timed-out bare push is never mistaken for a missing upstream and retried as `--set-upstream`.
 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
@@ -99,12 +50,10 @@ interface PushOptions {
 }
 
 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 } : {},
+		env: await git_ssh_keepalive.to_environment(),
 	}
 }
 
@@ -142,7 +91,7 @@ function to_retry_notice(arguments_list: Array<string>): string {
 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 } })
+	return new Error(message, { cause: { exit_code: TIMEOUT_EXIT_CODE } })
 }
 
 // One push, bounded and retried once — and **only** on a timeout. A push the remote rejected (a
@@ -164,10 +113,4 @@ const git_push_transport = {
 }
 
 export { git_push_transport }
-export {
-	KEEPALIVE_SSH_COMMAND,
-	PUSH_TIMEOUT_MESSAGE,
-	PUSH_TIMEOUT_MS,
-	SSH_COMMAND_VARIABLE,
-	SSH_LEGACY_VARIABLE,
-}
+export { PUSH_TIMEOUT_MESSAGE, PUSH_TIMEOUT_MS }

package/scripts/git/git-spawn.ts

@@ -1,6 +1,13 @@
 import { execa } from 'execa'
 import { git_utilities } from './constants'
-import { create_spawn_error, get_exit_code } from './git-execa-error'
+import {
+	create_spawn_error,
+	get_exit_code,
+	has_timed_out,
+	TIMEOUT_EXIT_CODE,
+} from './git-execa-error'
+import { PUSH_TIMEOUT_MS } from './git-push-transport'
+import { git_ssh_keepalive } from './git-ssh-keepalive'
 
 // 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 —
@@ -9,8 +16,8 @@ import { create_spawn_error, get_exit_code } from './git-execa-error'
 // `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
+// second helper of this kind: a push needs a transport-fault retry that no other command has, so it
+// spawns git itself. The timeout it carries is shared here by `read_remote` / `with_output_remote`. 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
@@ -26,6 +33,73 @@ async function read(arguments_: Array<string>): Promise<string> {
 	return stdout.trimEnd()
 }
 
+// The budget for a git call that talks to the remote — `fetch` and `pull` (joshuafolkken/kit#2942).
+// `read` and `with_output` wait without end, and a `git fetch --prune` under `josh main:sync` sat on
+// a dead ssh connection for 37 minutes, stalling the unattended backlog driver whose merge step runs
+// it. The push's budget is reused rather than a second number chosen: both transfer objects over the
+// same transport, and that one is already read off what a healthy transfer costs here.
+const REMOTE_TIMEOUT_MS = PUSH_TIMEOUT_MS
+const MS_PER_SECOND = 1000
+
+// A budget kill is reported as a timeout, never as whatever the killed process printed first, and
+// `cause` carries the same `TIMEOUT_EXIT_CODE` a timed-out push does. Unlike the push it is not
+// retried here: what the issue needed is that the wait ends, and a failure then surfaces to the
+// caller — `run:merge` raises a failed `main:sync` — instead of a second budget doubling the wait.
+function to_remote_error(command: string, error: unknown, timeout_ms: number): Error {
+	if (!has_timed_out(error)) return create_spawn_error(command, get_exit_code(error))
+
+	const seconds = String(Math.round(timeout_ms / MS_PER_SECOND))
+
+	return new Error(`git ${command} timed out after ${seconds}s`, {
+		cause: { exit_code: TIMEOUT_EXIT_CODE },
+	})
+}
+
+interface RemoteOptions {
+	stdio?: 'inherit'
+	timeout: number
+	env: Record<string, string>
+}
+
+// One remote call, bounded and kept alive. execa kills git on the budget; the ssh keepalive is what
+// makes ssh — which git does not kill with itself — exit on a dead connection as well.
+async function spawn_remote(arguments_: Array<string>, options: RemoteOptions): Promise<string> {
+	const git_cmd = 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.
+		const { stdout } = await execa(git_cmd, arguments_, options) // NOSONAR
+
+		return typeof stdout === 'string' ? stdout.trimEnd() : ''
+	} catch (error) {
+		throw to_remote_error(arguments_[0] ?? '', error, options.timeout)
+	}
+}
+
+// `read` for a call that reaches the remote. The budget is a parameter only so a test can hold it to
+// seconds; every production caller takes the default.
+async function read_remote(
+	arguments_: Array<string>,
+	timeout_ms: number = REMOTE_TIMEOUT_MS,
+): Promise<string> {
+	return await spawn_remote(arguments_, {
+		timeout: timeout_ms,
+		env: await git_ssh_keepalive.to_environment(),
+	})
+}
+
+// `with_output` for a call that reaches the remote — the output stays on the terminal, as a pull's
+// progress and a credential prompt need.
+async function with_output_remote(command: string, arguments_list: Array<string>): Promise<void> {
+	await spawn_remote([command, ...arguments_list], {
+		stdio: 'inherit',
+		timeout: REMOTE_TIMEOUT_MS,
+		env: await git_ssh_keepalive.to_environment(),
+	})
+}
+
 async function with_output(command: string, arguments_list: Array<string>): Promise<void> {
 	const git_command_bin = git_utilities.get_git_command_for_spawn()
 
@@ -41,7 +115,9 @@ async function with_output(command: string, arguments_list: Array<string>): Prom
 
 const git_spawn = {
 	read,
+	read_remote,
 	with_output,
+	with_output_remote,
 }
 
 export { git_spawn }

package/scripts/git/git-ssh-keepalive.ts

@@ -0,0 +1,74 @@
+import { execa } from 'execa'
+import { git_utilities } from './constants'
+
+// The ssh environment every git network call runs under (joshuafolkken/kit#2942). It began inside
+// `git-push-transport.ts` as the push's own (joshuafolkken/kit#1251), and moved here when the fetch
+// and pull of `josh main:sync` turned out to need the same thing: a dead connection under a `git
+// fetch` was waited on for 37 minutes, stalling the unattended backlog driver behind it.
+//
+// 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 caller's
+// timeout bounds the damage either way; this is what makes the common case fail in seconds rather
+// than sit out the whole budget — and, because ssh exits on its own, it is also what leaves no ssh
+// behind: git does not kill its transport child when it is itself killed on a timeout.
+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'
+
+// 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 git 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 connecting. 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 caller's timeout still bounds the call,
+// 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
+	}
+}
+
+// The `env` a git network spawn passes to execa: the keepalive command, or nothing at all.
+async function to_environment(): Promise<Record<string, string>> {
+	const should_keep_alive = !(await has_configured_ssh_command())
+
+	return should_keep_alive ? { [SSH_COMMAND_VARIABLE]: KEEPALIVE_SSH_COMMAND } : {}
+}
+
+const git_ssh_keepalive = {
+	to_environment,
+}
+
+export { git_ssh_keepalive }
+export { KEEPALIVE_SSH_COMMAND, SSH_COMMAND_VARIABLE, SSH_LEGACY_VARIABLE }

package/scripts/git/git-staging.ts

@@ -1,6 +1,7 @@
 import {
+	LEGACY_OBSERVATION_LEDGER_PATHS,
 	observation_ledger,
-	OBSERVATION_LEDGER_PATHS,
+	OBSERVATION_LEDGER_DIRECTORY,
 } from '#scripts/observations/observation-ledger'
 import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { git_command } from './git-command'
@@ -77,17 +78,28 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 // **A line that breaks the grammar keeps the old exclusion** (joshuafolkken/kit#2123): the commit
 // goes ahead without the ledger, and `pnpm josh observations:flush` — which refuses the same line and
 // names it — is where it is repaired. The migration is run first, as the flush runs it, so a line
-// still on the old path (joshuafolkken/kit#2724) is committed at the new one. A lane has no ledger
-// line of its own to carry: its writers append to the primary checkout's.
+// still on an old path (joshuafolkken/kit#2724) is committed in the directory. **A lane carries its
+// own lines** (joshuafolkken/kit#2919): its writers append to its own tree's issue file, so this is
+// the step that takes them to the default branch.
+const LEDGER_PATHSPECS: ReadonlyArray<string> = [
+	OBSERVATION_LEDGER_DIRECTORY,
+	...LEGACY_OBSERVATION_LEDGER_PATHS,
+]
+
 async function ledger_exclusions(): Promise<ReadonlyArray<string>> {
 	const broken = await observation_ledger_prepare.prepare(await git_command.repository_root())
 
-	return broken.length > 0 ? OBSERVATION_LEDGER_PATHS : []
+	return broken.length > 0 ? LEDGER_PATHSPECS : []
+}
+
+// An excluded pathspec covers what sits under it, as git reads it — the directory's files included.
+function is_excluded(file_path: string, excluded: ReadonlyArray<string>): boolean {
+	return excluded.some((spec) => file_path === spec || file_path.startsWith(`${spec}/`))
 }
 
 // A migration claim is a copy mid-move, never the ledger itself, so it is never staged.
 function is_stageable(file_path: string, excluded: ReadonlyArray<string>): boolean {
-	return !observation_ledger.is_migration_claim(file_path) && !excluded.includes(file_path)
+	return !observation_ledger.is_migration_claim(file_path) && !is_excluded(file_path, excluded)
 }
 
 // **Said out loud, because the alternative is an unexplained failure.** With the ledger the only
@@ -95,15 +107,15 @@ function is_stageable(file_path: string, excluded: ReadonlyArray<string>): boole
 // 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/maintainers/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.
+// **The paths are parsed rather than matched as substrings**: `docs/maintainers/observations-old/x.md`
+// 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, excluded: ReadonlyArray<string>): void {
 	const left_out = status_output
 		.split('\n')
 		.filter((line) => line.trim().length > 0)
 		.map((line) => observation_ledger.status_path(line))
-		.filter((file_path) => excluded.includes(file_path))
+		.filter((file_path) => is_excluded(file_path, excluded))
 
 	for (const file_path of left_out) {
 		console.info(

package/{scripts-ai → scripts/git}/git-workflow.ts

@@ -1,16 +1,16 @@
 #!/usr/bin/env tsx
 import { parseArgs } from 'node:util'
-import { git_branch } from '../scripts/git/git-branch'
-import { git_commit } from '../scripts/git/git-commit'
-import { git_error } from '../scripts/git/git-error'
-import { git_issue, type IssueInfo } from '../scripts/git/git-issue'
-import { git_pr } from '../scripts/git/git-pr'
-import { git_preflight } from '../scripts/git/git-preflight'
-import { git_prompt, type WorkflowConfirmations } from '../scripts/git/git-prompt'
-import { git_push } from '../scripts/git/git-push'
-import { git_staging } from '../scripts/git/git-staging'
-import { cli_body } from '../scripts/josh/cli-body'
-import { test_red_commit } from '../scripts/test/test-red-commit'
+import { cli_body } from '#scripts/josh/cli-body'
+import { test_red_commit } from '#scripts/test/test-red-commit'
+import { git_branch } from './git-branch'
+import { git_commit } from './git-commit'
+import { git_error } from './git-error'
+import { git_issue, type IssueInfo } from './git-issue'
+import { git_pr } from './git-pr'
+import { git_preflight } from './git-preflight'
+import { git_prompt, type WorkflowConfirmations } from './git-prompt'
+import { git_push } from './git-push'
+import { git_staging } from './git-staging'
 
 const SKIP_MESSAGES = {
 	commit: '💡 Commit skipped.',

package/scripts/git/github-issue-url.ts

@@ -6,7 +6,7 @@
 // notification carrying only a pull-request URL until joshuafolkken/kit#994 added the second form
 // here rather than beside it.
 //
-// Two other modules read a URL for something narrower and keep their own patterns. `git-epic-parse`
+// Two other modules read a URL for something narrower and keep their own patterns. `epic-parse`
 // scans an epic body for task-list rows, so its regex is anchored to the row marker and runs
 // globally over a document; `propagate-steps` takes the trailing number of whatever URL
 // `gh issue create` just printed, where the repository is already known. This one is for a caller

package/scripts/git/gone-branch.ts

@@ -100,9 +100,10 @@ async function delete_each(names: ReadonlyArray<string>): Promise<PruneResult> {
 }
 
 // `fetch --prune` first, because `[gone]` is read from the remote-tracking refs and those outlive the
-// remote branch until something prunes them.
+// remote branch until something prunes them. The fetch is the one call here that reaches the remote,
+// so it is the one bounded (joshuafolkken/kit#2942).
 async function prune(default_branch: string): Promise<PruneResult> {
-	await git_spawn.read(['fetch', '--prune'])
+	await git_spawn.read_remote(['fetch', '--prune'])
 
 	return await delete_each(await read_candidates(default_branch))
 }