@joshuafolkken/kit 1.1005.0 → 1.1035.0

package/scripts/adopt/adopt-toolkits.ts

@@ -32,7 +32,7 @@ function is_toolkit_package(package_name: string): boolean {
 
 // kit is the base tier and every other toolkit distributes files *derived* from kit's, so the two
 // can manage the same path and whichever `sync` ran last decides its contents
-// (`docs/sync.md` → "two distribution tiers"). Ordering is therefore base-first: kit syncs, then the
+// (`docs/maintainers/sync-rationale.md` → "The managed-workflow stamp"). Ordering is therefore base-first: kit syncs, then the
 // toolkits that overlay it. Sorting by name would put kit last and have it overwrite the overlay
 // with the original every single run.
 function toolkit_rank(package_name: string): number {

package/scripts/adopt/adopt.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { refuse_unknown_flags } from '#scripts/lib/cli-flags'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { propagate_run, type TargetResult } from '#scripts/propagate/propagate-run'
 import { propagate_steps, type Release, type ReleasePlan } from '#scripts/propagate/propagate-steps'
 import type { PropagateTarget } from '#scripts/propagate/propagate-targets'
@@ -40,7 +40,7 @@ interface RunOptions {
 
 function parse_options(argv: ReadonlyArray<string>): RunOptions {
 	const options: RunOptions = { is_dry_run: argv.includes(DRY_RUN_FLAG) }
-	const usage = refuse_unknown_flags(argv, KNOWN_FLAGS, 'adopt')
+	const usage = cli_flags.refuse_unknown_flags(argv, KNOWN_FLAGS, 'adopt')
 
 	return usage === undefined ? options : { ...options, usage }
 }

package/scripts/agent/agent-event.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import type { AgentProvider } from './agent-role-profile'
 import { claude_result_event } from './claude-result-event'
@@ -53,14 +54,6 @@ const EMPTY_STATE: AgentEventState = {
 const LAUNCH_HEADER_PREFIX = '=== '
 const LAUNCH_HEADER_MARKER = ' · started by process '
 
-function parse_line(line: string): unknown {
-	try {
-		return JSON.parse(line)
-	} catch {
-		return undefined
-	}
-}
-
 function usable_text(value: unknown): string | undefined {
 	return typeof value === 'string' && value.trim() !== '' ? value : undefined
 }
@@ -149,7 +142,7 @@ function next_state(line: string, state: AgentEventState): AgentEventState {
 	const is_header = line.startsWith(LAUNCH_HEADER_PREFIX) && line.includes(LAUNCH_HEADER_MARKER)
 	if (is_header) return EMPTY_STATE
 
-	return normalized(parse_line(line), state)
+	return normalized(json_value.parse_or_undefined(line), state)
 }
 
 function read(transcript: string): AgentEventState {

package/scripts/agent/agent-exit-record.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { claude_result_event, type ClaudeResultEvent } from './claude-result-event'
 
 // The exit record of a dispatched lane child — the terminal `result` event a `claude -p` session
@@ -12,18 +13,10 @@ import { claude_result_event, type ClaudeResultEvent } from './claude-result-eve
 // over; a transcript with no result event at all reads as `undefined`, which the classifier treats as
 // an unreadable ending rather than guessing one.
 
-function parse_line(line: string): unknown {
-	try {
-		return JSON.parse(line)
-	} catch {
-		return undefined
-	}
-}
-
 function read_exit_record(transcript: string): ClaudeResultEvent | undefined {
 	return transcript
 		.split('\n')
-		.map((line) => claude_result_event.decode(parse_line(line)))
+		.map((line) => claude_result_event.decode(json_value.parse_or_undefined(line)))
 		.findLast((record) => record !== undefined)
 }
 

package/scripts/backlog/backlog-budget-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { path_decision } from '#scripts/josh/path-decision'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { backlog_budget, type BacklogAnswer, type BudgetInput } from './backlog-budget'
 
 // The thin half of `josh backlog:budget` (joshuafolkken/kit#1632): read the loop's state off the
@@ -32,11 +32,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean>>
 // A misspelled flag is refused rather than defaulted, the contract `path_decision.has_unknown_flag`
 // states for the path-decided commands: an invocation nobody can read is never answered.
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 function text_of(value: string | boolean | undefined): string | undefined {

package/scripts/backlog/backlog-drive-cli.ts

@@ -1,13 +1,14 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
 import { lane_launch_cli } from '#scripts/lane/lane-launch-cli'
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
 import { run_carry, type RunCarry } from '#scripts/run/run-carry'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { run_merge_cli } from '#scripts/run/run-merge-cli'
@@ -49,7 +50,7 @@ const LIST_SEPARATOR = ','
 const COUNT_PATTERN = /^\d+$/u
 const ISSUE_PATTERN = /^[1-9]\d*$/u
 const USAGE =
-	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>]'
+	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>] [--stopped <n>]'
 
 const OPTIONS = {
 	active: { type: 'string' },
@@ -59,6 +60,7 @@ const OPTIONS = {
 	max: { type: 'string' },
 	only: { type: 'boolean' },
 	owner: { type: 'string' },
+	stopped: { type: 'string' },
 	window: { type: 'string' },
 } as const
 
@@ -72,16 +74,14 @@ interface DriveContext {
 	window_ms: number | undefined
 	window: string | undefined
 	is_only: boolean
+	// The child whose merge answered `stop` before the hand-back: the resumed run starts already stopping.
+	stopped: string | undefined
 }
 
 type Values = Partial<Record<Exclude<keyof typeof OPTIONS, 'only'>, string>> & { only?: boolean }
 
 function read_values(argv: ReadonlyArray<string>): Values | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 // A comma list of issue numbers; one entry that is not an issue number refuses the whole list.
@@ -110,6 +110,12 @@ function is_valid_window(raw: string | undefined): boolean {
 	return raw === undefined || COUNT_PATTERN.test(raw)
 }
 
+function is_valid_single(values: Values): boolean {
+	const is_valid_stopped = values.stopped === undefined || ISSUE_PATTERN.test(values.stopped)
+
+	return is_valid_stopped && is_valid_window(values.window)
+}
+
 function owner_of(values: Values | undefined): string | undefined {
 	const owner = values?.owner
 
@@ -117,7 +123,7 @@ function owner_of(values: Values | undefined): string | undefined {
 }
 
 function to_context(values: Values, owner: string): DriveContext | undefined {
-	if (!is_valid_window(values.window)) return undefined
+	if (!is_valid_single(values)) return undefined
 
 	const forwarded = forwarded_of(values)
 	const exclude = to_issues(values.exclude)
@@ -136,6 +142,7 @@ function to_context(values: Values, owner: string): DriveContext | undefined {
 		window_ms,
 		window: values.window,
 		is_only: values.only === true,
+		stopped: values.stopped,
 	}
 }
 
@@ -274,6 +281,7 @@ function resume_line(state: DriveState, context: DriveContext): string {
 
 	if (exclude.length > 0) flags.push('--exclude', exclude.join(LIST_SEPARATOR))
 	if (context.window !== undefined) flags.push('--window', context.window)
+	if (state.stopped_by !== undefined) flags.push('--stopped', state.stopped_by)
 
 	return `resume: ${flags.join(' ')}`
 }
@@ -325,7 +333,9 @@ async function drive(context: DriveContext): Promise<number> {
 	const seeded = await seeded_lanes(context)
 
 	if (seeded === undefined) return FAILURE_EXIT_CODE
-	const initial = backlog_drive.initial_state(seeded, context.active ?? new Date().toISOString())
+	const fresh = backlog_drive.initial_state(seeded, context.active ?? new Date().toISOString())
+	const initial =
+		context.stopped === undefined ? fresh : backlog_drive.merge_stopped(context.stopped, fresh)
 	const last = { state: { ...initial, exclude: [...context.exclude] } }
 	const config = { poll_ms: POLL_MS, offer_ms: OFFER_MS, window_ms: context.window_ms }
 	const end = await backlog_drive.run_loop(last.state, config, ports_of(context, seeded, last))
@@ -340,7 +350,7 @@ async function run_safe(context: DriveContext): Promise<number> {
 	try {
 		return await drive(context)
 	} catch (error) {
-		console.info(`error ${error instanceof Error ? error.message : String(error)}`)
+		console.info(`error ${error_text.message_of(error)}`)
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/backlog/backlog-drive.ts

@@ -16,19 +16,22 @@
 // **Everything it touches is a port**, the pattern `run-wake-loop.ts` set, so the sequencing is pinned
 // without a process, a network or a clock.
 
-// The `run:merge` tokens that need the parent: a hand-off, a person's stop, a tripped guard, a foreign
-// owner, an unreadable state. `resumed` is not among them — the same lane is awaited again.
-const HANDOFF_TOKENS: ReadonlySet<string> = new Set([
+const RUN_VERDICT = 'run'
+const STOP_VERDICT = 'stop'
+// The `run:merge` tokens that end the loop at once: a hand-off, a person's stop, the environment down,
+// a foreign owner, an unreadable state. `resumed` is not among them — the same lane is awaited again.
+const IMMEDIATE_TOKENS: ReadonlySet<string> = new Set([
 	'over',
 	'human-review',
-	'stop',
 	'environment',
 	'busy',
 	'retry',
 ])
+// Every token `run:merge` prints first even on a non-zero exit. `stop` — a parked backlog or the failure
+// guard — is the offer's `stop` reached through a merge: the child is collected, nothing more starts,
+// and the children still in flight are collected before the loop ends (joshuafolkken/kit#2881).
+const HANDOFF_TOKENS: ReadonlySet<string> = new Set([...IMMEDIATE_TOKENS, STOP_VERDICT])
 const RESUMED_TOKEN = 'resumed'
-const RUN_VERDICT = 'run'
-const STOP_VERDICT = 'stop'
 const WATCH_VERDICT = 'watch'
 // The verdicts the loop acts on without the parent. Any other is handed back as it was printed.
 const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
@@ -63,6 +66,8 @@ interface DriveState {
 	is_stopping: boolean
 	stop_reason?: string | undefined
 	stop_is_finish?: boolean | undefined
+	// The child whose merge answered `stop`, carried on the resume line: no offer re-derives that stop.
+	stopped_by?: string | undefined
 }
 
 interface DriveEnd {
@@ -133,22 +138,43 @@ function initial_state(in_flight: ReadonlyArray<string>, active: string): DriveS
 	}
 }
 
-// One finished child: collected, excluded, and — unless its cut was resumed in place — out of flight.
+// The stop a merge reached: kept as the first stop's reason when an offer already stopped the run.
+function merge_stopped(issue: string, state: DriveState): DriveState {
+	if (state.is_stopping) return state
+
+	return {
+		...state,
+		is_stopping: true,
+		stop_reason: `run:merge #${issue} answered stop`,
+		stopped_by: issue,
+	}
+}
+
+// The child collected and excluded, and — unless its cut was resumed in place — out of flight.
+function collected_state(
+	issue: string,
+	token: string,
+	state: DriveState,
+	active: string,
+): DriveState {
+	const in_flight =
+		token === RESUMED_TOKEN ? state.in_flight : state.in_flight.filter((item) => item !== issue)
+	const exclude = state.exclude.includes(issue) ? state.exclude : [...state.exclude, issue]
+
+	return { ...state, in_flight, exclude, active }
+}
+
+// One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const token = await ports.merge(issue)
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
 	if (token === '') return ended('merge', state, undefined, issue)
-	if (HANDOFF_TOKENS.has(token)) return ended('merge', state, token, issue)
+	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
-	const in_flight =
-		token === RESUMED_TOKEN ? state.in_flight : state.in_flight.filter((item) => item !== issue)
-	const exclude = state.exclude.includes(issue) ? state.exclude : [...state.exclude, issue]
+	const next = collected_state(issue, token, state, ports.now().toISOString())
 
-	return {
-		kind: 'continue',
-		state: { ...state, in_flight, exclude, active: ports.now().toISOString() },
-	}
+	return { kind: 'continue', state: token === STOP_VERDICT ? merge_stopped(issue, next) : next }
 }
 
 async function collect_finished(state: DriveState, ports: DrivePorts): Promise<PassResult> {
@@ -320,7 +346,15 @@ async function run_loop(
 	return step.end
 }
 
-const backlog_drive = { HANDOFF_TOKENS, collect, initial_state, on_verdict, run_loop, run_pass }
+const backlog_drive = {
+	HANDOFF_TOKENS,
+	collect,
+	initial_state,
+	merge_stopped,
+	on_verdict,
+	run_loop,
+	run_pass,
+}
 
 export type { DriveEnd, DrivePorts, DriveState, LoopConfig, LoopPorts, OfferRead, PassResult }
 export { backlog_drive }

package/scripts/backlog/backlog-offer-cli.ts

@@ -2,7 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { josh_command } from '#scripts/josh/josh-run'
-import { rule_value_cli } from '#scripts/rules/rule-value-cli'
+import { rule_value_cache } from '#scripts/rules/rule-value-cache'
 import { run_event_stream } from '#scripts/run/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { z } from 'zod'
@@ -242,11 +242,12 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	if (values === undefined) return refuse()
 
-	// The loop head is the one place `rule:value` is called from: once per iteration, the parent's
+	// The loop head is the one place `rule:value` is read from: once per iteration, the parent's
 	// context still small, so a rule that never fires shows up as a printed row rather than as
-	// something a person has to remember to measure (joshuafolkken/kit#2271). It reports to stderr and
-	// never fails, so a broken reading never stops the backlog.
-	rule_value_cli.emit()
+	// something a person has to remember to measure (joshuafolkken/kit#2271). It prints the cached
+	// reading and refreshes it in a detached process, so the offer never waits on the measurement
+	// (joshuafolkken/kit#2881), and it never fails, so a broken reading never stops the backlog.
+	rule_value_cache.emit()
 
 	const counts = counts_of(values)
 

package/scripts/backlog/backlog-plan.ts

@@ -1,8 +1,8 @@
 import type { EpicChild } from '#scripts/epic/epic-graph'
+import type { IssueReference } from '#scripts/epic/epic-reference'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo } from '#scripts/epic/epic-solo'
 import { epic_triage } from '#scripts/epic/epic-triage'
-import type { IssueReference } from '#scripts/git/git-epic-reference'
 import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 

package/scripts/build/build-bin.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { build } from 'esbuild'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
@@ -26,7 +27,7 @@ async function main(): Promise<void> {
 		await build_bin()
 		console.info(`  ✔ ${OUTFILE} built`)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/build/build-config-merge.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { build_library, library_paths } from './build-library'
 
 const CONFIG_MERGE_LIBRARY = 'config-merge'
@@ -16,7 +17,7 @@ async function main(): Promise<void> {
 		console.info(`  ✔ ${CONFIG_MERGE_OUTFILE} built`)
 		console.info(`  ✔ ${CONFIG_MERGE_DTS_FILE} built`)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/build/build-hooks.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env tsx
+import { readdirSync, rmSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { build } from 'esbuild'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
@@ -50,17 +52,35 @@ function outfile_for(bundle: HookBundle): string {
 	return path.join(OUT_DIR, `${bundle.out}.js`)
 }
 
-async function build_hooks(): Promise<void> {
-	await build({
+// The output directory is flat (every entry and chunk sits at its top level), so a file whose name
+// this build did not emit is a leftover of an earlier one.
+function prune_stale_outputs(out_directory: string, outputs: ReadonlyArray<string>): void {
+	const live = new Set(outputs.map((output) => path.basename(output)))
+
+	for (const name of readdirSync(out_directory)) {
+		if (!live.has(name)) rmSync(path.join(out_directory, name), { recursive: true, force: true })
+	}
+}
+
+// With `splitting: true` every build emits freshly hashed `chunk-*.js` files, so without a cleanup
+// the chunks of every earlier build pile up beside the live ones and ship in any local pack
+// (joshuafolkken/kit#2885). The cleanup runs after the build rather than emptying the directory
+// first: this checkout's own settings.json launches `node dist/hooks/<name>.js` on every tool call,
+// and an emptied directory would make a hook launched mid-build fail to load and its guard fail open.
+async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
+	const { metafile } = await build({
 		entryPoints: HOOK_BUNDLES.map((bundle) => entry_point(bundle)),
-		outdir: OUT_DIR,
+		outdir: out_directory,
 		bundle: true,
 		splitting: true,
 		platform: 'node',
 		format: 'esm',
 		target: 'node22',
 		packages: 'external',
+		metafile: true,
 	})
+
+	prune_stale_outputs(out_directory, Object.keys(metafile.outputs))
 }
 
 async function main(): Promise<void> {
@@ -68,7 +88,7 @@ async function main(): Promise<void> {
 		await build_hooks()
 		for (const bundle of HOOK_BUNDLES) console.info(`  ✔ ${outfile_for(bundle)} built`)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/build/build-managed-marker.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { build_library, library_paths } from './build-library'
 
 const MANAGED_MARKER_LIBRARY = 'managed-marker'
@@ -16,7 +17,7 @@ async function main(): Promise<void> {
 		console.info(`  ✔ ${MANAGED_MARKER_OUTFILE} built`)
 		console.info(`  ✔ ${MANAGED_MARKER_DTS_FILE} built`)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/build/build-self-sync-guard.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { build_library, library_paths } from './build-library'
 
 const SELF_SYNC_GUARD_LIBRARY = 'self-sync-guard'
@@ -16,7 +17,7 @@ async function main(): Promise<void> {
 		console.info(`  ✔ ${SELF_SYNC_GUARD_OUTFILE} built`)
 		console.info(`  ✔ ${SELF_SYNC_GUARD_DTS_FILE} built`)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/build/build-version.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { build_library, library_paths } from './build-library'
 
 const VERSION_LIBRARY = 'version'
@@ -15,7 +16,7 @@ async function main(): Promise<void> {
 		console.info(`  ✔ ${VERSION_OUTFILE} built`)
 		console.info(`  ✔ ${VERSION_DTS_FILE} built`)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/cases/cases-logic.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { file_reader } from '#scripts/lib/read-file'
 
 // `josh cases <path...>` (joshuafolkken/kit#2246): read the changed paths and answer which I/O
 // boundaries the code crosses — network, process start, filesystem — then name the abnormal cases
@@ -63,11 +63,7 @@ const BOUNDARIES: ReadonlyArray<BoundaryDefinition> = [
 // A path that cannot be read counts as no boundary rather than an error: a deleted or renamed path in
 // a diff is still passed in, and the answer for it is simply "nothing crossed here".
 function read_file(path: string): string {
-	try {
-		return readFileSync(path, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(path) ?? ''
 }
 
 // The distinct boundaries any of the paths cross. The content is joined and each boundary is tested

package/scripts/ci/pr-classification.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import {
 	BREAKING_CHANGE_LABEL as BREAKING,
 	BUGFIX_LABEL as BUGFIX,
@@ -7,7 +8,7 @@ import {
 	ENHANCEMENT_LABEL,
 	type ReleaseClassification,
 } from '#scripts/git/issue-labels'
-import { execaSync } from 'execa'
+import { error_text } from '#scripts/lib/error-message'
 import { z } from 'zod'
 
 const CLASSIFICATION_SET: ReadonlySet<string> = new Set(CLASSIFICATION_LABELS)
@@ -95,17 +96,17 @@ function select_issue_classification(issue_json: string): ReleaseClassification
 // payload, that run fails, and when it lands in the newer check suite GitHub keeps its red result —
 // a rerun replays the same payload and fails again (joshuafolkken/kit#2712).
 function fetch_current_labels(repository: string, pull_number: number): ReadonlyArray<string> {
-	const result = execaSync(
-		'gh',
-		['api', `repos/${repository}/issues/${String(pull_number)}/labels`, '--jq', '.[].name'],
-		{ reject: false },
-	)
-
-	if (result.exitCode !== 0) {
-		throw new Error(`Could not read the pull request labels: ${result.stderr}`)
-	}
+	const path = `repos/${repository}/issues/${String(pull_number)}/labels`
+
+	try {
+		const names = git_gh_exec.exec_gh_api_sync({ path, jq_filter: '.[].name' })
 
-	return result.stdout.split('\n').filter((name) => name !== '')
+		return names.split('\n').filter((name) => name !== '')
+	} catch (error) {
+		const detail = error_text.message_of(error)
+
+		throw new Error(`Could not read the pull request labels: ${detail}`, { cause: error })
+	}
 }
 
 function check_event(
@@ -133,6 +134,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 const pr_classification = {
 	classification_error,
 	check_event,
+	fetch_current_labels,
 	declaration,
 	is_classification,
 	select_issue_classification,

package/scripts/cost-runtime/cost-transcript.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import { lane_paths } from '#scripts/lane/lane-paths'
+import { file_reader } from '#scripts/lib/read-file'
 import { cost_usage, type UsageRecord } from './cost-usage'
 
 // Finding and reading Claude Code's session transcripts (joshuafolkken/kit#962).
@@ -404,16 +405,8 @@ function tally(content: string): Omit<SessionUsage, 'session_id'> {
 	}
 }
 
-function read_text(file_path: string): string | undefined {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return undefined
-	}
-}
-
 function read_session(file: SessionFile): SessionUsage {
-	const content = read_text(file.path)
+	const content = file_reader.read_if_readable(file.path)
 
 	if (content === undefined) return { session_id: file.session_id, ...empty_session() }
 
@@ -426,7 +419,7 @@ function read_session(file: SessionFile): SessionUsage {
 // "could not be read" is already reported through `is_readable`, and throwing here would turn one
 // missing session into a failed command.
 function read_raw(file: SessionFile): string {
-	return read_text(file.path) ?? ''
+	return file_reader.read_if_readable(file.path) ?? ''
 }
 
 // The same read, with the failure left visible (joshuafolkken/kit#1439). **An unreadable transcript
@@ -435,7 +428,7 @@ function read_raw(file: SessionFile): string {
 // measured* rather than as measured at zero. `is_readable` on `SessionUsage` is the same distinction
 // on the cost side; this is it for a caller that wants the text.
 function read_optional(file: SessionFile): string | undefined {
-	return read_text(file.path)
+	return file_reader.read_if_readable(file.path)
 }
 
 // One directory the search looked in, and whether it was there to look in. `exists` tells a directory

package/scripts/doctor/doctor-consumer.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { safe_json_parse } from '#scripts/version/parse-json'
@@ -36,16 +37,8 @@ const STATE_TARGET_MISSING = 'target-missing'
 const STATE_MISSING = 'missing'
 type ClaudeMdState = typeof STATE_OK | typeof STATE_TARGET_MISSING | typeof STATE_MISSING
 
-function read_optional(file_path: string): string | undefined {
-	try {
-		return existsSync(file_path) ? readFileSync(file_path, 'utf8') : undefined
-	} catch {
-		return undefined
-	}
-}
-
 function parse_manifest(root: string): ManifestShape | undefined {
-	const content = read_optional(path.join(root, 'package.json'))
+	const content = file_reader.read_if_readable(path.join(root, 'package.json'))
 	if (content === undefined) return undefined
 	const parsed = manifest_schema.safeParse(safe_json_parse(content))
 
@@ -74,7 +67,7 @@ function is_kit_consumer(root: string): boolean {
 }
 
 function is_plugin_declared(root: string): boolean {
-	const content = read_optional(path.join(root, SETTINGS_PATH))
+	const content = file_reader.read_if_readable(path.join(root, SETTINGS_PATH))
 	if (content === undefined) return false
 	const parsed = settings_schema.safeParse(safe_json_parse(content))
 
@@ -94,7 +87,7 @@ function configured_hooks_path(root: string): string | undefined {
 }
 
 function claude_md_state(root: string): ClaudeMdState {
-	const content = read_optional(path.join(root, CLAUDE_MD))
+	const content = file_reader.read_if_readable(path.join(root, CLAUDE_MD))
 	if (content === undefined) return STATE_MISSING
 	if (!content.includes(CLAUDE_MD_POINTER)) return STATE_OK