@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/gate/core-budget.ts

@@ -6,6 +6,7 @@ import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { z } from 'zod'
 
 // A machine-wide weighted core budget with admission control (joshuafolkken/kit#2351).
@@ -46,6 +47,26 @@ const WAIT_CAP_MS = 120_000
 // The head of the ledger is always admitted, so the smallest budget worth planning against is one core.
 const MIN_BUDGET = 1
 
+// **The cores each heavy tool occupies, declared once for both places that reserve them**
+// (joshuafolkken/kit#3345). `gate-plan.ts`'s checks and the `josh` commands that run the same tools
+// directly read these, so a direct `josh lint` claims what the gate's lint claims. The lint, type check
+// and spell check numbers are `gate-plan.ts`'s measured table, floored. The whole-tree eslint scan
+// behind `josh lines` and `josh refactor:scan` runs in one process: measured cold on the 11-core
+// machine on 2026-10-06, 113s of CPU over 98s of wall, so it gets one core.
+const CORE_WEIGHTS = {
+	lint: 2,
+	type_check: 1,
+	spell_check: 1,
+	eslint_scan: 1,
+} as const
+
+// **The environment mark that says a parent already holds this process's cores**
+// (joshuafolkken/kit#3345). `josh gate` reserves per check and then spawns `pnpm josh lint`. Without
+// the mark, that child's own dispatch would claim a second place for the cores its parent already
+// holds. Every holder sets it, and every child inherits it through the environment and claims nothing.
+const HELD_KEY = 'JOSH_CORE_RESERVED'
+const HELD_VALUE = '1'
+
 const reservation_schema = process_owner_schema.extend({
 	weight: z.number(),
 	claimed_at: z.number(),
@@ -133,7 +154,7 @@ function live_reservations(directory: string = PLATFORM_TEMP_ROOT): Array<LiveRe
 	return marker_files(directory).flatMap((name) => {
 		const reservation = live_reservation(path.join(directory, name))
 
-		return reservation === undefined ? [] : [{ key: name, reservation }]
+		return reservation === undefined ? [] : { key: name, reservation }
 	})
 }
 
@@ -272,14 +293,61 @@ async function with_core_reservation<T>(
 	}
 }
 
+function is_held(): boolean {
+	return process.env[HELD_KEY] === HELD_VALUE
+}
+
+// A function of its own so the restoring write does not sit after an `await`, where
+// `require-atomic-updates` reads any write to `process` as a possible race — the reason `josh.ts`
+// gives `record_exit_code`.
+function set_held_mark(value: string): void {
+	process.env[HELD_KEY] = value
+}
+
+// Marks this process, and every child it spawns, as running inside a held reservation. The previous
+// value comes back afterwards, so a nested holder never clears the mark its outer holder set.
+async function with_held_mark<T>(run: () => Promise<T>): Promise<T> {
+	const previous = process.env[HELD_KEY] ?? ''
+
+	set_held_mark(HELD_VALUE)
+
+	try {
+		return await run()
+	} finally {
+		set_held_mark(previous)
+	}
+}
+
+// **A command's reservation: the gate's claim, unless a parent already holds the cores**
+// (joshuafolkken/kit#3345). `josh-logic.ts` calls this around every command that declares a weight.
+// Each command then only declares its weight, and no command carries a copy of the claim, run and
+// release steps. A solo run is admitted on the first read, so a run with room on the machine starts
+// with no wait. A command inside a unit suite claims nothing either, for the reason `reserved-run.ts`
+// gives: the suite's own reservation already covers it, and a place claimed there would wait on it.
+async function with_command_reservation<T>(
+	weight: number,
+	run: () => Promise<T>,
+	options: ReserveOptions = {},
+): Promise<T> {
+	if (is_held() || unit_worker_share.is_nested_run()) return await run()
+
+	return await with_core_reservation(weight, async () => await with_held_mark(run), options)
+}
+
 const core_budget = {
+	CORE_WEIGHTS,
+	HELD_KEY,
+	HELD_VALUE,
 	RESERVED_PREFIX,
 	admitted_keys,
 	admitted_load,
+	is_held,
 	live_reservations,
 	release,
 	reserve,
+	with_command_reservation,
 	with_core_reservation,
+	with_held_mark,
 }
 
 export type { LiveReservation, Reservation, ReserveOptions }

package/scripts/gate/gate-plan.ts

@@ -1,6 +1,7 @@
 import { availableParallelism } from 'node:os'
 import { josh_verdict } from '#scripts/josh/josh-verdict'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
+import { core_budget } from './core-budget'
 
 // How many of the gate's checks run at once, and how wide the one elastic check may fan out —
 // both derived from the machine rather than fixed at four (joshuafolkken/kit#1258).
@@ -61,15 +62,30 @@ const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LA
 // check rather than one appended after the unit suite is what keeps the plan's shape intact: the
 // `--no-unit` set stays "the whole gate minus the unit suite", and a CI runner — which has no recorded
 // transcripts — runs it as a trivial green rather than skipping it.
+//
+// **The three reserving weights are `core_budget.CORE_WEIGHTS`** (joshuafolkken/kit#3345), the same
+// numbers the `josh lint`, `josh check` and `josh cspell:dot` commands claim when run directly.
+//
+// **The two zero weights were measured again for joshuafolkken/kit#3345, and they stay zero.** These are
+// warm runs on the 11-core machine on 2026-10-06. `behavior` took 0.6s of wall for 0.7s of CPU, which
+// is node starting up. `exports:unused` took 5.5s of wall for 9.0s of CPU, about 1.6 cores. Floored,
+// that would be one core, but a reservation lasts the whole gate's plan, not the check's five seconds.
+// It would lower `RESERVED_CORES` from 4 to 5 and cut the solo unit cap from 7 workers to 6 for the
+// full length of the unit suite, to cover a burst that ends before lint does. Nothing has measured
+// that trade, so the measured shape stays.
 const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
-	{ label: LINT_LABEL, target: 'lint', reserved_cores: 2 },
-	{ label: TYPE_CHECK_LABEL, target: 'check', reserved_cores: 1 },
-	{ label: 'cspell', target: 'cspell:dot', reserved_cores: 1 },
+	{ label: LINT_LABEL, target: 'lint', reserved_cores: core_budget.CORE_WEIGHTS.lint },
+	{
+		label: TYPE_CHECK_LABEL,
+		target: 'check',
+		reserved_cores: core_budget.CORE_WEIGHTS.type_check,
+	},
+	{ label: 'cspell', target: 'cspell:dot', reserved_cores: core_budget.CORE_WEIGHTS.spell_check },
 	{ label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
 	// **The unused-member check reserves no core** (joshuafolkken/kit#2987): it builds one TypeScript
-	// program and walks it single-threaded for about 5s — over well before lint and the type check, so
-	// a reservation would only take a place from the four-core CI runner's fan-out and a worker from
-	// the unit suite for the whole gate.
+	// program and walks it for about 5s, and it is over well before lint and the type check. A
+	// reservation would only take a place from the four-core CI runner's fan-out and a worker from the
+	// unit suite for the whole gate.
 	{ label: 'exports', target: 'exports:unused', reserved_cores: 0 },
 ]
 
@@ -242,6 +258,11 @@ function resolve_unit_worker_cap(
 	return available_cores - RESERVED_CORES
 }
 
+// The unit suite's weight when nothing caps its pool: the cores left once the static checks have theirs.
+function solo_unit_weight(available_cores: number): number {
+	return Math.max(0, available_cores - RESERVED_CORES)
+}
+
 // The cores a check reserves from the machine-wide budget while it runs (joshuafolkken/kit#2351). The
 // static checks declare their measured reservation; the unit suite declares the pool it will open,
 // which `unit_worker_cap` has already sized against the runs in flight. **This is the same table, read
@@ -256,7 +277,25 @@ function resolve_unit_worker_cap(
 function check_weight(check: GateCheck, plan: GatePlan, available_cores: number): number {
 	if (check.label !== UNIT_LABEL) return check.reserved_cores
 
-	return plan.unit_worker_cap ?? Math.max(0, available_cores - RESERVED_CORES)
+	return plan.unit_worker_cap ?? solo_unit_weight(available_cores)
+}
+
+// The cores a unit run started directly reserves (joshuafolkken/kit#3345): the share it will pass to
+// vitest while other runs are live, and otherwise the gate's own solo unit weight. **Not the whole
+// machine**, though a lone vitest sizes its own pool: FIFO admission lets a claim of every core in only
+// once the ledger is empty, so a one-file `josh test:related` would wait out every other lane's gate
+// and hold every later claim behind it. One weight for the suite however it is started. **Floored at one
+// worker**: on a machine the static checks fill, a four-core CI runner among them, the gate's solo
+// weight is zero because its siblings hold every core — a direct run has no siblings, and vitest still
+// occupies a core.
+function direct_unit_weight(
+	available_cores: number = availableParallelism(),
+	live_runs: number = unit_worker_share.live_run_count(),
+): number {
+	const weight =
+		unit_worker_share.current_share(available_cores, live_runs) ?? solo_unit_weight(available_cores)
+
+	return Math.max(unit_worker_share.MIN_WORKERS, weight)
 }
 
 // `availableParallelism()` rather than `cpus().length`: it reports what this process may actually
@@ -345,6 +384,7 @@ const gate_plan = {
 	UNIT_LABEL,
 	WARNING_CHECKER_LABELS,
 	check_weight,
+	direct_unit_weight,
 	format_gate_plan,
 	format_machine,
 	has_unit_check,

package/scripts/gate/gate-skip.ts

@@ -60,18 +60,42 @@ const FORCE_FLAG = '--force'
 //
 // A `base` that could not be read is `undefined`, and an older record carries none: both compare
 // unequal to anything, so the gate runs its checks. No base means no reuse, never reuse without one.
-function reusable_green_gate(
+//
+// **A refusal carries its reason** (joshuafolkken/kit#3307): a pre-push hook that fell back to the
+// whole unit suite said nothing about why, so a merge base moved by ship's main sync and a lock file
+// rewritten by the hook's own install each cost minutes before anyone could tell them apart.
+type GateReuse = { stamp: FileMapStamp } | { miss: string }
+
+function base_moved(recorded: string | undefined, base: string): string {
+	return `the merge base moved since the green gate (${recorded ?? 'none'} → ${base})`
+}
+
+function gate_reuse(
 	tree: Record<string, string>,
 	base: string | undefined,
 	source?: string,
-): FileMapStamp | undefined {
-	if (base === undefined || Object.keys(tree).length === 0) return undefined
+): GateReuse {
+	if (base === undefined) return { miss: 'the merge base could not be read' }
+	if (Object.keys(tree).length === 0) return { miss: 'no file differs from the merge base' }
 
 	const stamp = review_brief.matching_stamp(review_stamps.gate_stamp.read(source), tree)
 
-	if (stamp?.base !== base) return undefined
+	if (stamp === undefined) return { miss: 'no green gate record matches the changed files' }
+	if (stamp.base !== base) return { miss: base_moved(stamp.base, base) }
+
+	return { stamp }
+}
+
+function stamp_of(reuse: GateReuse): FileMapStamp | undefined {
+	return 'stamp' in reuse ? reuse.stamp : undefined
+}
 
-	return stamp
+function reusable_green_gate(
+	tree: Record<string, string>,
+	base: string | undefined,
+	source?: string,
+): FileMapStamp | undefined {
+	return stamp_of(gate_reuse(tree, base, source))
 }
 
 // **The sentence claims the result, and never merely the omission.** "verification skipped" on its
@@ -116,8 +140,15 @@ function format_skip(taken_at: string): string {
 	})
 }
 
-const gate_skip = { FORCE_FLAG, format_reuse_notice, format_skip, reusable_green_gate }
+const gate_skip = {
+	FORCE_FLAG,
+	format_reuse_notice,
+	format_skip,
+	gate_reuse,
+	reusable_green_gate,
+	stamp_of,
+}
 
-export type { ReuseNotice }
+export type { GateReuse, ReuseNotice }
 
 export { gate_skip }

package/scripts/gate/hook-gate-reuse.ts

@@ -1,7 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
-import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
-import { gate_skip } from './gate-skip'
+import { gate_skip, type GateReuse } from './gate-skip'
 import type { GateTree } from './gate-tree'
 
 // What the two git hooks share when they decline to re-run a check `pnpm josh gate` already passed on
@@ -94,6 +93,8 @@ interface HookReuse {
 	// The hook-specific narrowing: whether what this git operation carries is the tree the record
 	// describes. `is_worktree_clean` for a push, `is_index_matching_worktree` for a commit.
 	is_tree_carried: boolean
+	// The reason a refusal on that narrowing reports, in the hook's own words (joshuafolkken/kit#3307).
+	carry_miss: string
 	extra_arguments: ReadonlyArray<string>
 	force_env: string
 	// The record to read, so a test can plant one without overwriting the record a live run relies on.
@@ -102,27 +103,28 @@ interface HookReuse {
 	source?: string | undefined
 }
 
-// The stamp rather than a boolean, for the same reason `gate_skip.reusable_green_gate` hands one back:
-// the caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
-// printing.
+// The stamp rather than a boolean, for the same reason `gate_skip.gate_reuse` hands one back: the
+// caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
+// printing. A refusal carries its reason instead (joshuafolkken/kit#3307).
 //
 // **Any argument at all refuses the reuse**, not only the force flag. A caller who narrowed the run
 // asked for that run rather than for a recorded result about a whole tree, and a hook's own line passes
 // none, so this costs it nothing.
-function reusable_green_hook(input: HookReuse): FileMapStamp | undefined {
-	if (input.extra_arguments.length > 0 || is_force_requested(input.force_env)) return undefined
-	if (!input.is_tree_carried) return undefined
+function hook_reuse(input: HookReuse): GateReuse {
+	if (input.extra_arguments.length > 0) return { miss: 'arguments were passed to the hook' }
+	if (is_force_requested(input.force_env)) return { miss: `${input.force_env} is set` }
+	if (!input.is_tree_carried) return { miss: input.carry_miss }
 
-	return gate_skip.reusable_green_gate(input.tree.files, input.tree.base, input.source)
+	return gate_skip.gate_reuse(input.tree.files, input.tree.base, input.source)
 }
 
 const hook_gate_reuse = {
 	GATE_REUSING_TARGETS,
+	hook_reuse,
 	is_force_requested,
 	is_index_matching_worktree,
 	is_worktree_clean,
 	read_status_lines,
-	reusable_green_hook,
 }
 
 export type { HookReuse }

package/scripts/gate/pre-commit-type-check.ts

@@ -96,14 +96,17 @@ async function reusable_green_commit(
 	source?: string,
 	start_directory: string = process.cwd(),
 ): Promise<FileMapStamp | undefined> {
-	const reusable = hook_gate_reuse.reusable_green_hook({
+	const reuse = hook_gate_reuse.hook_reuse({
 		tree,
 		is_tree_carried: tree.is_index_matching_worktree,
+		carry_miss: 'the index differs from the working tree',
 		extra_arguments,
 		force_env: FORCE_ENV,
 		source,
 	})
 
+	const reusable = gate_skip.stamp_of(reuse)
+
 	if (reusable === undefined) return undefined
 
 	return (await is_recorded_check_this_check(start_directory)) ? reusable : undefined

package/scripts/gate/project-checks.ts

@@ -2,6 +2,7 @@ import { existsSync, globSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { project_profile } from '#scripts/init/project-profile'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
 import { z } from 'zod'
@@ -43,15 +44,11 @@ const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies']
 const object_schema = z.record(z.string(), z.unknown())
 
 function project_root(directory: string): string {
-	let current = directory
-
-	while (!existsSync(path.join(current, PACKAGE_JSON))) {
-		const parent = path.dirname(current)
-		if (parent === current) return directory
-		current = parent
-	}
-
-	return current
+	return (
+		ancestor_directories.nearest(directory, (candidate) =>
+			existsSync(path.join(candidate, PACKAGE_JSON)),
+		) ?? directory
+	)
 }
 
 function is_ignored(entry: string): boolean {

package/scripts/gate/type-check-step.ts

@@ -1,4 +1,5 @@
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
 // joshuafolkken/kit#934: `josh gate`'s type-check step used to be `tsc --noEmit` for every project.
@@ -28,8 +29,6 @@ const TOOLKIT_BINS: ReadonlyArray<string> = ['josh-app', 'josh-game']
 // a bracketed warning printed first would otherwise be read as the command list.
 const USAGE_COMMANDS_PATTERN = /Usage:[^<>\n]*<([^<>\n]+)>/u
 const COMMAND_SEPARATOR = '|'
-// A toolkit that prints its usage answers in milliseconds; anything slower is hung.
-const USAGE_TIMEOUT_MS = 30_000
 
 function parse_usage_commands(output: string): ReadonlyArray<string> {
 	const group = USAGE_COMMANDS_PATTERN.exec(output)?.[1]
@@ -46,7 +45,7 @@ async function read_toolkit_commands(bin_path: string): Promise<ReadonlyArray<st
 		const result = await execa(bin_path, [], {
 			all: true,
 			reject: false,
-			timeout: USAGE_TIMEOUT_MS,
+			timeout: COMMAND_TIMEOUT_MS,
 		})
 
 		return parse_usage_commands(result.all)

package/scripts/gate/verification-gate.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 import { review_stamps } from '#scripts/review/review-stamps'
@@ -166,7 +167,7 @@ interface BudgetContext {
 function default_budget(): BudgetContext {
 	return {
 		available_cores: availableParallelism(),
-		is_reserved: !unit_worker_share.is_nested_run(),
+		is_reserved: !unit_worker_share.is_nested_run() && !core_budget.is_held(),
 	}
 }
 
@@ -222,10 +223,17 @@ async function run_gate_steps(
 ): Promise<ReadonlyArray<GateStepResult>> {
 	const reserved = await build_reserved_steps(process.cwd(), plan, budget.available_cores)
 
-	return await bounded_pool.bounded_map(
-		reserved,
-		plan.concurrency,
-		async (entry) => await run_reserved_step(entry, budget),
+	// **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
+	// 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(
+		async () =>
+			await bounded_pool.bounded_map(
+				reserved,
+				plan.concurrency,
+				async (entry) => await run_reserved_step(entry, budget),
+			),
 	)
 }
 
@@ -299,6 +307,9 @@ interface GateOptions {
 	// 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
+	// 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**
@@ -339,14 +350,20 @@ async function settle_gate(
 	tree: GateTree,
 	options: GateOptions & { started_at: number },
 ): Promise<number> {
+	const elapsed_ms = performance.now() - options.started_at
 	const failed_labels = gate_report.report_gate_steps(results, {
 		is_verbose: options.is_verbose ?? false,
 		log_path: options.log_path,
-		elapsed_ms: performance.now() - options.started_at,
+		elapsed_ms,
 		step_count: String(plan.checks.length),
 	})
+	const is_passed = failed_labels.length === 0
 
-	if (failed_labels.length > 0) return FAIL_EXIT_CODE
+	if (options.ledger_path !== undefined) {
+		await lane_ledger.record_gate(options.ledger_path, elapsed_ms, is_passed)
+	}
+
+	if (!is_passed) return FAIL_EXIT_CODE
 
 	await record_whole_gate(plan, results, tree, options)
 
@@ -474,7 +491,9 @@ async function run_gate_command(
 // summary, written last, is the first thing lost. Setting the code lets the writes drain and the
 // process end on its own, which it can, since every child has already exited by here.
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX))
+	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX), {
+		ledger_path: await lane_ledger.target(),
+	})
 }
 
 const verification_gate = {

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

@@ -14,8 +14,8 @@ const FULL_PAGE_QUERY = '?per_page=100'
 // `gh api` expands `{owner}` and `{repo}` from the current repository, so the unqualified form needs
 // no extra lookup to name a path. An explicit `repo` names another repository — the form a
 // cross-repository reference takes.
-function repo_api_path(repo?: string): string {
-	return `repos/${repo ?? '{owner}/{repo}'}`
+function repo_api_path(repo = '{owner}/{repo}'): string {
+	return `repos/${repo}`
 }
 
 // The issue collection — what a listing pages through and what a creation posts to. One segment,

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

@@ -1,8 +1,8 @@
+import { blocking_issue_schema } from '#scripts/git/git-schemas'
 import {
 	parse_json_array_or_undefined,
 	parse_json_object_safe,
 } from '#scripts/git/parse-json-array'
-import { blocking_issue_schema } from '#scripts/git/schemas'
 import type { IssueReference } from '#scripts/issue/issue-reference'
 import { z } from 'zod'
 import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
@@ -163,8 +163,8 @@ function empty_blocked_by(): BlockedBy {
 // repository and names a different issue there (joshuafolkken/kit#1126). Undefined when the field is
 // absent or shaped otherwise; the caller then falls back to the repository it is reading in, which is
 // what an unqualified relation has always meant.
-function repo_of_url(repository_url: string | undefined): string | undefined {
-	const match = REPOSITORY_URL.exec(repository_url ?? '')
+function repo_of_url(repository_url: string | undefined = ''): string | undefined {
+	const match = REPOSITORY_URL.exec(repository_url)
 
 	return match?.[REPOSITORY_URL_GROUP]
 }

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

@@ -29,6 +29,7 @@ const DELETE_METHOD = 'DELETE'
 // 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'
+const LABEL_NAMES_FILTER = '.[].name'
 
 const LABELS_SEGMENT = '/labels'
 const COMMENTS_SEGMENT = '/comments'
@@ -182,17 +183,60 @@ async function issue_create_with_label(input: {
 	)
 }
 
+// The outcome of applying one label, with the swallowed failure's gist kept for a caller that has to
+// say why it refused (joshuafolkken/kit#3312).
+type LabelWrite = { is_applied: true } | { is_applied: false; reason: string }
+
+// The issue's label names, read back after a failed write. A read that itself fails answers
+// `undefined`, which the caller treats as "not applied" — the write's own error is the reason then.
+async function read_label_names(issue_number: string): Promise<Array<string> | undefined> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({
+			path: `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`,
+			should_paginate: true,
+			jq_filter: LABEL_NAMES_FILTER,
+		})
+
+		return raw.split('\n').map((name) => name.trim())
+	} catch (error) {
+		error_text.trace_swallowed('git_gh_issue_write.read_label_names', error)
+
+		return undefined
+	}
+}
+
+// **A failed answer is not a failed write.** The POST is idempotent, and a timeout, a non-zero exit
+// after the write or a secondary rate limit can each throw after the label landed — which refused a
+// lane dispatch whose label was in fact applied (joshuafolkken/kit#3312). So a throw is confirmed by
+// reading the labels back, and only a label that is really absent answers `is_applied: false`.
+async function issue_apply_label(issue_number: string, label: string): Promise<LabelWrite> {
+	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
+
+	try {
+		await git_gh_exec.exec_gh_api({ path: labels_path, body: JSON.stringify({ labels: [label] }) })
+
+		return { is_applied: true }
+	} catch (error) {
+		const names = await read_label_names(issue_number)
+
+		if (names?.includes(label) === true) return { is_applied: true }
+		error_text.trace_swallowed('git_gh_issue_write.issue_apply_label', error)
+
+		// The first line is the gist: gh follows it with the response body, which a one-line refusal
+		// does not need.
+		const [gist = ''] = error_text.message_of(error).split('\n', 1)
+
+		return { is_applied: false, reason: gist }
+	}
+}
+
 // Applied after the body edit so a failure leaves an issue with the epic sections and no label,
 // which `epic:check` reports — rather than a labelled issue with nothing to track. The caller checks
 // the return: the label is what the auto-close filters on (joshuafolkken/kit#865).
 async function issue_add_label(issue_number: string, label: string): Promise<boolean> {
-	return await did_write_succeed(
-		async () =>
-			await git_gh_exec.exec_gh_api({
-				path: `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`,
-				body: JSON.stringify({ labels: [label] }),
-			}),
-	)
+	const write = await issue_apply_label(issue_number, label)
+
+	return write.is_applied
 }
 
 // The counterpart to the addition above, for a run taking its own marker back off
@@ -279,6 +323,7 @@ const git_gh_issue_write = {
 	label_ensure,
 	issue_create_request,
 	issue_create_with_label,
+	issue_apply_label,
 	issue_add_label,
 	issue_remove_label,
 	issue_add_blocked_by,
@@ -286,3 +331,4 @@ const git_gh_issue_write = {
 }
 
 export { git_gh_issue_write }
+export type { LabelWrite }

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

@@ -26,8 +26,10 @@ const SUMMARY_FIELDS = 'number,title,labels,createdAt'
 // `SUMMARY_FIELDS` on purpose: a listing carries no `blockedBy`, so the field is answered from each
 // row's own dependencies endpoint, and asking for it on the shared list would put that request
 // behind the next-issues display too — where a refused one becomes a failure with no message at all,
-// since the listing swallows the error (joshuafolkken/kit#996, joshuafolkken/kit#1025).
-const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy`
+// since the listing swallows the error (joshuafolkken/kit#996, joshuafolkken/kit#1025). `body` costs
+// no request — the REST listing row already carries it — and is what the backlog offer reads for
+// the restructures each issue declares (joshuafolkken/kit#3221).
+const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body`
 
 // Every listing below goes through the one REST invocation in `git-gh-issue-list.ts`. It kept the
 // `json_fields` / `limit` contract it had as a `gh issue list` wrapper, so these callers changed
@@ -111,7 +113,7 @@ async function issue_list_by_label(label: string, limit: number): Promise<IssueL
 }
 
 // The same filter with the fields the `auto-ok` pickup needs (joshuafolkken/kit#906): it orders by
-// `createdAt` and re-checks `labels` client-side, so bodies would be fetched and thrown away. A
+// `createdAt`, re-checks `labels` client-side and reads each body for its declared restructures. A
 // label that does not exist in the repository is not an error — the listing comes back empty, which
 // is exactly "nobody has opted anything in".
 // `json_fields` overrides the pickup's list. Its only caller is the probe that runs *after* a failed