@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/git/git-execa-error.ts

@@ -22,6 +22,11 @@ function has_timed_out(error: unknown): boolean {
 	return error.timedOut === true
 }
 
+// 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. Shared by every git spawn that carries a
+// budget: the push (`git-push-transport.ts`) and the fetch and pull (`git-spawn.ts`).
+const TIMEOUT_EXIT_CODE = 'timeout'
+
 // The error a spawned git command fails with. The exit code is carried on `cause` as well as in the
 // message, because callers branch on it rather than parse it: `git_command.push` reads 128 there to
 // decide whether to retry with `--set-upstream`.
@@ -32,4 +37,4 @@ function create_spawn_error(command: string, exit_code: number | undefined): Err
 	return new Error(error_message, { cause: { exit_code: exit_code_string } })
 }
 
-export { create_spawn_error, get_exit_code, has_timed_out }
+export { create_spawn_error, get_exit_code, has_timed_out, TIMEOUT_EXIT_CODE }

package/{scripts-ai → scripts/git}/git-followup-finish.ts

@@ -1,11 +1,11 @@
-import { git_followup_cleanup, type CleanupStep } from '../scripts/git/git-followup-cleanup'
-import { git_followup_pending } from '../scripts/git/git-followup-pending'
-import { git_next_issues } from '../scripts/git/git-next-issues'
-import { review_attest } from '../scripts/review/review-attest'
-import { review_stamps } from '../scripts/review/review-stamps'
-import { run_hold } from '../scripts/run/run-hold'
-import { run_progress_clock } from '../scripts/run/run-progress-clock'
+import { review_attest } from '#scripts/review/review-attest'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { run_hold } from '#scripts/run/run-hold'
+import { run_progress_clock } from '#scripts/run/run-progress-clock'
 import { parse_completed_issue_number } from './followup-issue-number'
+import { git_followup_cleanup, type CleanupStep } from './git-followup-cleanup'
+import { git_followup_pending } from './git-followup-pending'
+import { git_next_issues } from './git-next-issues'
 
 // **The count of unreleased merges, not the project version** (joshuafolkken/kit#1486). This line
 // used to read the local `package.json` and was read as "the version this run just shipped"; children

package/scripts/git/git-followup-flush.ts

@@ -1,62 +1,88 @@
 import { observation_ledger } from '#scripts/observations/observation-ledger'
-import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { observations_flush } from '#scripts/observations/observations-flush'
 import { git_command } from './git-command'
-import { git_followup_cleanup } from './git-followup-cleanup'
-import { main_sync } from './main-sync'
+import { git_spawn } from './git-spawn'
 
 // The residual commit path for the observation ledger (joshuafolkken/kit#1810). A run's appended lines
-// ride its own commit (joshuafolkken/kit#2763), so after the merge the ledger is usually clean and this
-// short-circuits; what it still catches is a line appended after the commit — a second review round's
-// record — which would otherwise stay in the working tree until a person remembered to flush it. This
-// wires the flush into `pnpm josh followup`, the one step that knows the merge has landed.
+// ride its own commit (joshuafolkken/kit#2763), so the ledger is usually clean by now and this
+// short-circuits; what it still catches is a line appended after that commit — a second review round's
+// record — which would otherwise stay in the working tree after the merge.
 //
-// **It runs before the working-tree hold is released** (`scripts-ai/git-followup-finish.ts`, whose
-// `finish()` runs after `git_pr_followup.run()` returns), because a flush switches branches, and a
-// hold released first would let another run grab the tree mid-switch.
-
-const MAIN_SYNC_SUCCESS = 0
-const FLUSH_RECOVERY = 'pnpm josh observations:flush'
-const SYNC_FAILURE_MESSAGE =
-	'Could not return to the default branch to flush the observation ledger; `pnpm josh ms` printed the reason above.'
-
-// `observations_flush.flush` requires the default branch, so the checkout is returned to it first.
-// `main_sync.run` catches its own errors and answers with an exit code rather than throwing, so a
-// checkout it could not move is turned into the throw the guarded step below reports.
-async function sync_and_flush(): Promise<void> {
-	if ((await main_sync.run([])) !== MAIN_SYNC_SUCCESS) throw new Error(SYNC_FAILURE_MESSAGE)
-
-	console.info(await observations_flush.flush(new Date()))
+// **It commits onto the pull request's own branch, before the merge** (joshuafolkken/kit#2919). It used
+// to flush after the merge from the default branch, which a lane cannot reach, so a lane's lines
+// waited in the primary checkout for a batch-end flush and were lost there to another run's stash.
+// Committed to the branch instead, the lines merge with the pull request — in a lane as anywhere — and
+// the CI wait `pnpm josh followup` runs next covers the pushed commit like any other push.
+
+const COMMIT_MESSAGE_PREFIX = 'Record observation ledger entries'
+
+function commit_message(issue_number: string | undefined): string {
+	return issue_number === undefined
+		? COMMIT_MESSAGE_PREFIX
+		: `${COMMIT_MESSAGE_PREFIX} #${issue_number}`
 }
 
-// **Short-circuits when the ledger holds no pending append.** That is every run that recorded no
-// observation, so the ordinary run pays nothing. Guarded like its sibling tail steps (joshuafolkken/kit#1539): past the merge a flush
-// failure is reported, never allowed to take the merge, the epic close and the hold release with it.
-//
-// **A lane skips it outright** (joshuafolkken/kit#2419). Its ledger is the primary checkout's
-// (`observation-ledger-home.ts`), which this step cannot flush — `main_sync` refuses in a linked work
-// tree — so the line waits in the primary checkout and the `backlogrun` commits every lane's lines at
-// once through `pnpm josh run:carry --end` (joshuafolkken/kit#2492).
-async function flush_ledger_step(should_merge: boolean): Promise<void> {
-	if (
-		!should_merge ||
-		observation_ledger_home.is_lane() ||
-		!observation_ledger.has_pending_append(await git_command.status())
-	) {
-		return
+// **A broken line refuses the merge rather than riding it** (joshuafolkken/kit#2123): the branch's
+// ledger file goes away with the lane, so a line left behind here is a line lost.
+async function assert_grammar(): Promise<void> {
+	const broken = await observation_ledger_prepare.prepare(await git_command.repository_root())
+
+	if (broken.length > 0) throw new Error(observations_flush.broken_lines_message(broken))
+}
+
+// **A push that fails takes its commit back**, leaving the lines staged: the next `pnpm josh followup`
+// then finds them pending and retries. Left committed, they would read as clean and the merge would
+// go ahead without them, the lines stranded in a local commit no reader sees.
+async function push_or_undo_commit(): Promise<void> {
+	try {
+		await git_command.push()
+	} catch (error) {
+		await git_spawn.read(['reset', '--soft', 'HEAD~1'])
+		throw error
 	}
+}
+
+// Only the ledger paths are staged — whatever else the tree holds is the run's to commit, not this
+// step's — and `-A` takes a migration's deletion of an old path with it.
+async function commit_and_push(
+	paths: ReadonlyArray<string>,
+	issue_number: string | undefined,
+): Promise<void> {
+	await git_spawn.read(['add', '-A', '--', ...paths])
+	await git_command.commit(commit_message(issue_number))
+	await push_or_undo_commit()
+}
+
+// **Short-circuits when the ledger holds no pending append**, which is every run that recorded nothing
+// after its commit, and on a `--no-merge` run, which has no merge for the lines to ride.
+async function commit_ledger_step(
+	should_merge: boolean,
+	issue_number: string | undefined,
+): Promise<void> {
+	if (!should_merge) return
+
+	const status_output = await git_command.status()
+
+	if (!observation_ledger.has_pending_append(status_output)) return
+
+	await assert_grammar()
+
+	// Read again: the grammar check migrated any old-path ledger, which changes what is to be staged.
+	const paths = observation_ledger
+		.ledger_paths(await git_command.status())
+		.filter((file_path) => !observation_ledger.is_migration_claim(file_path))
+
+	// A live run's migration claim alone is pending, not a line: with no path, `git add -A --` would
+	// stage the whole tree.
+	if (paths.length === 0) return
 
-	// `should_merge` is always true past the early return; it is passed on as `run_guarded_step`'s
-	// guard flag rather than a literal `true` so this step stays identical to its sibling tail steps —
-	// hardcoding `true` would turn the guard on for a `--no-merge` run if the early return were ever
-	// dropped (the trap `in_progress_step` warns of).
-	await git_followup_cleanup.run_guarded_step(should_merge, {
-		label: 'The observation ledger flush',
-		recovery: FLUSH_RECOVERY,
-		run: sync_and_flush,
-	})
+	await commit_and_push(paths, issue_number)
+	console.info(
+		`💡 Committed ${String(paths.length)} observation ledger path(s) to the pull request.`,
+	)
 }
 
-const git_followup_flush = { flush_ledger_step }
+const git_followup_flush = { COMMIT_MESSAGE_PREFIX, commit_ledger_step }
 
 export { git_followup_flush }

package/scripts/git/git-followup-issue-close.ts

@@ -1,6 +1,6 @@
+import { epic_parse } from '#scripts/epic/epic-parse'
 import { poll, type PollOptions } from '#scripts/lib/poll'
 import { z } from 'zod'
-import { git_epic_parse } from './git-epic-parse'
 import { git_gh_command } from './git-gh-command'
 import { parse_json_object_safe } from './parse-json-array'
 
@@ -28,7 +28,7 @@ async function is_issue_closed(issue_number: string): Promise<boolean> {
 	const raw = await git_gh_command.issue_get_state_and_relations(issue_number)
 	const parsed = raw === undefined ? undefined : parse_json_object_safe(raw, state_read_schema)
 
-	return git_epic_parse.is_state_closed(parsed?.state)
+	return epic_parse.is_state_closed(parsed?.state)
 }
 
 const FOLLOWUP_CLOSER = 'pnpm josh followup'

package/scripts/git/git-followup-label.ts

@@ -46,7 +46,7 @@ async function read_label_names(issue_number: string): Promise<ReadonlyArray<str
 // **An issue that does not carry it is never written to**, which is what keeps the step silent on a
 // run whose issue was never labelled — a `404` swallowed into a warning would report a failure where
 // there was nothing to do. The read itself is always paid: one `number,labels,body` call per merged
-// run, which is the read `git-epic-read.ts` already makes rather than a field list of its own.
+// run, which is the read `epic-read.ts` already makes rather than a field list of its own.
 //
 // A run whose pull request named no issue has nothing to strip, so it returns rather than throwing:
 // the number is recovered from the `closes #N` keyword, and its absence is already reported where

package/scripts/git/git-followup-pending.ts

@@ -21,7 +21,7 @@ import { git_command } from './git-command'
 // there cannot include this run's own merge, and a bare number would be understated by exactly one.
 // Saying so is the honest form of the same measurement. The console line printed after the merge
 // passes `false` and carries no note, because by then the merge is on the remote and the fetch below
-// brings it in; `scripts-ai/git-followup-finish.ts` is that caller, so **both branches of this flag
+// brings it in; `git-followup-finish.ts` is that caller, so **both branches of this flag
 // are live**. What a run *does* about the count is `pnpm josh release:scope`, asked after the merge,
 // which reads `read_pending` below rather than this line (joshuafolkken/kit#1582).
 const MERGE_PENDING_NOTE = "— this run's merge is not counted; it lands next"

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

@@ -1,18 +1,19 @@
 #!/usr/bin/env tsx
 import { parseArgs } from 'node:util'
-import { git_branch } from '../scripts/git/git-branch'
-import { git_error } from '../scripts/git/git-error'
-import { git_notify, type GitNotifyConfig } from '../scripts/git/git-notify'
-import { git_pr_followup } from '../scripts/git/git-pr-followup'
-import { cli_body } from '../scripts/josh/cli-body'
-import { live_evidence } from '../scripts/review/live-evidence'
-import { review_attest } from '../scripts/review/review-attest'
-import { review_record } from '../scripts/review/review-record'
-import { load_optional_environment } from './environment-loader'
+import { cli_body } from '#scripts/josh/cli-body'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { live_evidence } from '#scripts/review/live-evidence'
+import { review_attest } from '#scripts/review/review-attest'
+import { review_record } from '#scripts/review/review-record'
 import { parse_issue_number_from_text } from './followup-issue-number'
+import { git_branch } from './git-branch'
+import { git_error } from './git-error'
 import { git_followup_finish } from './git-followup-finish'
+import { git_followup_flush } from './git-followup-flush'
+import { git_notify, type GitNotifyConfig } from './git-notify'
+import { git_pr_followup } from './git-pr-followup'
 
-load_optional_environment()
+josh_environment_file.load_environment_file()
 
 // cspell:words coderabbit
 
@@ -202,6 +203,17 @@ async function assert_merge_gates(
 	await assert_live_evidence(should_merge, branch_name)
 }
 
+// After the gates, before the CI wait: a line appended since the run's commit rides the pull request
+// itself, so it merges with it — a lane's included (joshuafolkken/kit#2919).
+async function prepare_merge(
+	should_merge: boolean,
+	issue_number: string | undefined,
+	branch_name: string,
+): Promise<void> {
+	await assert_merge_gates(should_merge, issue_number, branch_name)
+	await git_followup_flush.commit_ledger_step(should_merge, issue_number)
+}
+
 async function main(): Promise<void> {
 	const cli = parse_cli_arguments()
 
@@ -216,7 +228,7 @@ async function main(): Promise<void> {
 	const should_merge = is_merge_resolved(cli.values)
 	const branch_name = await resolve_branch_name(cli.values.branch)
 
-	await assert_merge_gates(should_merge, issue_number, branch_name)
+	await prepare_merge(should_merge, issue_number, branch_name)
 	// **The number the run reports on is the one it used**, which is the number the pull request
 	// closes where the invocation named none (joshuafolkken/kit#1539). Recovered inside `run`, so the
 	// tail records a run the command line could not identify rather than silently skipping it.

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

@@ -1,4 +1,5 @@
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { error_text } from '#scripts/lib/error-message'
 import { execa, execaSync } from 'execa'
 import { has_timed_out } from './git-execa-error'
 import { check_gh_installed } from './git-gh-check'
@@ -21,7 +22,7 @@ const BODY_FROM_STDIN = '-'
 //   *sleeps* rather than the wall clock, so each poll's requests sit on top of it. A request allowed
 //   to outlast that whole window would make the budget meaningless; half of it keeps one request
 //   from dominating the look-ahead.
-// - kit's other `gh` spawns already sit at 5 seconds (`repo-setting.ts`) and 20
+// - the readers that override it ask for 5 seconds (`repo-setting.ts`) and 20
 //   (`propagate-publish.ts`, `epic-cross-repo.ts`). Sixty is deliberately the most generous of them,
 //   because this entry also serves `--paginate` requests — several HTTP round trips inside one
 //   spawn — which a 5-second budget would break.
@@ -70,10 +71,10 @@ function to_timeout_option(timeout_ms?: number): { timeout: number } {
 // Nothing is spread when there is nothing to remove, so a spawn outside such a wrapper keeps its
 // options exactly as they were.
 //
-// **It is exported because this file is not the only place `gh` is spawned.** The synchronous
-// readers that spell their own `gh api` (`gh-spawn.ts`, `repo-setting.ts`, `epic-cross-repo.ts`,
-// `version-remote.ts`, `propagate-publish.ts`) spread it too, and `git-gh-exec-proxy.test.ts` refuses
-// a new `gh api` spawn anywhere under `scripts/` that does not.
+// **It is exported for the one spawn that is not a REST request** — `josh start`'s `gh repo create`
+// step (`start-exec.ts`). Every `gh api` request goes through the entries below since
+// joshuafolkken/kit#2901, which `gh-subcommand-guard.test.ts` enforces, and
+// `git-gh-exec-proxy.test.ts` still refuses a `gh api` spawn that does not spread it.
 interface DirectEnvironment {
 	env?: Record<string, undefined>
 }
@@ -84,8 +85,20 @@ function direct_environment(): DirectEnvironment {
 	return Object.keys(removed).length > 0 ? { env: removed } : {}
 }
 
-function to_spawn_options(timeout_ms?: number): { timeout: number } & DirectEnvironment {
-	return { ...to_timeout_option(timeout_ms), ...direct_environment() }
+interface SpawnOptions extends DirectEnvironment {
+	timeout: number
+	cwd?: string
+}
+
+// `cwd` is spread in only when given: `{owner}/{repo}` in a path is resolved from the checkout gh
+// runs in, so a caller pinned to the project root says so, and every other caller keeps inheriting
+// the process's own directory exactly as before.
+function to_spawn_options(timeout_ms?: number, cwd?: string): SpawnOptions {
+	return {
+		...to_timeout_option(timeout_ms),
+		...direct_environment(),
+		...(cwd !== undefined && { cwd }),
+	}
 }
 
 // What a request that ran out of time is labelled with, ahead of whatever gh managed to write.
@@ -113,10 +126,6 @@ function to_timeout_prefix(error: unknown): string {
 	return has_timed_out(error) ? `${GH_REQUEST_TIMEOUT_MESSAGE}: ` : ''
 }
 
-function to_error_message(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 // Surface the gh CLI's stderr as the thrown message when present (matching the previous spawn
 // behavior), otherwise fall back to execa's own message — **and append what gh wrote to stdout**.
 //
@@ -134,7 +143,7 @@ function to_error_message(error: unknown): string {
 function to_gh_error(error: unknown): Error {
 	const stderr = has_stderr_field(error) ? error.stderr.trim() : ''
 	const stdout = has_stdout_field(error) ? error.stdout.trim() : ''
-	const summary = stderr.length > 0 ? stderr : to_error_message(error)
+	const summary = stderr.length > 0 ? stderr : error_text.message_of(error)
 	const detail = stdout.length > 0 ? `${summary}\n${stdout}` : summary
 
 	return gh_failure.attach(
@@ -143,11 +152,16 @@ function to_gh_error(error: unknown): Error {
 	)
 }
 
-async function exec_gh_command(arguments_: Array<string>, timeout_ms?: number): Promise<string> {
+async function exec_gh_command(
+	arguments_: Array<string>,
+	timeout_ms?: number,
+	cwd?: string,
+): Promise<string> {
 	await check_gh_installed()
+	const options = to_spawn_options(timeout_ms, cwd)
 
 	try {
-		const { stdout } = await execa('gh', arguments_, to_spawn_options(timeout_ms)) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+		const { stdout } = await execa('gh', arguments_, options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 
 		return stdout.trimEnd()
 	} catch (error) {
@@ -161,12 +175,13 @@ async function exec_gh_command_with_stdin(input: {
 	// `number | undefined` rather than plain optional: `exec_gh_api` forwards its own optional field,
 	// which `exactOptionalPropertyTypes` will not narrow for it.
 	timeout_ms?: number | undefined
+	cwd?: string | undefined
 }): Promise<string> {
 	await check_gh_installed()
 
 	// Built ahead of the call so the spawn itself stays on one line: `// NOSONAR` suppresses the rule
 	// only on the line it sits on, and a wrapped call moves that line away from the reported one.
-	const options = { input: input.stdin_body, ...to_spawn_options(input.timeout_ms) }
+	const options = { input: input.stdin_body, ...to_spawn_options(input.timeout_ms, input.cwd) }
 
 	try {
 		const { stdout } = await execa('gh', input.args, options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
@@ -186,6 +201,12 @@ function parse_status_line(output: string): number | undefined {
 	return status === undefined ? undefined : Number(status)
 }
 
+// What a status probe that exited non-zero reached: `--include` keeps the status line even then,
+// and execa carries it on the error it throws.
+function status_of_failure(error: unknown): number | undefined {
+	return has_stdout_field(error) ? parse_status_line(error.stdout) : undefined
+}
+
 // The HTTP status of one `gh api` request, read from the status line rather than from `gh`'s error
 // text. A message is prose that can be reworded between releases; the status code is the protocol,
 // so a caller distinguishing "there is nothing at that number" (404) from "the read failed" (403,
@@ -215,7 +236,24 @@ async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<nu
 
 		return parse_status_line(stdout)
 	} catch (error) {
-		return has_stdout_field(error) ? parse_status_line(error.stdout) : undefined
+		return status_of_failure(error)
+	}
+}
+
+// The synchronous twin of `exec_gh_api_status`, for `epic-cross-repo.ts`, whose resolver is
+// synchronous all the way up to `epic_classify` (joshuafolkken/kit#2901). Same request, same
+// answer: the status line, or `undefined` when no status was reached. It cannot run
+// `check_gh_installed`, which awaits — a missing gh is a spawn that throws without stdout, so it
+// answers `undefined`, which is what that check would have led to anyway.
+function exec_gh_api_status_sync(path: string, timeout_ms?: number): number | undefined {
+	const options = to_spawn_options(timeout_ms)
+
+	try {
+		const { stdout } = execaSync('gh', ['api', '--include', '--silent', path], options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+		return parse_status_line(stdout)
+	} catch (error) {
+		return status_of_failure(error)
 	}
 }
 
@@ -251,8 +289,13 @@ interface GhApiRequest {
 	should_slurp?: boolean
 	jq_filter?: string
 	// The budget for this one request, overriding `GH_REQUEST_TIMEOUT_MS`. A field rather than a
-	// second argument for the reason recorded beside that constant (joshuafolkken/kit#1065).
+	// second argument for the reason recorded beside that constant (joshuafolkken/kit#1065). `0` is
+	// execa's own "no budget", kept for the one reader whose caller's writes depend on the answer
+	// (`gh-spawn.ts`, joshuafolkken/kit#805).
 	timeout_ms?: number
+	// The checkout gh runs in, which is what `{owner}/{repo}` in `path` resolves against. Absent means
+	// the process's own directory.
+	cwd?: string
 }
 
 function optional_flag(flag: string, value?: string): Array<string> {
@@ -277,20 +320,23 @@ function to_gh_api_args(request: GhApiRequest): Array<string> {
 
 // The response body of one `gh api` request, as text. Every REST caller that can await one goes
 // through it, so the verb, the body and the paging stop being spelled out per call site
-// (joshuafolkken/kit#1023). The synchronous readers that cannot — `gh-spawn.ts`, `epic-cross-repo.ts`
-// — still share its path builder.
+// (joshuafolkken/kit#1023). A caller that cannot await uses `exec_gh_api_sync` or
+// `read_gh_api_sync` below.
 //
 // Failure handling funnels through `to_gh_error` on both paths below, so a failed request throws
 // with gh's stderr summary *and* the JSON error body it wrote to stdout.
 async function exec_gh_api(request: GhApiRequest): Promise<string> {
 	const args = to_gh_api_args(request)
 
-	if (request.body === undefined) return await exec_gh_command(args, request.timeout_ms)
+	if (request.body === undefined) {
+		return await exec_gh_command(args, request.timeout_ms, request.cwd)
+	}
 
 	return await exec_gh_command_with_stdin({
 		args,
 		stdin_body: request.body,
 		timeout_ms: request.timeout_ms,
+		cwd: request.cwd,
 	})
 }
 
@@ -300,11 +346,10 @@ async function exec_gh_api(request: GhApiRequest): Promise<string> {
 // opens in the consumer is created here rather than by turning the whole runner asynchronous for
 // one request (joshuafolkken/kit#1042).
 //
-// It is the **write** side's synchronous entry, and the only one so far. The synchronous *readers*
-// named above `exec_gh_api` — `gh-spawn.ts`, `epic-cross-repo.ts`, `repo-setting.ts`,
-// `propagate-publish.ts`, `version-remote.ts` — each spell their own `['api', path, '--jq', …]` out
-// and share only the path builder; a read has no body and no verb to get wrong, which is why they
-// were left as they are rather than migrated here in passing.
+// It began as the write side's synchronous entry; since joshuafolkken/kit#2901 the synchronous
+// readers — `gh-spawn.ts`, `epic-cross-repo.ts`, `repo-setting.ts`, `propagate-publish.ts`,
+// `version-remote.ts` — go through it too, rather than each spelling its own `execaSync('gh', …)`
+// with its own error handling, timeout and proxy handling.
 //
 // **It is the same layer, not a second one.** The argument builder and the error translation are
 // shared with the asynchronous path above, so `--input -` for the body, `--jq` for the unwrap, and
@@ -318,7 +363,7 @@ async function exec_gh_api(request: GhApiRequest): Promise<string> {
 // replaced already did.
 function exec_gh_api_sync(request: GhApiRequest): string {
 	const body_option = request.body === undefined ? {} : { input: request.body }
-	const options = { ...body_option, ...to_spawn_options(request.timeout_ms) }
+	const options = { ...body_option, ...to_spawn_options(request.timeout_ms, request.cwd) }
 
 	try {
 		const { stdout } = execaSync('gh', to_gh_api_args(request), options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
@@ -329,13 +374,27 @@ function exec_gh_api_sync(request: GhApiRequest): string {
 	}
 }
 
+// `exec_gh_api_sync` for a reader to which a failed request is an answer rather than an error:
+// `undefined` for every failure — a non-zero exit, a timeout, gh missing — and the response text
+// otherwise. The readers that degrade instead of throwing (a report that says `unreadable`, a
+// registry read that retries) share this one catch rather than each writing their own.
+function read_gh_api_sync(request: GhApiRequest): string | undefined {
+	try {
+		return exec_gh_api_sync(request)
+	} catch {
+		return undefined
+	}
+}
+
 const git_gh_exec = {
 	direct_environment,
 	exec_gh_command,
 	exec_gh_command_with_stdin,
 	exec_gh_api,
 	exec_gh_api_sync,
+	read_gh_api_sync,
 	exec_gh_api_status,
+	exec_gh_api_status_sync,
 	parse_status_line,
 }
 

package/scripts/git/git-gh-issue-read.ts

@@ -1,4 +1,3 @@
-import type { IssueReference } from './git-epic-reference'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { gh_failure, type GhFailure } from './git-gh-failure'
@@ -10,6 +9,7 @@ import {
 	type RestIssue,
 } from './git-gh-issue-rest'
 import { gh_reachability } from './git-gh-reachability'
+import type { IssueReference } from './issue-reference'
 
 // Reading one issue. Split out of `git-gh-issue.ts`, which had grown past the file-length limit
 // while holding both the reads and the writes; the reads are what every epic command goes through,
@@ -341,7 +341,7 @@ async function issue_get_plan_fields_classified(issue_number: string): Promise<I
 	return await issue_view_json_classified(issue_number, PLAN_FIELDS)
 }
 
-// `state` rides along for `git-epic-add.ts`'s closed-epic refusal (joshuafolkken/kit#2337); every
+// `state` rides along for `epic-add.ts`'s closed-epic refusal (joshuafolkken/kit#2337); every
 // other caller reads only the labels and body and ignores it, so it costs no extra request.
 async function issue_get_labels_and_body(issue_number: string): Promise<string | undefined> {
 	return await issue_view_json(issue_number, 'number,state,labels,body')

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

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import type { IssueReference } from './git-epic-reference'
 import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
+import type { IssueReference } from './issue-reference'
 import { parse_json_array_or_undefined, parse_json_object_safe } from './parse-json-array'
 import { blocking_issue_schema } from './schemas'
 
@@ -19,7 +19,7 @@ import { blocking_issue_schema } from './schemas'
 //
 // `number` is required so that a 200 carrying something other than an issue — a proxy's HTML error
 // page, an API message object — fails the parse rather than passing as an issue whose every field is
-// missing. `git-epic-close` would turn that into `is_closed: false` for every child and report it as
+// missing. `epic-close` would turn that into `is_closed: false` for every child and report it as
 // fact. The dependency summary is absent on a pull request, which the issue endpoint serves as
 // readily as an issue, so it stays optional and tolerates an explicit null.
 const rest_issue_schema = z.looseObject({

package/scripts/git/git-gh-issue-write.ts

@@ -24,7 +24,7 @@ const PATCH_METHOD = 'PATCH'
 const DELETE_METHOD = 'DELETE'
 
 // `gh issue edit`, `gh issue comment` and `gh issue create` each printed one URL, and the callers
-// read it — `git-epic-run.ts` parses the epic's number back out of it. REST answers the whole
+// read it — `epic-run.ts` parses the epic's number back out of it. REST answers the whole
 // object, so the same value is unwrapped out of it rather than the shape being changed.
 const HTML_URL_FILTER = '.html_url'
 const ID_FILTER = '.id'
@@ -34,9 +34,9 @@ const COMMENTS_SEGMENT = '/comments'
 const CLOSED_STATE = 'closed'
 const COLOR_HASH = '#'
 
-// The four writers below answered `boolean` under `gh`, and their callers read it: `git-epic-run.ts`
-// only reports the epic label when it was applied, `git-epic-relations.ts` counts the relations it
-// could not apply, and `git-epic-close.ts` prints "close it manually" on a false. One try/catch
+// The four writers below answered `boolean` under `gh`, and their callers read it: `epic-run.ts`
+// only reports the epic label when it was applied, `epic-relations.ts` counts the relations it
+// could not apply, and `epic-close.ts` prints "close it manually" on a false. One try/catch
 // rather than four copies of it (`CLAUDE.md` → "No clones").
 async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean> {
 	try {
@@ -77,7 +77,7 @@ async function issue_try_comment(issue_number: string, body: string): Promise<bo
 // **The comment goes first**, which is what keeps the return value meaning what it meant: a `false`
 // then says "the issue is still open" in *both* failure branches, because the state change is the
 // last thing attempted. Closing first would answer `false` for an issue that is in fact closed, and
-// `git-epic-close.ts` prints "close it manually" on that answer.
+// `epic-close.ts` prints "close it manually" on that answer.
 //
 // **`comment: undefined` closes without commenting**, and it is what the ordering above costs: a run
 // whose comment landed and whose close was refused leaves the issue open carrying the comment, so
@@ -168,7 +168,7 @@ function issue_create_request(input: {
 }
 
 // The browser URL of the created issue, which is what `gh issue create` printed and what
-// `git-epic-run.ts` parses the epic's number out of.
+// `epic-run.ts` parses the epic's number out of.
 async function issue_create_with_label(input: {
 	title: string
 	label: string

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

@@ -43,9 +43,6 @@ const COMMENTS_QUERY = FULL_PAGE_QUERY
 // Written as a constant rather than inline: `{owner}` inside a template literal reads as a broken
 // interpolation.
 const OWNER_PLACEHOLDER = '{owner}'
-const NO_HEAD_REF_MESSAGE = 'gh api answered a pull request with no head branch'
-const FORK_HEAD_MESSAGE =
-	'gh api answered a pull request whose head branch is in another repository'
 // What a branch-keyed caller that cannot fold an absence into its own answer throws. Lives here
 // rather than beside either caller: the merge-gate snapshot and the two branch-keyed writes all need
 // it, and three copies of one message is the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1029).
@@ -236,21 +233,6 @@ async function pr_view(branch_name: string): Promise<string> {
 	return JSON.stringify(git_gh_pr_rest.to_pr_info(pull))
 }
 
-// Already keyed by number, so no resolution is needed. It throws where the others fold to an empty
-// answer, which is the contract `sync-dependabot-pins.ts` relies on: it checks out the branch it is
-// handed, and a guessed one would push template pins onto the wrong PR.
-async function pr_head_reference(pr_number: number): Promise<string> {
-	const pull = await read_pull(pr_number)
-	const reference = pull.head?.ref
-	if (reference === undefined) throw new Error(NO_HEAD_REF_MESSAGE)
-	// A fork's head is not on `origin` under this name, and `origin` may well carry a different branch
-	// that answers to it. Refusing is the same contract the missing ref has: the caller checks out what
-	// it is handed, so a guessed branch pushes template pins onto the wrong pull request.
-	if (!git_gh_pr_rest.is_same_repository_head(pull)) throw new Error(FORK_HEAD_MESSAGE)
-
-	return reference
-}
-
 // `undefined` when the listing could not be read — a failed request, or a PR whose number could not
 // be resolved. Not `'[]'`, which every failure used to become.
 //
@@ -300,7 +282,6 @@ const git_gh_pr_read = {
 	pr_get_url,
 	pr_get_body,
 	pr_view,
-	pr_head_reference,
 	pr_get_comments,
 	pr_get_review_comments,
 }
@@ -315,8 +296,6 @@ export {
 	read_pull,
 	require_pr_number,
 	resolve_pr_number,
-	FORK_HEAD_MESSAGE,
-	NO_HEAD_REF_MESSAGE,
 	NO_PULL_REQUEST_MESSAGE,
 	UNREADABLE_PULL_REQUEST_MESSAGE,
 }