@joshuafolkken/kit 1.1050.0 → 1.1128.0

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { josh_command } from '#scripts/josh/josh-run'
+import { cli_flags } from '#scripts/lib/cli-flags'
 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'
@@ -61,15 +61,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean | ReadonlyArray<
 const FORWARDED = ['started', 'active', 'merged', 'running', 'max', 'idle'] as const
 
 function read_values(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
-}
-
-function text_of(value: string | boolean | ReadonlyArray<string> | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 function to_count(raw: string | undefined): number | undefined {
@@ -94,8 +86,8 @@ interface OfferCounts {
 // The two counts the mapping needs: `--running` decides `wait`, `--retries` decides `retry`. Either
 // given but unreadable refuses the whole invocation.
 function counts_of(values: ParsedValues): OfferCounts | undefined {
-	const running = count_of(text_of(values.running), DEFAULT_COUNT)
-	const retries = count_of(text_of(values.retries), DEFAULT_COUNT)
+	const running = count_of(cli_flags.string_of(values.running), DEFAULT_COUNT)
+	const retries = count_of(cli_flags.string_of(values.retries), DEFAULT_COUNT)
 
 	if (running === undefined || retries === undefined) return undefined
 
@@ -109,7 +101,7 @@ function excludes_of(values: ParsedValues): ReadonlyArray<string> {
 }
 
 function next_argv(values: ParsedValues): ReadonlyArray<string> {
-	const repo = text_of(values.repo)
+	const repo = cli_flags.string_of(values.repo)
 
 	return [
 		'backlog:next',
@@ -120,7 +112,7 @@ function next_argv(values: ParsedValues): ReadonlyArray<string> {
 
 function budget_argv(values: ParsedValues, answer: string): ReadonlyArray<string> {
 	const forwarded = FORWARDED.flatMap((name) => {
-		const value = text_of(values[name])
+		const value = cli_flags.string_of(values[name])
 
 		return value === undefined ? [] : [`--${name}`, value]
 	})
@@ -262,16 +254,11 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 
 const backlog_offer_cli = {
 	JSON_KEY,
-	USAGE,
 	budget_argv,
 	counts_of,
-	emit,
-	main,
-	mark_drain,
 	next_argv,
 	read_values,
 	run,
-	to_tokens,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

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

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
 import { epic_index } from '#scripts/epic/epic-index'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { read_json_listing } from '#scripts/git/parse-json-array'
 import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { run_invocation } from '#scripts/run/run-invocation'
@@ -263,13 +263,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const backlog_plan_cli = {
 	OPEN_TRUNCATED_MESSAGE,
 	OPEN_UNREADABLE_MESSAGE,
-	USAGE,
 	WAVES_WITH_NAMED_MESSAGE,
-	classify,
-	fetch_open,
-	main,
-	print_plan,
-	report,
 	run,
 }
 

package/scripts/backlog/backlog-plan.ts

@@ -3,7 +3,8 @@ 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 { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
 // The plan a person reads before a `backlogrun` starts (joshuafolkken/kit#1652).
@@ -57,23 +58,29 @@ interface PlanContext {
 
 // A child elsewhere is qualified, because a bare number would name *this* repository's issue of that
 // number — a different issue (joshuafolkken/kit#1016). Takes the reference rather than the child, so
-// a `blocked_by` edge is named by the same rule the child itself is.
-function reference_of(reference: IssueReference, repo: string): string {
+// a `blocked_by` edge is named by the same rule the child itself is. This repository's issue is cited
+// (joshuafolkken/kit#3099): the plan is copied into a report verbatim, so the line it prints is the
+// citation the report carries.
+function cite_of(reference: IssueReference, repo: string, title: string | undefined): string {
 	const number = String(reference.number)
 
-	return reference.repo === repo ? `#${number}` : `${reference.repo}#${number}`
+	return reference.repo === repo
+		? issue_cite.reference(repo, number, title)
+		: `${reference.repo}#${number}`
+}
+
+function reference_of(reference: IssueReference, repo: string): string {
+	return cite_of(reference, repo, undefined)
 }
 
 // A title is only known for this repository's issues — the open listing the titles come from is this
 // repository's. A child elsewhere is still named, just without one.
-function title_of(child: EpicChild, context: PlanContext): string {
-	return child.repo === context.repo ? (context.titles.get(child.number) ?? '') : ''
+function title_of(child: EpicChild, context: PlanContext): string | undefined {
+	return child.repo === context.repo ? context.titles.get(child.number) : undefined
 }
 
-function join_row(reference: string, title: string, note: string): string {
-	const parts = [reference, title, note === '' ? '' : `— ${note}`].filter((part) => part !== '')
-
-	return `${ROW_INDENT}${parts.join('  ')}`
+function join_row(reference: string, note: string): string {
+	return note === '' ? `${ROW_INDENT}${reference}` : `${ROW_INDENT}${reference}  — ${note}`
 }
 
 // A `run:solo` child is marked beside its number, so a person reading the plan sees which issues
@@ -89,15 +96,15 @@ function mark_of(child: EpicChild): string | undefined {
 	return epic_triage.is_triaged(child) ? undefined : UNTRIAGED_MARK
 }
 
-function marked_reference(child: EpicChild, repo: string): string {
-	const reference = reference_of(child, repo)
+function marked_reference(child: EpicChild, repo: string, title?: string): string {
+	const reference = cite_of(child, repo, title)
 	const mark = mark_of(child)
 
 	return mark === undefined ? reference : `${reference} ${mark}`
 }
 
 function row_of(child: EpicChild, context: PlanContext, note: string): string {
-	return join_row(marked_reference(child, context.repo), title_of(child, context), note)
+	return join_row(marked_reference(child, context.repo, title_of(child, context)), note)
 }
 
 // Why this one is not offered yet. The blocker numbers are the answer whenever there are any — that
@@ -164,8 +171,10 @@ function waiting_lines(children: ReadonlyArray<EpicChild>, context: PlanContext)
 	})
 }
 
-function scope_lines(rows: ReadonlyArray<OutOfScopeRow>): Array<string> {
-	return rows.map((row) => join_row(`#${String(row.number)}`, row.title, row.reason))
+function scope_lines(rows: ReadonlyArray<OutOfScopeRow>, repo: string): Array<string> {
+	return rows.map((row) =>
+		join_row(issue_cite.reference(repo, String(row.number), row.title), row.reason),
+	)
 }
 
 // The classification could not be made, so every section below it would be rendered from buckets
@@ -186,10 +195,12 @@ interface NamedPlan {
 	only: boolean
 }
 
-// The named issues are this repository's own, so a bare `#N` names them and a title is looked up the
-// same way the pool's rows are. The order is the invocation's, never sorted.
+// The named issues are this repository's own, so they are cited against it and a title is looked up
+// the same way the pool's rows are. The order is the invocation's, never sorted.
 function named_lines(named: ReadonlyArray<number>, context: PlanContext): Array<string> {
-	return named.map((issue) => join_row(`#${String(issue)}`, context.titles.get(issue) ?? '', ''))
+	return named.map((issue) =>
+		join_row(issue_cite.reference(context.repo, String(issue), context.titles.get(issue)), ''),
+	)
 }
 
 // The section leads the plan when the invocation named issues, and is absent otherwise — a bare
@@ -230,7 +241,7 @@ function format_plan(
 		'',
 		section(HUMAN_HEADING, child_lines(result.blocked_on_people, context, no_note)),
 		'',
-		section(SCOPE_HEADING, scope_lines(out_of_scope)),
+		section(SCOPE_HEADING, scope_lines(out_of_scope, context.repo)),
 	].join('\n')
 }
 

package/scripts/backlog/backlog-pool.ts

@@ -5,14 +5,14 @@ import { epic_index } from '#scripts/epic/epic-index'
 import { epic_issue } from '#scripts/epic/epic-issue'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
-import { git_next_issues } from '#scripts/git/git-next-issues'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { git_next_issues } from '#scripts/issue/git-next-issues'
 import {
 	ALREADY_DONE_LABEL,
 	EPIC_LABEL,
 	has_any_label,
 	NEEDS_DECISION_LABEL,
-} from '#scripts/git/issue-labels'
-import type { OpenIssueData } from '#scripts/git/schemas'
+} from '#scripts/issue/issue-labels'
 
 // The candidate pool `josh backlog:next` answers from (joshuafolkken/kit#1630).
 //
@@ -328,14 +328,11 @@ const backlog_pool = {
 	standalone_keys,
 	drop_excluded,
 	epic_classification,
-	is_epic_row,
-	keys_of,
 	merge_classifications,
 	opted_in_epics,
 	standalone_rows,
 	to_child,
 	to_children,
-	unique_children,
 }
 
 export { backlog_pool }

package/scripts/backlog/backlog-rank.ts

@@ -3,7 +3,7 @@ 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'
+import { git_next_issues } from '#scripts/issue/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
@@ -100,7 +100,7 @@ function gate(
 	)
 }
 
-const backlog_rank = { everything_in, gate, rank, rank_result, select }
+const backlog_rank = { everything_in, gate, rank_result, select }
 
 export { backlog_rank }
 export type { OfferInput }

package/scripts/backlog/backlog-ready.ts

@@ -1,3 +1,5 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry } from '#scripts/lane/lane-registry'
@@ -21,6 +23,13 @@ interface ReadyPorts {
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
+async function free_under(limit: number): Promise<number> {
+	const lanes = await lane_registry.list_lanes()
+	const live = lanes.filter((lane) => !lane.is_stranded).length
+
+	return lane_capacity.free_lanes(limit, live)
+}
+
 // Free lanes right now: the limit less the live lanes. An unreadable limit reads as no free lane — the
 // safe direction, since both the stall and the ready line need a free lane and reporting one that is
 // not there is the false positive neither may raise.
@@ -35,10 +44,18 @@ async function free_lane_count(): Promise<number> {
 
 	if (limit.kind !== 'limit') return NO_FREE
 
-	const lanes = await lane_registry.list_lanes()
-	const live = lanes.filter((lane) => !lane.is_stranded).length
+	return await free_under(limit.limit)
+}
 
-	return lane_capacity.free_lanes(limit.limit, live)
+// **The drive's count throws on an unreadable limit** (joshuafolkken/kit#3027). The drive launches no
+// more than this count, so the safe-direction zero above would leave it launching nothing and reporting
+// nothing for good; a bad setting is the hard error `lane_capacity` says it is, ending the drive loudly.
+async function drive_free_lane_count(): Promise<number> {
+	const limit = lane_capacity.lane_limit()
+
+	if (limit.kind !== 'limit') throw new Error(limit.problem)
+
+	return await free_under(limit.limit)
 }
 
 // **A `--only` run has no pool to drain** (joshuafolkken/kit#2472). `backlog:next` lists the opted-in
@@ -77,35 +94,46 @@ async function read_ready(ports: ReadyPorts = DEFAULT_PORTS): Promise<ReadyReadi
 	return { issues: await ports.ready_issues(), free_lanes }
 }
 
-// `undefined` unless there is both runnable work and a lane for it — the only state worth a line.
-function ready_line(reading: ReadyReading): string | undefined {
+// `undefined` unless there is both runnable work and a lane for it — the only state worth a line. Each
+// issue is a number-link against `slug` (joshuafolkken/kit#3099): the parent copies this line into its
+// report, so a bare `#N` here is the citation the Stop guard sends back.
+function ready_line(reading: ReadyReading, slug: string | undefined): string | undefined {
 	if (reading.issues.length === NONE || reading.free_lanes <= NO_FREE) return undefined
 
-	const issues = reading.issues.map((issue) => `#${issue}`).join(' ')
+	const cite = issue_cite.citer(slug, new Map())
+	const issues = reading.issues.map((issue) => cite(issue)).join(' ')
 
 	return `ready ${issues} · free lanes ${String(reading.free_lanes)}`
 }
 
+type RepoRead = () => Promise<string | undefined>
+
 // The watcher's line on exit, for the driving parent alone — a `fullrun` watcher has no pool to pick
 // from. Best-effort: a reading that fails prints nothing rather than failing the watcher whose exit is
 // the wake.
 async function parent_ready_line(
 	ports: ReadyPorts,
 	is_parent: () => Promise<boolean>,
+	read_repo: RepoRead,
 ): Promise<string | undefined> {
 	if (!(await is_parent())) return undefined
 
-	return ready_line(await read_ready(ports))
+	const reading = await read_ready(ports)
+
+	return reading.issues.length === NONE ? undefined : ready_line(reading, await read_repo())
+}
+
+function print_line(line: string | undefined): void {
+	if (line !== undefined) console.info(line)
 }
 
 async function print_ready_line(
 	ports: ReadyPorts = DEFAULT_PORTS,
 	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+	read_repo: RepoRead = git_gh_command.repo_get_name_with_owner,
 ): Promise<void> {
 	try {
-		const line = await parent_ready_line(ports, is_parent)
-
-		if (line !== undefined) console.info(line)
+		print_line(await parent_ready_line(ports, is_parent, read_repo))
 	} catch {
 		// A pick-up line is a hint; the wake it rides must still be delivered.
 	}
@@ -135,6 +163,7 @@ const backlog_ready = {
 	read_backlog_next,
 	print_offer_hint,
 	free_lane_count,
+	drive_free_lane_count,
 	drains_pool,
 	print_ready_line,
 	read_ready,

package/scripts/backlog/backlog-scope.ts

@@ -1,6 +1,6 @@
 import type { EpicNextResult } from '#scripts/epic/epic-report'
-import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
 import type { OpenIssueData } from '#scripts/git/schemas'
+import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 
 // Which open issues the backlog will not run, and why (joshuafolkken/kit#1652).
 //
@@ -135,8 +135,6 @@ const backlog_scope = {
 	OPTED_IN_UNPLACED_REASON,
 	open_numbers_of,
 	out_of_scope,
-	planned_numbers,
-	reason_for,
 	titles_of,
 }
 

package/scripts/backlog/backlog-stalled-detect.ts

@@ -1,4 +1,4 @@
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
@@ -137,7 +137,7 @@ async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS):
 	}
 }
 
-const backlog_stalled_detect = { DEFAULT_PORTS, detect_and_report, gather, report, run_stall_check }
+const backlog_stalled_detect = { detect_and_report, run_stall_check }
 
 export { backlog_stalled_detect }
 export type { DetectPorts }

package/scripts/backlog/backlog-stalled.ts

@@ -118,7 +118,6 @@ const backlog_stalled = {
 	count_ready_tokens,
 	describe,
 	dispatch_age_ms,
-	is_stalled,
 	needs_triage,
 	ready_tokens,
 }

package/scripts/backlog/backlog-waves.ts

@@ -4,7 +4,11 @@ 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 { has_label_name, IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import {
+	has_label_name,
+	IN_PROGRESS_LABEL,
+	NEEDS_DECISION_LABEL,
+} from '#scripts/issue/issue-labels'
 import { backlog_plan, type PlanContext } from './backlog-plan'
 import { backlog_rank } from './backlog-rank'
 
@@ -171,7 +175,6 @@ function format_waves(
 const backlog_waves = {
 	HEADING_ASSUMPTION,
 	NEEDS_DECISION_NOTE,
-	NOT_REACHED_NOTE,
 	PARALLEL_NOTE,
 	UNREACHED_HEADING,
 	build,

package/scripts/behavior/behavior-cli.ts

@@ -81,7 +81,7 @@ function run(cwd: string = process.cwd()): number {
 	return file === undefined ? report_no_transcript() : check_session(file)
 }
 
-const behavior_cli = { LABEL, check_session, current_session, run }
+const behavior_cli = { check_session, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = run()
 

package/scripts/build/build-codex-hooks.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { codex_hooks } from '#scripts/agent/codex-hooks'
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const CLAUDE_SETTINGS = path.join(REPO_ROOT, '.claude', 'settings.json')
+const CODEX_HOOKS = path.join(REPO_ROOT, '.codex', 'hooks.json')
+
+// Regenerate `.codex/hooks.json` from `.claude/settings.json` (joshuafolkken/kit#2997). The output is
+// committed rather than gitignored: Codex reads it straight from a fresh clone of kit, before any
+// build has run, and `josh init` / `josh sync` copy it to consumers from the package.
+function build_codex_hooks(): string {
+	writeFileSync(CODEX_HOOKS, codex_hooks.codex_hooks_text(readFileSync(CLAUDE_SETTINGS, 'utf8')))
+
+	return CODEX_HOOKS
+}
+
+function main(): void {
+	console.info(`  ✔ ${build_codex_hooks()} built`)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { build_codex_hooks, CLAUDE_SETTINGS, CODEX_HOOKS }

package/scripts/build/build-hooks.ts

@@ -1,12 +1,27 @@
 #!/usr/bin/env tsx
-import { readdirSync, rmSync } from 'node:fs'
+import {
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { hook_bundle_stamp } from '#scripts/build/hook-bundle-stamp'
 import { error_text } from '#scripts/lib/error-message'
-import { build } from 'esbuild'
+import { build, type OnLoadArgs, type OutputFile, type Plugin, type PluginBuild } from 'esbuild'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const OUT_DIR = path.join(PACKAGE_DIR, 'dist', 'hooks')
+const { STAMP_NAME } = hook_bundle_stamp
+const CHUNK_PREFIX = 'chunk-'
+const STAGING_PREFIX = '.hooks-staging-'
+// esbuild compiles a plugin filter as a Go regexp, which rejects the `u` flag.
+// eslint-disable-next-line require-unicode-regexp
+const ANY_PATH = /.*/
 
 // Each Claude Code hook is bundled to its own `dist/hooks/<name>.js`, so a consumer (and kit itself)
 // invokes `node dist/hooks/<name>.js` directly — no `pnpm` launch and no `tsx` re-spawn from the
@@ -60,20 +75,76 @@ function outfile_for(bundle: HookBundle): string {
 // 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)))
+	const live = new Set([...outputs.map((output) => path.basename(output)), STAMP_NAME])
 
 	for (const name of readdirSync(out_directory)) {
 		if (!live.has(name)) rmSync(path.join(out_directory, name), { recursive: true, force: true })
 	}
 }
 
+// Every file the build loads is read here, so the stamp digests the exact bytes that were bundled —
+// a source edited mid-build is recorded as what it was, and the next launch rebuilds it.
+function source_recorder(sources: Map<string, Uint8Array>): Plugin {
+	return {
+		name: 'hook-source-recorder',
+		setup(plugin_build: PluginBuild): void {
+			plugin_build.onLoad({ filter: ANY_PATH, namespace: 'file' }, function load(args: OnLoadArgs) {
+				const contents = readFileSync(args.path)
+
+				sources.set(path.relative(PACKAGE_DIR, args.path), contents)
+
+				return { contents, loader: 'default' }
+			})
+		},
+	}
+}
+
+function is_chunk(file: OutputFile): boolean {
+	return path.basename(file.path).startsWith(CHUNK_PREFIX)
+}
+
+// Shared chunks first, then the entries that import them: an entry swapped in before its chunks
+// would fail to load in a hook launched at that moment.
+function is_chunk_first(left: OutputFile, right: OutputFile): number {
+	return Number(is_chunk(right)) - Number(is_chunk(left))
+}
+
+// Each file is written into a private staging directory and renamed into place, so a hook never
+// reads a half-written bundle and two builds running side by side never write one file at once.
+function place(staging: string, target: string, contents: Uint8Array | string): void {
+	const temporary = path.join(staging, path.basename(target))
+
+	writeFileSync(temporary, contents)
+	renameSync(temporary, target)
+}
+
+function place_build(out_directory: string, files: ReadonlyArray<OutputFile>, stamp: string): void {
+	mkdirSync(out_directory, { recursive: true })
+	const staging = mkdtempSync(path.join(path.dirname(out_directory), STAGING_PREFIX))
+
+	try {
+		for (const file of files.toSorted(is_chunk_first)) place(staging, file.path, file.contents)
+		prune_stale_outputs(
+			out_directory,
+			files.map((file) => file.path),
+		)
+		place(staging, path.join(out_directory, STAMP_NAME), stamp)
+	} finally {
+		rmSync(staging, { 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.
+// (joshuafolkken/kit#2885). The cleanup runs after the new files are in place 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. The source digest is placed last (`hook-bundle-stamp.ts`), so a launch only reads
+// the bundles as fresh once every one of them is in place (joshuafolkken/kit#2984).
 async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
-	const { metafile } = await build({
+	const sources = new Map<string, Uint8Array>()
+	const { outputFiles: files } = await build({
+		absWorkingDir: PACKAGE_DIR,
 		entryPoints: HOOK_BUNDLES.map((bundle) => entry_point(bundle)),
 		outdir: out_directory,
 		bundle: true,
@@ -82,10 +153,15 @@ async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
 		format: 'esm',
 		target: 'node22',
 		packages: 'external',
-		metafile: true,
+		write: false,
+		plugins: [source_recorder(sources)],
 	})
+	const stamp = hook_bundle_stamp.stamp_text(
+		sources,
+		files.map((file) => file.path),
+	)
 
-	prune_stale_outputs(out_directory, Object.keys(metafile.outputs))
+	place_build(out_directory, files, stamp)
 }
 
 async function main(): Promise<void> {