@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/gate/verification-gate.ts

@@ -11,6 +11,7 @@ import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { core_budget } from './core-budget'
+import { gate_ledger, type GateLedgerStart } from './gate-ledger'
 import { gate_plan, type GatePlan } from './gate-plan'
 import { gate_report, type GateStep, type GateStepResult } from './gate-report'
 import { gate_skip } from './gate-skip'
@@ -19,15 +20,10 @@ import { gate_tree, type GateTree } from './gate-tree'
 import { project_checks } from './project-checks'
 import { scoped_green, type ScopedSources } from './scoped-green'
 
-// joshuafolkken/kit#914: the completion gate's four checks are independent and share no mutable
-// state, yet every entry point ran them one after another — paid again on every `epicrun` child,
-// every `/code-review` fix and every `halfrun` stop. Worse than the seconds: a serial gate reports
-// one failure at a time, so a tree with a lint error and a type error costs two full round trips to
-// discover.
-//
-// The margin has narrowed as the checks gained caches and is re-measured rather than repeated: on
-// this repository today, 19.1s back to back against 15.1s together (joshuafolkken/kit#1258). How
-// many run at once, and how wide the unit suite fans out, are `gate-plan.ts`'s to decide.
+// The completion gate's four checks are independent and share no mutable state, so they run
+// together. Beyond the seconds: a serial gate reports one failure at a time, so a tree with a lint
+// error and a type error would cost two full round trips to discover. How many run at once, and how
+// wide the unit suite fans out, are `gate-plan.ts`'s to decide.
 //
 // Each step shells out to the `josh` sub-command that already defines it, rather than repeating the
 // underlying tool invocations here — one definition per check, in `josh-commands-development.ts`.
@@ -59,7 +55,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 }
 
 // The record `josh review:brief` reads, written only on a fully green run and only with the tree it
-// was green on (joshuafolkken/kit#1241). `/code-review` runs in a forked process that reads none of
+// was green on. `/code-review` runs in a forked process that reads none of
 // this repository's documents, so "the unit tests already passed" reaches it only if the invocation
 // carries it — and it may only carry it if something wrote down that they did, on **this** tree.
 //
@@ -68,15 +64,16 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // project has no tests — must not become "the unit tests all passed": the gate keeps that skip
 // visible on the console, and a record erasing it would have the brief tell a review agent not to
 // re-run tests that never ran. A step that passed **with a checker's warnings** is withheld for the
-// same reason one place further on (joshuafolkken/kit#1328): since the record is now reused instead of
-// the checks being re-run, a warning printed once would never be printed again on that tree, and
-// hiding an eslint or svelte-check finding is the same failure as hiding a skip. It is
-// `has_checker_warning`, not `has_warnings`, that decides this (joshuafolkken/kit#2318): the loose
+// same reason one place further on: since the record is reused instead of the checks being re-run, a
+// warning printed once would never be printed again on that tree, and hiding an eslint or
+// svelte-check finding is the same failure as hiding a skip. It is `has_checker_warning`, not
+// `has_warnings`, that decides this: the loose
 // marker match is right for the print path, where a false positive costs one printed body, but here a
 // false positive withholds the whole record and turns a green gate's `run:review --join` red — so a
 // benign line from another tool (a Vite config deprecation on `test:unit`) must not withhold it. A
 // tree that moved while
-// the checks were in flight (the `PostToolUse` formatter, an editor save) is not the tree they read.
+// the checks were in flight (the `PostToolUse` formatter, an editor save) is not the tree they read —
+// with no exception: no gate step writes to the tree.
 // And a failed write leaves no record at all, which a temp-directory problem must never turn into a
 // red gate.
 //
@@ -105,7 +102,7 @@ async function record_green_gate(
 	}
 }
 
-// The marker that says a gate is running on this tree right now (joshuafolkken/kit#1242). The gate
+// The marker that says a gate is running on this tree right now. The gate
 // and `/code-review` are started together — neither writes to the working tree — so by the time
 // `josh review:brief` composes the invocation the checks are usually still in flight. Without this
 // record that state reads as "no gate was ever run", and the review agent runs the unit suite the
@@ -114,8 +111,8 @@ async function record_green_gate(
 // **Both halves swallow their failure, and for the same reason `record_green_gate` does**: the
 // marker is a convenience for the next command and nothing about it may reach the gate's verdict. A
 // marker that could not be written costs a brief that says `Not verified`, which is the safe
-// direction; one that could not be cleared costs nothing beyond the file itself, because since
-// joshuafolkken/kit#1245 the record names the writing process by pid **and** start time — so a marker
+// direction; one that could not be cleared costs nothing beyond the file itself, because the record
+// names the writing process by pid **and** start time — so a marker
 // this gate leaves behind reads as not running from the moment the gate exits, however long it sits
 // there and whatever the operating system later does with that pid. The next gate overwrites it.
 function mark_gate_running(before: Record<string, string>, target?: string): void {
@@ -154,8 +151,8 @@ async function with_gate_marker<T>(
 	}
 }
 
-// This gate's share of the machine, resolved once at the gate's entry and carried down as one value
-// (joshuafolkken/kit#2351). `available_cores` is the budget every check reserves against; `is_reserved`
+// This gate's share of the machine, resolved once at the gate's entry and carried down as one value.
+// `available_cores` is the budget every check reserves against; `is_reserved`
 // is false for a gate nested inside another gate's unit suite — this repository's own gate tests — so
 // the outer gate reserves and every gate beneath it does not. Captured before this gate sets
 // `JOSH_UNIT_RUN_MARKED`, which is why it is read at entry rather than re-derived here.
@@ -171,12 +168,13 @@ function default_budget(): BudgetContext {
 	}
 }
 
-// A gate step paired with the cores it reserves from the machine-wide budget while it runs
-// (joshuafolkken/kit#2351). The weight travels with the step so `run_gate_steps` never has to re-pair a
+// A gate step paired with the cores it reserves from the machine-wide budget while it runs.
+// The weight travels with the step so `run_gate_steps` never has to re-pair a
 // step with its check by index.
 interface ReservedStep {
 	step: GateStep
 	weight: number
+	memory_mb: number
 }
 
 async function build_reserved_steps(
@@ -188,12 +186,13 @@ async function build_reserved_steps(
 		plan.checks.map(async (check) => ({
 			step: await build_gate_step(check, start_directory, plan),
 			weight: gate_plan.check_weight(check, plan, available_cores),
+			memory_mb: gate_plan.check_memory(check, plan, available_cores),
 		})),
 	)
 }
 
 // **A nested gate takes no reservation, and the budget is what makes that necessary rather than
-// merely tidy** (joshuafolkken/kit#2351). The unit step spawns the suite, which runs this repository's
+// merely tidy**. The unit step spawns the suite, which runs this repository's
 // own gate tests; each of those is a gate inside the outer gate's unit reservation, and a place it
 // claimed would wait for cores the outer gate cannot free until the suite — this test included —
 // finishes.
@@ -205,26 +204,29 @@ async function run_reserved_step(
 
 	return await core_budget.with_core_reservation(
 		reserved.weight,
-		async () => await run_gate_step(reserved.step),
-		{ budget: budget.available_cores },
+		async (admission) => ({
+			...(await run_gate_step(reserved.step)),
+			budget_note: core_budget.describe_overflow(admission),
+		}),
+		{ budget: budget.available_cores, memory_mb: reserved.memory_mb },
 	)
 }
 
 // `bounded_pool` rather than a bare `Promise.all`, so the plan's `concurrency` is what decides how
-// many run at once (joshuafolkken/kit#1258). **The all-failures-in-one-pass property survives the
+// many run at once. **The all-failures-in-one-pass property survives the
 // change** because no check ever rejects: `buffered_process` reports a non-zero exit as a value, so
 // the pool's first-failure abort — written for callers that spawn real Claude sessions — never
 // fires here and every queued check still runs. Results come back in input order however they
 // finished, which is what keeps the printed sections in declaration order. Each step first claims its
-// place in the machine-wide budget and waits while the budget is full (joshuafolkken/kit#2351).
+// place in the machine-wide budget and waits while the budget is full.
 async function run_gate_steps(
 	plan: GatePlan,
 	budget: BudgetContext = default_budget(),
 ): Promise<ReadonlyArray<GateStepResult>> {
 	const reserved = await build_reserved_steps(process.cwd(), plan, budget.available_cores)
 
-	// **The checks run under the held mark, so a check's own dispatch claims nothing**
-	// (joshuafolkken/kit#3345). Each check is a `pnpm josh <target>` child, and a target that declares
+	// **The checks run under the held mark, so a check's own dispatch claims nothing**.
+	// Each check is a `pnpm josh <target>` child, and a target that declares
 	// a weight would otherwise claim a second place for the cores reserved for it here. A nested gate
 	// sets the mark too, since its checks are covered by the outer gate's reservation.
 	return await core_budget.with_held_mark(
@@ -237,15 +239,15 @@ async function run_gate_steps(
 	)
 }
 
-// **Both markers are claims about the unit suite, so a gate that is not running it makes neither**
-// (joshuafolkken/kit#1226). The in-flight marker tells the next `josh review:brief` that a gate is
+// **Both markers are claims about the unit suite, so a gate that is not running it makes neither**.
+// The in-flight marker tells the next `josh review:brief` that a gate is
 // covering this tree right now, which is what stops a review agent re-running the suite; the
 // unit-run marker tells a sibling lane a vitest run is on the machine, which is what makes that
 // lane divide its own workers. A `--no-unit` gate that wrote either would be answering for a check
 // it never started — the first by telling a review the tests are covered when they are running in a
 // different CI job, the second by throttling a lane on its behalf.
 //
-// **The work the markers cover ends at the green record, not at the last check** (joshuafolkken/kit#2434).
+// **The work the markers cover ends at the green record, not at the last check**.
 // Cleared before `record_green_gate` wrote, the in-flight marker left a gap of tens of milliseconds in
 // which `run:review --join` read neither a running gate nor a green one — and answered RED for a gate
 // that was about to record green. Cleared after it, a reader that sees no marker is reading a gate
@@ -271,11 +273,16 @@ async function run_marked_gate<T>(
 // a core count the plan was not derived from — the one misreading this line exists to prevent.
 // The concurrent-run count is read here rather than inside `gate-plan.ts` for the reason the core
 // count already is: that module stays a pure function of its inputs, and the machine is asked once and
-// handed to both calls. Counted *before* the unit step writes its own marker, so `+ 1` is this gate
-// (joshuafolkken/kit#1515).
+// handed to both calls. Counted *before* the unit step writes its own marker, so `+ 1` is this gate.
 function announce_gate_plan(is_unit_included: boolean, available_cores: number): GatePlan {
 	const concurrent_runs = unit_worker_share.live_run_count() + unit_worker_share.SOLO_RUNS
-	const plan = gate_plan.resolve_gate_plan(available_cores, concurrent_runs, is_unit_included)
+	const is_kit_repository = project_checks.is_kit_repository(process.cwd())
+	const plan = gate_plan.resolve_gate_plan(
+		available_cores,
+		concurrent_runs,
+		is_unit_included,
+		is_kit_repository,
+	)
 
 	process.stdout.write(`${gate_plan.format_gate_plan(plan, available_cores, concurrent_runs)}\n`)
 
@@ -300,20 +307,20 @@ interface GateOptions {
 	// inside `pnpm josh gate`, so a test writing to the shared path would overwrite the live gate's
 	// own log with the output of four checks that never ran.
 	log_path?: string
-	// **The scoped pre-check the CLI entry turns on** (joshuafolkken/kit#2296). Off everywhere else so
+	// **The scoped pre-check the CLI entry turns on**. Off everywhere else so
 	// that a direct `run_verification_gate` call — the whole of `verification-gate.test.ts` — is never
 	// refused by a real checkout's missing scoped record; `run_gate_command` sets it true.
 	is_scoped_enforced?: boolean
 	// The scoped records' paths, overridable so a test can plant a green pair rather than depend on the
 	// surrounding checkout's — the reason `scoped-green.ts` takes a `source` per stamp.
 	scoped_sources?: ScopedSources
-	// The lane ledger a finished gate's duration is appended to (joshuafolkken/kit#3355). Only the CLI
+	// The lane ledger a finished gate's duration is appended to. Only the CLI
 	// entry resolves it, so a suite driving the gate never writes a measurement of checks that never ran.
 	ledger_path?: string | undefined
 }
 
 // **The gate refuses to start when the scoped pair has not been green on this tree**
-// (joshuafolkken/kit#2296) — the same record `josh review:brief` reads, applied one step earlier so the
+//  — the same record `josh review:brief` reads, applied one step earlier so the
 // first gate is the only gate. It is the CLI entry's check alone (`is_scoped_enforced`), and it never
 // fires for CI's `--no-unit` gate or a `--force` run: CI has no scoped record in front of it, and
 // `--force` is the caller saying to run regardless. `scoped_green` owns the record and the `JOSH_SCOPED_GREEN`
@@ -325,12 +332,12 @@ function scoped_precheck_refusal(tree: GateTree, options: GateOptions): string |
 	return scoped_green.refusal_for(tree.files, tree.base, options.scoped_sources)
 }
 
-// **A partial gate records nothing green, and this is the same rule as the skip one layer out**
-// (joshuafolkken/kit#1226). The record's whole meaning to `josh review:brief` and to `gate_skip` is
+// **A partial gate records nothing green, and this is the same rule as the skip one layer out**.
+// The record's whole meaning to `josh review:brief` and to `gate_skip` is
 // "every check this repository gates on passed on exactly this tree"; a `--no-unit` run proves three
 // of the four, so writing it would let the next full `josh gate` be skipped on a tree whose unit
-// suite nobody ran here — a check reporting success without having run, which is the state
-// joshuafolkken/kit#1224 exists to refuse.
+// suite nobody ran here — a check reporting success without having run, which is the state the
+// skip rule exists to refuse.
 async function record_whole_gate(
 	plan: GatePlan,
 	results: ReadonlyArray<GateStepResult>,
@@ -343,12 +350,12 @@ async function record_whole_gate(
 }
 
 // Reports the checks and records a green result — inside the markers, so the in-flight one outlives
-// the record it announces (joshuafolkken/kit#2434).
+// the record it announces.
 async function settle_gate(
 	plan: GatePlan,
 	results: ReadonlyArray<GateStepResult>,
 	tree: GateTree,
-	options: GateOptions & { started_at: number },
+	options: GateOptions & { started_at: number; ledger: GateLedgerStart },
 ): Promise<number> {
 	const elapsed_ms = performance.now() - options.started_at
 	const failed_labels = gate_report.report_gate_steps(results, {
@@ -359,9 +366,7 @@ async function settle_gate(
 	})
 	const is_passed = failed_labels.length === 0
 
-	if (options.ledger_path !== undefined) {
-		await lane_ledger.record_gate(options.ledger_path, elapsed_ms, is_passed)
-	}
+	await gate_ledger.record(options.ledger, results, { elapsed_ms, is_passed })
 
 	if (!is_passed) return FAIL_EXIT_CODE
 
@@ -373,15 +378,18 @@ async function settle_gate(
 // The plan line is printed by the checked path alone. A run that announced a four-way fan-out and
 // then skipped would be describing something that never happened, and the skip's own line already
 // says everything there is to say about a gate that started no process. The reporting itself is
-// `gate-report.ts`'s (joshuafolkken/kit#2296).
+// `gate-report.ts`'s.
 async function run_checked_gate(
 	tree: GateTree,
 	options: GateOptions,
 	started_at: number,
 ): Promise<number> {
 	const is_unit_included = options.is_unit_included ?? true
+	// Read before the concurrent-run count, never between it and the marker below: the reading waits out
+	// a sample window, and a lane counting inside that window would miss this gate.
+	const ledger = await gate_ledger.start(options.ledger_path)
 	// Resolved at the gate's entry, before this gate sets `JOSH_UNIT_RUN_MARKED`, so a gate nested in the
-	// unit suite reads the flag as set and reserves nothing (joshuafolkken/kit#2351).
+	// unit suite reads the flag as set and reserves nothing.
 	const budget = default_budget()
 	const plan = announce_gate_plan(is_unit_included, budget.available_cores)
 
@@ -390,11 +398,11 @@ async function run_checked_gate(
 	// together — the shape `epicrun` produces — would both read "nothing else is running" and both take
 	// the whole machine. Claimed here, after the count and before any check, it is already there when
 	// the next lane asks; the guard inside the spawned `josh test:unit` sees the handoff and adds no
-	// second marker for the same run (joshuafolkken/kit#1515).
+	// second marker for the same run.
 	async function run_and_settle(): Promise<number> {
 		const results = await run_gate_steps(plan, budget)
 
-		return await settle_gate(plan, results, tree, { ...options, started_at })
+		return await settle_gate(plan, results, tree, { ...options, started_at, ledger })
 	}
 
 	return await run_marked_gate(tree.files, plan, run_and_settle, options.marker_path)
@@ -410,8 +418,7 @@ function reusable_stamp(tree: GateTree, options: GateOptions): FileMapStamp | un
 
 // The two ways a gate ends before it runs a check: a green record it can reuse (exit 0), and the
 // scoped pre-check refusing a tree the pair has not been green on (exit 1). `undefined` means neither
-// fired and the checks run. **Nothing else stands between the skip and the checks** (joshuafolkken/kit#1486):
-// joshuafolkken/kit#1437's `package.json` refusal was removed once children stopped bumping.
+// fired and the checks run. **Nothing else stands between the skip and the checks.**
 function short_circuit_gate(tree: GateTree, options: GateOptions): number | undefined {
 	const reusable = reusable_stamp(tree, options)
 

package/scripts/gh/gh-spawn.ts

@@ -6,7 +6,7 @@ import { git_gh_exec } from './git-gh-exec'
 // synchronously because `josh init` / `josh sync` / `josh doctor` decide before they can await.
 // It asks REST for the same reason — `gh repo view` goes through GraphQL, which a cloud session is
 // refused (403), and a repository that reads as unresolved makes `init` / `sync` skip
-// `sonar-project.properties` outright (joshuafolkken/kit#1023). The path comes from the shared
+// `sonar-project.properties` outright. The path comes from the shared
 // builder rather than being spelled out again here.
 //
 // An unbounded lookup asks for `NO_BUDGET`, execa's own "no timeout": the shared layer otherwise
@@ -29,7 +29,7 @@ function fetch_repo_name(timeout_ms: number | undefined): string | undefined {
 // The unbounded lookup, for callers whose *writes* depend on the answer. A timeout would surface as
 // an unresolved repository, and `josh init` / `josh sync` react to that by skipping
 // `sonar-project.properties` entirely — so a latency spike would silently leave a consumer's Sonar
-// config stale. Waiting is the safer failure mode there (joshuafolkken/kit#805).
+// config stale. Waiting is the safer failure mode there.
 function get_repo_name_with_owner(): string | undefined {
 	return fetch_repo_name(undefined)
 }

package/scripts/gh/git-ai-review-scan.ts

@@ -111,8 +111,9 @@ function classify_claude_comment(comment: ReviewComment): ClassifiedFinding {
 	}
 }
 
-// Temporary (kit#753): CodeRabbit actionable comments are informational, never blockers, so a
-// slow CodeRabbit review cannot stall the merge gate. Revert together with kit#752.
+// Temporary: CodeRabbit actionable comments are informational, never blockers, so a
+// slow CodeRabbit review cannot stall the merge gate. Revert together with the rest of the
+// temporary CodeRabbit non-blocking policy.
 function build_coderabbit_info(comment: ReviewComment, count: number): ClassifiedFinding {
 	return {
 		author_login: comment.author_login,

package/scripts/gh/git-gh-api-path.ts

@@ -4,11 +4,11 @@
 // decision was already being spelled out per call site — in `git-gh-issue-read.ts`, and as a bare
 // string concatenation in `git-gh-pr.ts` and `epic-cross-repo.ts`. All three now build their paths
 // from here. Converting kit's GitHub calls to REST multiplies those call sites, so the decision is
-// made once rather than at each one (joshuafolkken/kit#1023).
+// made once rather than at each one.
 
 // One full page of a listing. REST answers 30 rows by default, and every listing this tooling reads
 // is paged through with `--paginate`, so asking for the largest page turns a long listing into fewer
-// round trips. Named once because three readers append it (joshuafolkken/kit#1028).
+// round trips. Named once because three readers append it.
 const FULL_PAGE_QUERY = '?per_page=100'
 
 // `gh api` expands `{owner}` and `{repo}` from the current repository, so the unqualified form needs
@@ -19,7 +19,7 @@ function repo_api_path(repo = '{owner}/{repo}'): string {
 }
 
 // The issue collection — what a listing pages through and what a creation posts to. One segment,
-// named once: the reads, the listing and the writes all build on it (joshuafolkken/kit#1026).
+// named once: the reads, the listing and the writes all build on it.
 function issues_api_path(repo?: string): string {
 	return `${repo_api_path(repo)}/issues`
 }
@@ -30,15 +30,14 @@ function issue_api_path(issue_number: string, repo?: string): string {
 
 // The dependency relations, which REST serves from their own endpoint rather than inside the issue.
 // Named here because three call sites address it — the read in `git-gh-issue-read.ts` and both
-// writes in `git-gh-issue-write.ts` (joshuafolkken/kit#1026).
+// writes in `git-gh-issue-write.ts`.
 function blocked_by_api_path(issue_number: string, repo?: string): string {
 	return `${issue_api_path(issue_number, repo)}/dependencies/blocked_by`
 }
 
 // A pull request's *conversation* comments. REST serves them from the issue endpoint rather than the
 // pull one — `pulls/{N}/comments` is the review thread, which is a different listing with a
-// different shape, and reading one where the other was meant is a silent mistake rather than a 404
-// (joshuafolkken/kit#1027).
+// different shape, and reading one where the other was meant is a silent mistake rather than a 404.
 function issue_comments_api_path(issue_number: string, repo?: string): string {
 	return `${issue_api_path(issue_number, repo)}/comments`
 }
@@ -49,14 +48,14 @@ function pulls_api_path(repo?: string): string {
 }
 
 // One pull request, addressed by number. `gh pr view` accepted a branch name and REST does not, so
-// every read below the branch lookup names the number instead (joshuafolkken/kit#1027).
+// every read below the branch lookup names the number instead.
 function pull_api_path(pr_number: string, repo?: string): string {
 	return `${pulls_api_path(repo)}/${pr_number}`
 }
 
 // The merge of one pull request. `gh pr merge <branch> --merge` is the GraphQL call this replaces,
 // and the method it named is sent as the `merge_method` field of the request body rather than being
-// left to the endpoint's default (joshuafolkken/kit#1029).
+// left to the endpoint's default.
 function pull_merge_api_path(pr_number: string, repo?: string): string {
 	return `${pull_api_path(pr_number, repo)}/merge`
 }
@@ -68,7 +67,7 @@ function pull_comments_api_path(pr_number: string, repo?: string): string {
 }
 
 // The review history of one pull request. There is no REST counterpart to GraphQL's
-// `reviewDecision`, so the merge gate folds this listing into one instead (joshuafolkken/kit#1028).
+// `reviewDecision`, so the merge gate folds this listing into one instead.
 function pull_reviews_api_path(pr_number: string, repo?: string): string {
 	return `${pull_api_path(pr_number, repo)}/reviews`
 }
@@ -92,13 +91,13 @@ function commit_status_api_path(commit_sha: string, repo?: string): string {
 }
 
 // A single tag reference. REST answers 404 when the tag does not exist, which is the whole of the
-// question the release command's tag watch asks (joshuafolkken/kit#1169).
+// question the release command's tag watch asks.
 function tag_reference_api_path(tag: string, repo?: string): string {
 	return `${repo_api_path(repo)}/git/ref/tags/${tag}`
 }
 
 // The GitHub Release published for one tag. REST answers 404 until `publish.yml`'s `create-release`
-// job has run, which is what the release command's progress watch asks (joshuafolkken/kit#3193).
+// job has run, which is what the release command's progress watch asks.
 function release_by_tag_api_path(tag: string, repo?: string): string {
 	return `${repo_api_path(repo)}/releases/tags/${tag}`
 }

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

@@ -7,10 +7,10 @@ import { gh_failure } from './git-gh-failure'
 
 const BODY_FROM_STDIN = '-'
 
-// The budget for **one** request through this layer, and the reason nothing here waits forever
-// (joshuafolkken/kit#1065). Every GitHub access kit makes funnels through the four entries below, so
-// until this existed a single hung `gh` held the caller open with no upper bound — most visibly in
-// `josh propagate`, whose runner is single-threaded and processed no further consumer at all.
+// The budget for **one** request through this layer, and the reason nothing here waits forever.
+// Every GitHub access kit makes funnels through the four entries below, so without it a single hung
+// `gh` would hold the caller open with no upper bound — most visibly in `josh propagate`, whose
+// runner is single-threaded and would process no further consumer at all.
 //
 // **It is a request's budget, not a step's.** `STEP_TIMEOUT_MS` (30 minutes, `propagate-steps.ts`)
 // covers a consumer's whole unit suite and a `pnpm add`; one REST call has no business borrowing
@@ -33,7 +33,7 @@ const BODY_FROM_STDIN = '-'
 //
 // **What a timed-out read costs its caller is decided by that caller, and two are worth naming.**
 // In the merge gate's poll loop (`wait_for_pr_success`) it is one unreadable poll: the loop retries
-// on its next interval and gives up on the third consecutive failure (joshuafolkken/kit#1077), so a
+// on its next interval and gives up on the third consecutive failure, so a
 // timeout, a 403, a rate limit and a dropped connection all end the wait loudly rather than hanging
 // or reading as a verdict, and re-running `followup` resumes it. In `followup`'s look-ahead it costs
 // a log line: `handle_watch_failure` absorbs the error and falls through to the polling.
@@ -59,22 +59,22 @@ function to_timeout_option(timeout_ms?: number): { timeout: number } {
 	return { timeout: timeout_ms ?? GH_REQUEST_TIMEOUT_MS }
 }
 
-// **`gh` dials GitHub directly, never through a proxy this machine stood up on loopback**
-// (joshuafolkken/kit#2436). A package-manager wrapper writes one into the environment of everything
+// **`gh` dials GitHub directly, never through a proxy this machine stood up on loopback**.
+// A package-manager wrapper writes one into the environment of everything
 // its invocation spawns, and it exists to inspect package downloads — api.github.com crosses it
-// without inspection, so the hop buys nothing and can fail on its own: measured on
-// joshuafolkken/kit#2422, one 30-second stall made the wrapper refuse every later GitHub connection
-// of that `followup`, and the retries in the poll loop could only ever fail. The loopback test and
-// the list of spellings are the agent-session launcher's (joshuafolkken/kit#1760), shared rather than
+// without inspection, so the hop buys nothing and can fail on its own: one 30-second stall makes the
+// wrapper refuse every later GitHub connection of that `followup`, and the retries in the poll loop
+// can then only ever fail. The loopback test and
+// the list of spellings are the agent-session launcher's, shared rather than
 // restated. Only the scanner's proxy goes — recognized by its CA — because any other loopback proxy
 // may be this machine's only route out; a proxy naming a real host is somebody's network and stays.
 // 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 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.
+// step (`start-exec.ts`). Every `gh api` request goes through the entries below, 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>
 }
@@ -92,7 +92,7 @@ interface SpawnOptions extends DirectEnvironment {
 
 // `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.
+// the process's own directory.
 function to_spawn_options(timeout_ms?: number, cwd?: string): SpawnOptions {
 	return {
 		...to_timeout_option(timeout_ms),
@@ -103,10 +103,10 @@ function to_spawn_options(timeout_ms?: number, cwd?: string): SpawnOptions {
 
 // What a request that ran out of time is labelled with, ahead of whatever gh managed to write.
 //
-// The distinction is joshuafolkken/kit#1048's, on a new failure: "the server said no" and "nobody
-// ever got an answer" are different diagnoses, and a timeout is the second. execa names it on the
-// error it throws, and without the prefix a hang that had written a line to stderr first would
-// arrive as that line — reported as whatever it happened to say instead of as a timeout.
+// "The server said no" and "nobody ever got an answer" are different diagnoses, and a timeout is
+// the second. execa names it on the error it throws, and without the prefix a hang that had written
+// a line to stderr first would arrive as that line — reported as whatever it happened to say
+// instead of as a timeout.
 const GH_REQUEST_TIMEOUT_MESSAGE = 'gh request timed out'
 
 function has_stderr_field(error: unknown): error is Error & { stderr: string } {
@@ -120,26 +120,24 @@ function has_stdout_field(error: unknown): error is Error & { stdout: string } {
 }
 
 // `has_timed_out` is shared with the push transport rather than restated here: execa marks a spawn
-// it killed the same way whichever binary was spawned, and `git push` gained a budget of its own in
-// joshuafolkken/kit#1251.
+// it killed the same way whichever binary was spawned, and `git push` has a budget of its own.
 function to_timeout_prefix(error: unknown): string {
 	return has_timed_out(error) ? `${GH_REQUEST_TIMEOUT_MESSAGE}: ` : ''
 }
 
-// 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**.
+// Surface the gh CLI's stderr as the thrown message when present, otherwise fall back to execa's
+// own message — **and append what gh wrote to stdout**.
 //
 // The append is not cosmetic. `gh api` splits a failed request across both streams: stderr carries
 // one summary line (`gh: Validation Failed (HTTP 422)`) and **stdout carries the JSON error body**,
-// which is the only place the reason is written. Every caller here is now a REST request, so
-// dropping stdout dropped the diagnosis from every REST failure — and `handle_pr_create_error`
-// reads the reason: a duplicate pull request is `A pull request already exists for <owner>:<branch>.`
-// inside that body, and matching it against stderr alone answers no (measured on
-// joshuafolkken/kit#1029).
+// which is the only place the reason is written. Every caller here is a REST request, so dropping
+// stdout would drop the diagnosis from every REST failure — and `handle_pr_create_error` reads the
+// reason: a duplicate pull request is `A pull request already exists for <owner>:<branch>.` inside
+// that body, and matching it against stderr alone answers no.
 //
 // The same stdout is what carries the request's own failure nature, so the classification is
 // attached here rather than reconstructed by a later probe: GitHub's error document names its status
-// and a request that never arrived wrote no document at all (joshuafolkken/kit#1690).
+// and a request that never arrived wrote no document at all.
 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() : ''
@@ -210,24 +208,22 @@ function status_of_failure(error: unknown): number | 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,
-// 429, 5xx) is matching a contract instead of a string (joshuafolkken/kit#957).
+// 429, 5xx) is matching a contract instead of a string.
 //
 // `--silent` drops the response body, so only the headers are parsed; `--include` keeps them even
 // when the request failed, and execa carries that output on the error it throws. `undefined` means
 // no status was reached at all — gh missing, a dropped connection — which is itself a failed read.
 //
-// **The fifth spawn in this file, and guarded like the other four** (joshuafolkken/kit#1065). It is
-// not one of the entries joshuafolkken/kit#1065 enumerated, and that is exactly why it is included:
-// leaving one unbounded `gh` spawn beside four bounded ones is the inconsistency that Issue argues
-// against, in the same file. Its contract is unchanged — a timeout reaches the `catch` and answers
-// `undefined`, which already means "no status was reached", which its one caller already reads as a
-// failed read rather than as a 404.
+// **The fifth spawn in this file, and guarded like the other four**: leaving one unbounded `gh`
+// spawn beside four bounded ones would be an inconsistency in the same file. A timeout reaches the
+// `catch` and answers `undefined`, which already means "no status was reached", which its one
+// caller already reads as a failed read rather than as a 404.
 async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<number | undefined> {
 	// Hoisted so the spawn below fits on one line, which `// NOSONAR` requires — it suppresses only
 	// the line it sits on. The **argument list** stays an inline literal for the opposite reason:
 	// `gh-subcommand-guard.ts` resolves the subcommand from it, and hoisting that into a `const`
 	// makes the scan report `<dynamic>` instead of `api`, leaving a future edit to
-	// `['issue', 'view', …]` uncaught (joshuafolkken/kit#1063).
+	// `['issue', 'view', …]` uncaught.
 	const options = to_spawn_options(timeout_ms)
 
 	try {
@@ -241,7 +237,7 @@ async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<nu
 }
 
 // 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
+// synchronous all the way up to `epic_classify`. 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.
@@ -280,7 +276,7 @@ const JQ_FLAG = '--jq'
 // this field exists for: `--paginate` alone emits one document per page, so a two-page response
 // arrives as `{…}{…}`, which `JSON.parse` rejects, and `--slurp` wraps those pages in one outer
 // array instead. It is a separate field rather than implied by `should_paginate` for that reason,
-// and because gh refuses it alongside `--jq` (joshuafolkken/kit#1027).
+// and because gh refuses it alongside `--jq`.
 interface GhApiRequest {
 	path: string
 	method?: string
@@ -289,9 +285,9 @@ 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). `0` is
+	// second argument for the reason recorded beside that constant. `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).
+	// (`gh-spawn.ts`).
 	timeout_ms?: number
 	// The checkout gh runs in, which is what `{owner}/{repo}` in `path` resolves against. Absent means
 	// the process's own directory.
@@ -319,8 +315,8 @@ 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). A caller that cannot await uses `exec_gh_api_sync` or
+// through it, so the verb, the body and the paging stop being spelled out per call site.
+// 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
@@ -344,12 +340,11 @@ async function exec_gh_api(request: GhApiRequest): Promise<string> {
 // consumer's steps as a sequential chain of `execaSync` spawns with inherited stdio, and that shape
 // reaches from `open_issue` up through `RunStep`, `run_target` and `run_targets` — so the issue it
 // opens in the consumer is created here rather than by turning the whole runner asynchronous for
-// one request (joshuafolkken/kit#1042).
+// one request.
 //
-// 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 serves the write side and the synchronous readers alike — `gh-spawn.ts`, `epic-cross-repo.ts`,
+// `repo-setting.ts`, `propagate-publish.ts`, `version-remote.ts` go through it 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