@joshuafolkken/kit 1.1010.0 → 1.1035.0

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,
 }

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-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)]
 	}
 }
 

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/issue-labels.ts

@@ -282,7 +282,7 @@ function label_name_of(labels: ReadonlyArray<string>, wanted: string): string |
 
 // The same comparison for a caller holding label *names* rather than listing rows. `EpicChild.labels`
 // is an array of strings (`scripts/epic/epic-graph.ts`), which is the one shape `has_any_label` cannot
-// take — so `epic-classify.ts` and `git-epic-validate.ts` each grew a raw case-sensitive
+// take — so `epic-classify.ts` and `epic-validate.ts` each grew a raw case-sensitive
 // `Array.includes` instead, and an `Epic`-cased label walked past both. Kept here beside the rule it
 // implements rather than at either call site, for the reason the comment above gives.
 //

package/scripts/git/issue-reference.ts

@@ -0,0 +1,19 @@
+// An issue named from outside any one graph — a task-list row, a citation in prose, a blocker
+// relation, a child that could not be read. Repository **and** number, because a number alone cannot
+// identify one: issue numbers are unique per repository, so the same `#40` names two different issues
+// depending on who wrote it (joshuafolkken/kit#1014).
+//
+// It lives in the git layer because the `blocked-by` relations are read here and carry a repository
+// of their own (joshuafolkken/kit#1126); the epic domain builds on this layer, never the other way
+// round (joshuafolkken/kit#2904). `epic-reference` re-exports it, so every epic importer is unchanged.
+//
+// `state` is present only on a reference read from a `blocked-by` relation whose response carried it
+// (joshuafolkken/kit#1943). The classifier needs it for a blocker no named graph tracks, where there is
+// no child record to read the state from; every other reference leaves it out.
+interface IssueReference {
+	repo: string
+	number: number
+	state?: 'OPEN' | 'CLOSED'
+}
+
+export type { IssueReference }

package/scripts/git/main-merge.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { extract_issue_number } from '#scripts/hooks/check-commit-message'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
 import { main_merge_guard } from './main-merge-guard'
 
@@ -103,7 +104,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return await dispatch(argv)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return FAILURE_EXIT_CODE
 	}