@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/backlog/backlog-next.ts

@@ -9,13 +9,13 @@ import { epic_next } from '#scripts/epic/epic-next'
 import { epic_next_read, type EpicRead } from '#scripts/epic/epic-next-read'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_report, type EpicNextResult, type EpicVerdict } from '#scripts/epic/epic-report'
-import { epic_solo } from '#scripts/epic/epic-solo'
 import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
 import { backlog_pool } from './backlog-pool'
+import { backlog_rank } from './backlog-rank'
 
 // `josh backlog:next` — what the whole opted-in backlog may run next (joshuafolkken/kit#1630).
 //
@@ -235,12 +235,15 @@ async function resolve(context: PoolContext): Promise<EpicNextResult | undefined
 		return undefined
 	}
 
-	// The defect priority is applied here rather than when printing, so `backlog:plan` shows the order
-	// the run takes (joshuafolkken/kit#2455).
-	return await backlog_defect_priority.prioritize(
+	// The defect priority and the ranking keys are applied here rather than when printing, so
+	// `backlog:plan` shows the order the run takes (joshuafolkken/kit#2455, joshuafolkken/kit#2928). The
+	// ranking goes last: its sort is stable, so the defect order survives as its final key.
+	const ordered = await backlog_defect_priority.prioritize(
 		combine(views_from(reads, context), context),
 		context.repo,
 	)
+
+	return backlog_rank.rank_result(ordered, context.repo)
 }
 
 // Whether the `error` verdict is really a transport failure wearing the graph's clothes.
@@ -274,13 +277,25 @@ function report_retry(context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
+// The rows the offer's cap bounds — the standalone half, which `backlog:plan --waves` reads too.
+function standalone_keys(context: PoolContext): ReadonlySet<string> {
+	return backlog_pool.standalone_keys(context.opted_in.issues, {
+		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
+		exclude: context.exclude,
+		repo: context.repo,
+	})
+}
+
 // The `run:solo` gate is applied here rather than in `resolve`, because `backlog:plan` shares
 // `resolve` and a plan made before the run lists everything (joshuafolkken/kit#2776). The holders are
-// read only on a `run` answer — the one answer the gate can change.
-async function gate_solo(result: EpicNextResult, repo: string): Promise<EpicNextResult> {
+// read only on a `run` answer — the one answer the gate can change. The cap follows the gate
+// (`backlog-rank.ts`, joshuafolkken/kit#2928).
+async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<EpicNextResult> {
 	if (result.verdict !== 'run') return result
 
-	const gated = epic_solo.gate(result, await epic_busy.read_repository(repo), repo)
+	const { repo } = context
+	const read = await epic_busy.read_repository(repo)
+	const gated = backlog_rank.gate(result, read, repo, standalone_keys(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
 
@@ -314,7 +329,7 @@ async function answer_pool(context: PoolContext): Promise<number> {
 
 	if (untriaged.length > 0) return report_triage(context, untriaged)
 
-	return report(await gate_solo(result, context.repo), context)
+	return report(await gate_solo(result, context), context)
 }
 
 // A backlog nobody has opted into answers `none` before either listing below is asked for.
@@ -402,6 +417,7 @@ const backlog_next = {
 	combine,
 	views_from,
 	resolve,
+	standalone_keys,
 	is_transport_failure,
 	report_retry,
 	report_triage,

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-cli.ts

@@ -104,6 +104,9 @@ interface Plan {
 	// past the listing cap. Carrying the *whole* index here instead would move that misreport rather
 	// than remove it: the sentence would name an epic that is withholding nothing.
 	tracked: ReadonlyMap<number, number>
+	// The rows the offer's cap bounds, so `--waves` cuts each wave where `backlog:next` does
+	// (joshuafolkken/kit#2928).
+	standalone: ReadonlySet<string>
 }
 
 // The listing plus whether it was cut. Carried together because the rows alone cannot say whether
@@ -138,6 +141,7 @@ async function classify(
 		repo: context.repo,
 		exclude,
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
+		standalone: backlog_next.standalone_keys(context),
 	}
 }
 
@@ -168,7 +172,7 @@ function print_plan(plan: Plan, listing: OpenListing, view: PlanView): void {
 	const context = context_of(plan, listing)
 
 	if (view.is_waves) {
-		console.info(backlog_waves.format_waves(plan.result, context))
+		console.info(backlog_waves.format_waves(plan.result, context, plan.standalone))
 
 		return
 	}

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/backlog/backlog-pool.ts

@@ -37,6 +37,9 @@ const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALRE
 // `tracked` is the narrowed set `epic_index.withheld_children` builds, not every child an epic
 // tracks (joshuafolkken/kit#1668) — the narrowing itself is defined there, once, for this half and
 // `auto-ok:next` alike.
+// The part of the context that decides which rows the standalone half considers at all.
+type ConsideredContext = Pick<StandaloneContext, 'tracked' | 'exclude' | 'repo'>
+
 interface StandaloneContext {
 	tracked: ReadonlyMap<number, number>
 	exclude: ReadonlyArray<number>
@@ -135,26 +138,28 @@ function standalone_rows(issues: ReadonlyArray<OpenIssueData>): ReadonlyArray<Op
 // are actually going to offer their children and applied here for the same reason. Which rows those
 // are is `epic_index.withheld_children`'s answer, not a second test made here. A row the caller
 // excluded is out of the pool entirely rather than merely unoffered: it has just merged.
-function is_considered(issue: OpenIssueData, context: StandaloneContext): boolean {
+function is_considered(issue: OpenIssueData, context: ConsideredContext): boolean {
 	return !context.tracked.has(issue.number) && !context.exclude.includes(issue.number)
 }
 
 // The standalone half, in the buckets the verdict is read from.
 //
-// The order is `git_next_issues.prioritize`'s and not a second one — the same ranking the
-// `🗒 Next issues` display and `auto-ok:next` already answer with, cap included, so the three cannot
-// disagree about what comes next. Anything it withholds is still open work: `needs-decision` is
-// waiting on a person, and everything else — a standing blocker, a run already in progress, a row
-// past the cap — resolves on its own and is waiting on time. **The cap is one of those**: a sixth
-// runnable standalone issue is reported as waiting rather than offered, and the next ask offers it
-// once one of the five above it merges, so the backlog drains without it ever being lost. That is
-// the cost of having one ranking rather than two, and `docs/josh-commands.md` states it.
+// The order is `git_next_issues.order`'s and not a second one — the same ranking the
+// `🗒 Next issues` display and `auto-ok:next` already answer with, so the three cannot disagree about
+// what comes next. Anything it withholds is still open work: `needs-decision` is waiting on a person,
+// and everything else — a standing blocker, a run already in progress — resolves on its own and is
+// waiting on time.
+//
+// **The display's cap is not applied here** (joshuafolkken/kit#2928). Cut at this point, a sixth
+// runnable `run:solo` issue never reached the gate that holds back what is ranked below it, so the
+// cap is applied after that gate instead (`backlog-rank.ts`). A row past it is still reported as
+// waiting and offered by a later ask, so the backlog drains without it ever being lost.
 function classify_standalone(
 	issues: ReadonlyArray<OpenIssueData>,
 	context: StandaloneContext,
 ): Classification {
 	const considered = issues.filter((issue) => is_considered(issue, context))
-	const runnable = git_next_issues.prioritize(
+	const runnable = git_next_issues.order(
 		considered.filter((issue) => auto_ok_cli.is_runnable(issue, context.tracked, context.exclude)),
 	)
 	const offered = new Set(runnable.map((issue) => issue.number))
@@ -301,11 +306,26 @@ function merge_classifications(left: Classification, right: Classification): Cla
 	}
 }
 
+// The keys of the rows the standalone half considers — the rows the offer's cap bounds. An issue an
+// opted-in epic tracks is that epic's child here, and never capped, exactly as before.
+function standalone_keys(
+	issues: ReadonlyArray<OpenIssueData>,
+	context: ConsideredContext,
+): ReadonlySet<string> {
+	return keys_of(
+		to_children(
+			standalone_rows(issues).filter((issue) => is_considered(issue, context)),
+			context.repo,
+		),
+	)
+}
+
 const backlog_pool = {
 	classify_standalone,
 	cross_epic_cycles,
 	running_set,
 	settle_standalone,
+	standalone_keys,
 	drop_excluded,
 	epic_classification,
 	is_epic_row,
@@ -319,4 +339,4 @@ const backlog_pool = {
 }
 
 export { backlog_pool }
-export type { StandaloneContext }
+export type { ConsideredContext, StandaloneContext }

package/scripts/backlog/backlog-rank.ts

@@ -0,0 +1,106 @@
+import type { BusyRead } from '#scripts/epic/epic-busy'
+import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
+import { epic_rank } from '#scripts/epic/epic-rank'
+import type { EpicNextResult } from '#scripts/epic/epic-report'
+import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
+import { git_next_issues } from '#scripts/git/git-next-issues'
+
+// What the backlog offers, in the order it is decided (joshuafolkken/kit#2928): rank, then the
+// `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
+// plan's first wave is what the run starts into an idle repository rather than an order the run never
+// takes.
+//
+// **The cap comes last.** It used to be applied while the standalone half was classified, before the
+// gate, so a `run:solo` issue ranked sixth or lower was cut before the gate could see it — and the
+// issues below it were offered past it. Cut after the gate, the cap only ever removes what the gate
+// would have offered, so it cannot hide a waiting `run:solo` issue from it. It still bounds only the
+// standalone rows, as it always has; an epic's children were never capped.
+
+// Every child the classification placed, in the order it placed them: the ranked candidates first,
+// then the waiting ones, then the ones waiting on a person.
+function everything_in(result: EpicNextResult): ReadonlyArray<EpicChild> {
+	const candidates = result.candidates.flatMap((bundle) => bundle.children)
+
+	return [...candidates, ...result.waiting, ...result.blocked_on_people]
+}
+
+// The ranking is `epic_rank.rank`, shared with a named epic's lanes.
+const { rank } = epic_rank
+
+// This repository's candidates re-ranked inside the result, so `backlog:plan` prints the order the
+// offer is decided in.
+function rank_result(result: EpicNextResult, repo: string): EpicNextResult {
+	if (result.verdict !== 'run') return result
+
+	const pool = everything_in(result)
+
+	return {
+		...result,
+		candidates: result.candidates.map((bundle) =>
+			bundle.repo === repo ? { ...bundle, children: rank(bundle.children, pool) } : bundle,
+		),
+	}
+}
+
+// The standalone rows past the cap, in offer order.
+function overflow_of(
+	offered: ReadonlyArray<EpicChild>,
+	standalone: ReadonlySet<string>,
+): ReadonlySet<string> {
+	const keys = offered.map((child) => epic_graph.key_of(child)).filter((key) => standalone.has(key))
+
+	return new Set(keys.slice(git_next_issues.DISPLAY_LIMIT))
+}
+
+function is_in(child: EpicChild, keys: ReadonlySet<string>): boolean {
+	return keys.has(epic_graph.key_of(child))
+}
+
+function cap(selection: SoloSelection, standalone: ReadonlySet<string>): SoloSelection {
+	const overflow = overflow_of(selection.offered, standalone)
+
+	if (overflow.size === 0) return selection
+
+	return {
+		...selection,
+		offered: selection.offered.filter((child) => !is_in(child, overflow)),
+		withheld: [
+			...selection.offered.filter((child) => is_in(child, overflow)),
+			...selection.withheld,
+		],
+	}
+}
+
+interface OfferInput {
+	candidates: ReadonlyArray<EpicChild>
+	pool: ReadonlyArray<EpicChild>
+	read: BusyRead
+	repo: string
+	// The keys of the standalone rows — the ones the cap bounds.
+	standalone: ReadonlySet<string>
+}
+
+function select(input: OfferInput): SoloSelection {
+	const ranked = rank(input.candidates, input.pool)
+
+	return cap(epic_solo.select(ranked, input.read, input.repo), input.standalone)
+}
+
+// `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.
+function gate(
+	result: EpicNextResult,
+	read: BusyRead,
+	repo: string,
+	standalone: ReadonlySet<string>,
+): SoloGate {
+	const pool = everything_in(result)
+
+	return epic_solo.gate(result, read, repo, (candidates) =>
+		select({ candidates, pool, read, repo, standalone }),
+	)
+}
+
+const backlog_rank = { everything_in, gate, rank, rank_result, select }
+
+export { backlog_rank }
+export type { OfferInput }

package/scripts/backlog/backlog-waves.ts

@@ -4,9 +4,9 @@ import { epic_cross_repo } from '#scripts/epic/epic-cross-repo'
 import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
-import { epic_solo } from '#scripts/epic/epic-solo'
 import { has_label_name, IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
 import { backlog_plan, type PlanContext } from './backlog-plan'
+import { backlog_rank } from './backlog-rank'
 
 // The order a `backlogrun` takes, wave by wave, before it starts (joshuafolkken/kit#2778).
 //
@@ -14,13 +14,13 @@ import { backlog_plan, type PlanContext } from './backlog-plan'
 // made from, so the order past the first answer was left for a person to work out by hand. This plays
 // the asks forward under one assumption: **every issue of a wave merges before the next wave starts**.
 //
-// **No rule is written twice.** The first wave is `epic_solo.select` over the very candidates
-// `backlog:next` resolves, asked of an idle repository — so it is what `backlog:next` prints when
-// nothing is running. Each later wave marks the earlier waves closed and re-classifies the same pool
+// **No rule is written twice.** The first wave is `backlog_rank.select` — rank, `run:solo` gate, cap —
+// over the very candidates `backlog:next` resolves, asked of an idle repository — so it is what
+// `backlog:next` prints when nothing is running (joshuafolkken/kit#2928). Each later wave marks the earlier waves closed and re-classifies the same pool
 // through `epic_classify.classify_children` with the resolver `epic:next` sorted it with the first
 // time — `epic_cross_repo.resolve_cross_repo`, so a blocker in another repository still waits for its
 // release rather than counting as done on close — then puts the runnable set through
-// `epic_solo.select` again.
+// `backlog_rank.select` again.
 
 const IDLE: BusyRead = { kind: 'idle' }
 const CLOSED = 'CLOSED'
@@ -45,14 +45,6 @@ function is_running(child: EpicChild): boolean {
 	return has_label_name(child.labels, IN_PROGRESS_LABEL)
 }
 
-// Every child the classification placed, in the order it placed them: the ranked candidates first,
-// then the waiting ones, then the ones waiting on a person.
-function everything_in(result: EpicNextResult): ReadonlyArray<EpicChild> {
-	const candidates = result.candidates.flatMap((bundle) => bundle.children)
-
-	return [...candidates, ...result.waiting, ...result.blocked_on_people]
-}
-
 function as_closed(child: EpicChild, done: ReadonlySet<string>): EpicChild {
 	return done.has(epic_graph.key_of(child)) ? { ...child, state: CLOSED } : child
 }
@@ -63,24 +55,35 @@ interface WavePool {
 	children: ReadonlyArray<EpicChild>
 	running: ReadonlySet<string>
 	repo: string
+	standalone: ReadonlySet<string>
 }
 
-function pool_of(result: EpicNextResult, repo: string): WavePool {
-	const all = everything_in(result)
+function pool_of(result: EpicNextResult, repo: string, standalone: ReadonlySet<string>): WavePool {
+	const all = backlog_rank.everything_in(result)
 
 	return {
 		children: all.filter((child) => !is_running(child)),
 		running: epic_outside_blocker.running_keys(all),
 		repo,
+		standalone,
 	}
 }
 
-function offer(runnable: ReadonlyArray<EpicChild>, repo: string): ReadonlyArray<EpicChild> {
-	return epic_solo.select(runnable, IDLE, repo).offered
+function offer(
+	candidates: ReadonlyArray<EpicChild>,
+	children: ReadonlyArray<EpicChild>,
+	pool: WavePool,
+): ReadonlyArray<EpicChild> {
+	const { repo, standalone } = pool
+
+	return backlog_rank.select({ candidates, pool: children, read: IDLE, repo, standalone }).offered
 }
 
-function first_wave(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
-	return offer(epic_report.candidates_for_repo(result, repo), repo)
+// Ranked against the whole result, exactly as `backlog:next` ranks it, so the two agree.
+function first_wave(result: EpicNextResult, pool: WavePool): ReadonlyArray<EpicChild> {
+	const candidates = epic_report.candidates_for_repo(result, pool.repo)
+
+	return offer(candidates, backlog_rank.everything_in(result), pool)
 }
 
 function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<EpicChild> {
@@ -93,25 +96,31 @@ function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<Epi
 
 	return offer(
 		runnable.filter((child) => child.repo === pool.repo),
-		pool.repo,
+		children,
+		pool,
 	)
 }
 
 // Each wave is closed before the next is asked for; a wave that offers nothing ends the plan, which
-// the pool's size bounds because every wave closes at least one child.
-function build(result: EpicNextResult, repo: string): WavePlan {
-	const pool = pool_of(result, repo)
+// the pool's size bounds because every wave closes at least one child. `standalone` names the rows the
+// offer's cap bounds; left empty, no wave is capped.
+function build(
+	result: EpicNextResult,
+	repo: string,
+	standalone: ReadonlySet<string> = new Set(),
+): WavePlan {
+	const pool = pool_of(result, repo, standalone)
 	const done = new Set<string>()
 	const waves: Array<ReadonlyArray<EpicChild>> = []
 
-	for (let wave = first_wave(result, repo); wave.length > 0; wave = next_wave(pool, done)) {
+	for (let wave = first_wave(result, pool); wave.length > 0; wave = next_wave(pool, done)) {
 		waves.push(wave)
 		for (const child of wave) done.add(epic_graph.key_of(child))
 	}
 
-	const unreached = everything_in(result).filter(
-		(child) => child.repo === repo && !done.has(epic_graph.key_of(child)),
-	)
+	const unreached = backlog_rank
+		.everything_in(result)
+		.filter((child) => child.repo === repo && !done.has(epic_graph.key_of(child)))
 
 	return { waves, unreached }
 }
@@ -139,10 +148,14 @@ function unreached_lines(plan: WavePlan, context: PlanContext): Array<string> {
 	)
 }
 
-function format_waves(result: EpicNextResult, context: PlanContext): string {
+function format_waves(
+	result: EpicNextResult,
+	context: PlanContext,
+	standalone: ReadonlySet<string> = new Set(),
+): string {
 	if (result.verdict === 'error') return backlog_plan.format_unusable(result)
 
-	const plan = build(result, context.repo)
+	const plan = build(result, context.repo, standalone)
 	const waves = plan.waves.map((wave, index) => wave_line(wave, index, context.repo))
 
 	return [

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)), '..', '..')
@@ -18,6 +20,11 @@ const OUT_DIR = path.join(PACKAGE_DIR, 'dist', 'hooks')
 // splitting keeps every entry in its own file with its own `import.meta.url`, so an imported guard's
 // `import.meta.url` never equals `argv[1]` and only the file actually launched runs its main.
 //
+// **The flip side: an entry another entry imports loses its main** (joshuafolkken/kit#2922). Splitting
+// moves a module two entries share into a chunk, so a launched hook whose own module is imported
+// elsewhere becomes a re-export stub that runs nothing. Each launched hook is therefore a `*-cli.ts`
+// file holding only the self-invoke, which no other module imports.
+//
 // `packages: 'external'` keeps bare dependencies as runtime imports the consumer resolves from kit's
 // node_modules, exactly as the library bundles do, while kit's internal `#scripts/*` graph is inlined.
 // No shebang banner is added: unlike `dist/josh.js` (the `bin.josh` entry, executed directly), a hook
@@ -33,9 +40,9 @@ interface HookBundle {
 // `delivered-rules` (the fourth guard) has no self-invoke, so it stays inlined.
 const HOOK_BUNDLES: ReadonlyArray<HookBundle> = [
 	{ source: 'scripts/hooks/codex-hook-adapter.ts', out: 'codex-hook-adapter' },
-	{ source: 'scripts/hooks/pretool-guard.ts', out: 'pretool-guard' },
+	{ source: 'scripts/hooks/pretool-guard-cli.ts', out: 'pretool-guard' },
 	{ source: 'scripts/hooks/stop-guard.ts', out: 'stop-guard' },
-	{ source: 'scripts/hooks/format-edited-file.ts', out: 'format-edited' },
+	{ source: 'scripts/hooks/format-edited-cli.ts', out: 'format-edited' },
 	{ source: 'scripts/josh/session-language-cli.ts', out: 'session-lang' },
 	{ source: 'scripts/hooks/batch-guard.ts', out: 'batch-guard' },
 	{ source: 'scripts/delegation/investigation-guard.ts', out: 'investigation-guard' },
@@ -50,17 +57,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 +93,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