@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/git/main-merge-regenerate.ts

@@ -1,64 +1,89 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
 import { SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { git_command } from './git-command'
 import { git_spawn } from './git-spawn'
+import { main_merge_budget_conflict } from './main-merge-budget-conflict'
 
-// A merge of the default branch that stops only on generated files is finished here rather than by a
-// resumed session: each such file is the output of a command, so running that command on the merged
-// tree writes the one correct resolution, with no conflict marker for anyone to read.
+// A merge of the default branch that stops only on the files below is finished here rather than by a
+// resumed session, with no conflict marker for anyone to read. A generated file is the output of a
+// command, so running that command on the merged tree writes the one correct resolution. A rewritten
+// file is resolved by a rule that keeps both sides of the merge, and throws on any hunk it cannot.
 //
-// **This table is the single list of what is resolved that way** — a file a person writes never
-// belongs in it, because regenerating would discard that person's side of the merge. A conflict on any
-// path not listed here still stops as `conflict`. A file belongs here only once its committed content
-// is exactly what its command writes: `tools/test/pure-files.ts` is not, so regenerating it would
-// rewrite far more than the conflict.
+// **This table is the single list of what is resolved that way** — a file a person writes belongs in
+// it only with a rewrite rule, because regenerating would discard that person's side of the merge. A
+// conflict on any path not listed here still stops as `conflict`. A file is regenerated only once its
+// committed content is exactly what its command writes: `tools/test/pure-files.ts` is not, so
+// regenerating it would rewrite far more than the conflict.
 
 interface RegeneratedFile {
 	path: string
 	command: ReadonlyArray<string>
 }
 
-const REGENERATED_FILES: ReadonlyArray<RegeneratedFile> = [
+interface RewrittenFile {
+	path: string
+	rewrite: (content: string) => string
+}
+
+type ResolvedFile = RegeneratedFile | RewrittenFile
+
+const RESOLVED_FILES: ReadonlyArray<ResolvedFile> = [
 	{
 		path: 'docs/josh-command-catalog.md',
-		command: ['pnpm', 'exec', 'tsx', 'tools/document/generate-catalog.ts'],
+		command: ['pnpm', 'exec', 'tsx', 'tools/document/generate-catalog-main.ts'],
+	},
+	{
+		path: main_merge_budget_conflict.BUDGET_TABLE_PATH,
+		rewrite: main_merge_budget_conflict.resolve,
 	},
 ]
 
-function regenerated_for(
+function resolved_for(
 	files: ReadonlyArray<string>,
-	table: ReadonlyArray<RegeneratedFile>,
-): ReadonlyArray<RegeneratedFile> {
+	table: ReadonlyArray<ResolvedFile>,
+): ReadonlyArray<ResolvedFile> {
 	const entries = files.map((file) => table.find((entry) => entry.path === file))
 
 	return entries.every((entry) => entry !== undefined) ? entries : []
 }
 
-// Each generator writes only its own file, so they run side by side.
-async function regenerate(entries: ReadonlyArray<RegeneratedFile>, cwd: string): Promise<void> {
+async function rewrite_file(entry: RewrittenFile, cwd: string): Promise<void> {
+	const file = path.join(cwd, entry.path)
+
+	await writeFile(file, entry.rewrite(await readFile(file, 'utf8')))
+}
+
+async function regenerate_file(entry: RegeneratedFile, cwd: string): Promise<void> {
+	const [binary = '', ...command_arguments] = entry.command
+
+	await execa(binary, command_arguments, { cwd })
+}
+
+// Each entry writes only its own file, so they run side by side.
+async function regenerate(entries: ReadonlyArray<ResolvedFile>, cwd: string): Promise<void> {
 	await Promise.all(
 		entries.map(async (entry) => {
-			const [binary = '', ...command_arguments] = entry.command
-
-			await execa(binary, command_arguments, { cwd })
+			await ('rewrite' in entry ? rewrite_file(entry, cwd) : regenerate_file(entry, cwd))
 		}),
 	)
 }
 
 // `--no-edit` keeps the message the merge was started with — the one carrying the issue number the
 // `commit-msg` hook asks for.
-async function conclude_merge(entries: ReadonlyArray<RegeneratedFile>): Promise<void> {
+async function conclude_merge(entries: ReadonlyArray<ResolvedFile>): Promise<void> {
 	await git_spawn.with_output('add', ['--', ...entries.map((entry) => entry.path)])
 	await git_spawn.with_output('commit', ['--no-edit'], { timeout_ms: SUITE_TIMEOUT_MS })
 }
 
-// Whether the merge that stopped on `files` was finished. A command that fails leaves the merge in
-// progress and answers `false`, so the stop is the `conflict` it would have been without this table.
+// Whether the merge that stopped on `files` was finished. A command that fails, or a rewrite that
+// refuses a hunk, leaves the merge in progress and answers `false`, so the stop is the `conflict` it would have been without this table.
 async function resolve(
 	files: ReadonlyArray<string>,
-	table: ReadonlyArray<RegeneratedFile> = REGENERATED_FILES,
+	table: ReadonlyArray<ResolvedFile> = RESOLVED_FILES,
 ): Promise<boolean> {
-	const entries = regenerated_for(files, table)
+	const entries = resolved_for(files, table)
 
 	if (entries.length === 0) return false
 
@@ -72,7 +97,16 @@ async function resolve(
 	return true
 }
 
-const main_merge_regenerate = { REGENERATED_FILES, resolve }
+// Whether a merge stopping on exactly `files` is one `resolve` would try to finish — asked before any
+// merge, by `josh ship`'s conflict probe, so it never stops on a conflict the sync resolves.
+function is_resolvable(
+	files: ReadonlyArray<string>,
+	table: ReadonlyArray<ResolvedFile> = RESOLVED_FILES,
+): boolean {
+	return resolved_for(files, table).length > 0
+}
+
+const main_merge_regenerate = { RESOLVED_FILES, is_resolvable, resolve }
 
-export type { RegeneratedFile }
+export type { RegeneratedFile, ResolvedFile, RewrittenFile }
 export { main_merge_regenerate }

package/scripts/git/main-merge.ts

@@ -1,8 +1,10 @@
 import { extract_issue_number } from '#scripts/hooks/check-commit-message'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { lane_install } from '#scripts/lane/lane-install'
 import { error_text } from '#scripts/lib/error-message'
 import { split_assess } from '#scripts/split/split-assess'
+import { split_early_notice } from '#scripts/split/split-early-notice'
 import { split_measure } from '#scripts/split/split-measure'
 import { git_command } from './git-command'
 import { main_merge_guard } from './main-merge-guard'
@@ -33,6 +35,9 @@ const FAILURE_EXIT_CODE = 1
 const COMMAND_NAME = 'main:merge'
 const SPLIT_UNMEASURED =
 	'split notice: the diff could not be measured — run `pnpm josh split:assess`'
+const LOCKFILE = 'pnpm-lock.yaml'
+const INSTALL_OWED =
+	'the merge brought in a lockfile change, but installing it failed — run `pnpm install --frozen-lockfile`'
 
 // git's default merge message carries no `#N`, so on an issue branch the `commit-msg` hook refuses
 // it and leaves the index mid-merge. The number is read with the hook's
@@ -47,7 +52,7 @@ function merge_message(default_branch: string, current_branch: string): string |
 }
 
 // What one merge of the default branch came to. `josh ship` merges it again
-// before the commit and on a conflicting pull request, and branches on the answer rather than on an
+// before the gate, before the push and on a followup failed on its checks, and branches on the answer rather than on an
 // exit code: `current` brought nothing in, so the tree is unchanged; `merged` changed it; `refused`
 // is the guard's answer, nothing attempted; `conflict` names the paths git left unmerged, so a resumed
 // session goes straight to them instead of asking git again.
@@ -65,7 +70,7 @@ interface MergeTarget {
 
 // A failure that left no unmerged path — a remote that cannot be reached, a hook that refused — is not
 // a conflict, so it is rethrown rather than reported as one with nothing to resolve. A conflict only on
-// generated files is regenerated and committed (`main-merge-regenerate.ts`), so it answers `undefined`
+// the files `main-merge-regenerate.ts` resolves is resolved and committed, so it answers `undefined`
 // and the merge reads as finished.
 async function unresolved_conflict(error: unknown): Promise<MergeOutcome | undefined> {
 	const files = main_merge_guard.unmerged_paths(await git_command.status())
@@ -89,6 +94,32 @@ async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
 	return { kind: target.is_current ? 'current' : 'merged', branch: default_branch }
 }
 
+// joshuafolkken/kit#4777: a merge that brings in a lockfile change leaves `node_modules` on the old
+// one, so the next check fails on files this branch never touched. Only a finished merge installs — a
+// conflict or a refusal changed no dependency yet. A failed install does not fail the merge; it says
+// the install is still owed, with pnpm's output. A throw is caught for the same reason: the merge is
+// already committed, so `josh ship` must not read it as refused.
+async function install_failure(): Promise<string | undefined> {
+	try {
+		const result = await lane_install.install_dependencies(await git_command.repository_root())
+
+		return result.is_installed ? undefined : result.output
+	} catch (error) {
+		return error_text.message_of(error)
+	}
+}
+
+async function install_merged_lockfile(
+	outcome: MergeOutcome,
+	incoming: ReadonlyArray<string>,
+): Promise<void> {
+	if (outcome.kind !== 'merged' || !incoming.includes(LOCKFILE)) return
+
+	const failure = await install_failure()
+
+	if (failure !== undefined) console.warn(`${INSTALL_OWED}\n${failure}`)
+}
+
 // The fetch is what makes `origin/<default>` current before the merge reads it. `git pull` did the
 // two together, which is the only thing it was doing here that is worth keeping. The refusal is read
 // after the fetch, so the incoming paths are the ones the merge would bring in.
@@ -104,14 +135,22 @@ async function merge(): Promise<MergeOutcome> {
 
 	if (message !== undefined) return { kind: 'refused', message }
 
-	return await merge_into({ default_branch, current_branch, is_current: incoming.length === 0 })
+	const outcome = await merge_into({
+		default_branch,
+		current_branch,
+		is_current: incoming.length === 0,
+	})
+
+	await install_merged_lockfile(outcome, incoming)
+
+	return outcome
 }
 
 // A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
 // the sanctioned commit rather than a request for `git add`.
 function failure_text(outcome: MergeOutcome): string | undefined {
 	if (outcome.kind === 'refused') return outcome.message
-	if (outcome.kind === 'conflict') return main_merge_guard.CONFLICT_HINT
+	if (outcome.kind === 'conflict') return main_merge_guard.conflict_hint()
 
 	return undefined
 }
@@ -121,9 +160,18 @@ function failure_text(outcome: MergeOutcome): string | undefined {
 // advisory: a finished merge never fails on it, and an unreadable diff says so rather than reading as
 // under the guide. It sits on the command, not on `merge()`, because `josh ship` merges again past the
 // point a run can act on it.
+async function measured_notice(): Promise<string | undefined> {
+	const measurement = await split_measure.read_branch()
+	const notice = split_assess.notice(measurement)
+
+	if (notice !== undefined) await split_early_notice.record(measurement)
+
+	return notice
+}
+
 async function split_notice(): Promise<string | undefined> {
 	try {
-		return split_assess.notice(await split_measure.read_branch())
+		return await measured_notice()
 	} catch (error) {
 		return `${SPLIT_UNMEASURED}: ${error_text.message_of(error)}`
 	}

package/scripts/git/no-base-checkout.ts

@@ -0,0 +1,127 @@
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	statSync,
+	symlinkSync,
+	writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { execa } from 'execa'
+import { changed_paths } from './changed-paths'
+import { git_command } from './git-command'
+import { git_location_environment } from './git-location-environment'
+
+// **A checkout of this tree as CI's `actions/checkout` hands it over** — a detached, depth-one `HEAD`
+// with no local default branch and no remote-tracking ref (joshuafolkken/kit#4710). Code that passes
+// `main` to git reads the local branch every lane has and passes here, then fails in CI with
+// `bad revision 'main'`; run inside this checkout, it fails here too. **The `origin` remote is kept**,
+// as CI keeps it: code that reads the repository's owner from it reads it here too
+// (joshuafolkken/kit#4738).
+//
+// **No object is copied**: the objects are borrowed through `objects/info/alternates`, and only the
+// tree is checked out. The work in progress is copied over it, and `node_modules` is linked, so the
+// tests read what the lane's own run reads.
+
+const CHECKOUT_PREFIX = 'josh-no-base-'
+const NODE_MODULES = 'node_modules'
+const ORIGIN_URL_KEY = 'remote.origin.url'
+
+// Cleared rather than inherited: under a git hook `GIT_DIR` beats `cwd`, and every command here must
+// act on the new checkout.
+async function git(cwd: string, arguments_: ReadonlyArray<string>): Promise<string> {
+	const { stdout } = await execa('git', arguments_, {
+		cwd,
+		env: git_location_environment.location_free_environment(),
+		extendEnv: true,
+	})
+
+	return stdout.trim()
+}
+
+// A file the work deleted is deleted from the checkout too. A directory git names as one path — a
+// nested repository, a submodule — is not the work's to copy.
+function copy_work(root: string, directory: string, file: string): void {
+	const source = path.join(root, file)
+	const target = path.join(directory, file)
+
+	if (!existsSync(source)) {
+		rmSync(target, { force: true })
+
+		return
+	}
+
+	if (statSync(source).isDirectory()) return
+
+	mkdirSync(path.dirname(target), { recursive: true })
+	copyFileSync(source, target)
+}
+
+async function borrow_objects(root: string, directory: string): Promise<void> {
+	const common = await git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+	const alternates = path.join(directory, '.git', 'objects', 'info', 'alternates')
+
+	writeFileSync(alternates, `${path.join(common, 'objects')}\n`)
+}
+
+// The remote is declared and never fetched, so it names the repository without bringing a
+// remote-tracking ref along. A repository with no `origin` hands none over. Written with `git config`
+// rather than `git remote add`, which the unit suite's network guard refuses whole.
+async function add_origin(root: string, directory: string): Promise<void> {
+	const origin_url = repo_discovery.read_origin_url(root)
+
+	if (origin_url !== undefined) await git(directory, ['config', ORIGIN_URL_KEY, origin_url])
+}
+
+function link_dependencies(root: string, directory: string): void {
+	const source = path.join(root, NODE_MODULES)
+
+	if (existsSync(source)) symlinkSync(source, path.join(directory, NODE_MODULES))
+}
+
+// `root` is the repository the checkout is cut from; the work in progress is read from the process's
+// own repository, which is the same one wherever `josh test:related` calls this.
+async function check_out(root: string, directory: string, head: string): Promise<void> {
+	await git(directory, ['init', '--quiet'])
+	await add_origin(root, directory)
+	await borrow_objects(root, directory)
+	await git(directory, ['checkout', '--quiet', '--detach', head])
+	writeFileSync(path.join(directory, '.git', 'shallow'), `${head}\n`)
+}
+
+async function fill(root: string, directory: string): Promise<void> {
+	const head = await git_command.head_commit()
+
+	await check_out(root, directory, head)
+	link_dependencies(root, directory)
+
+	const work = await changed_paths.read_changed_since(head)
+
+	for (const file of work) copy_work(root, directory, file)
+}
+
+function remove(directory: string): void {
+	rmSync(directory, { force: true, recursive: true })
+}
+
+// A checkout that could not be finished is removed before the failure is passed on.
+async function create(root: string): Promise<string> {
+	const directory = mkdtempSync(path.join(tmpdir(), CHECKOUT_PREFIX))
+
+	try {
+		await fill(root, directory)
+	} catch (error) {
+		remove(directory)
+		throw error
+	}
+
+	return directory
+}
+
+const no_base_checkout = { create, remove }
+
+export { no_base_checkout }

package/scripts/git/stash/git-stash.ts

@@ -88,12 +88,20 @@ async function pop(selector: string, directory?: string): Promise<void> {
 // — the resume path documented in `backlogrun-park.md` ("expect to resolve conflicts"). The non-zero
 // exit is indistinguishable from a real failure by its code alone, so a conflicted pop is told apart
 // by the unmerged paths it leaves: `--diff-filter=U` lists exactly those, empty on any other failure.
-async function has_conflict(directory?: string): Promise<boolean> {
+// Read from git rather than parsed from a status string (`main_merge_guard.unmerged_paths`), since a
+// stash caller holds a directory, not a status.
+async function unmerged_paths(directory?: string): Promise<Array<string>> {
 	const unmerged = await git_spawn.read(
 		git_args(directory, ['diff', NAME_ONLY_FLAG, '--diff-filter=U']),
 	)
 
-	return unmerged !== ''
+	return unmerged.split('\n').filter((line) => line !== '')
+}
+
+async function has_conflict(directory?: string): Promise<boolean> {
+	const unmerged = await unmerged_paths(directory)
+
+	return unmerged.length > 0
 }
 
 // Uncommitted work is anything `git status --porcelain` lists — untracked files included, which is what
@@ -211,6 +219,7 @@ const git_stash = {
 	push,
 	select,
 	STASHABLE_PATHSPEC,
+	unmerged_paths,
 	work_message,
 }
 

package/scripts/git/stash/stash-push-cli.ts

@@ -1,3 +1,4 @@
+import { main_merge_guard } from '#scripts/git/main-merge-guard'
 import { error_text } from '#scripts/lib/error-message'
 import { git_stash } from './git-stash'
 import { stash_args, type Request } from './stash-args'
@@ -16,6 +17,7 @@ import { stash_args, type Request } from './stash-args'
 // can call it unconditionally and pop only after `stashed`.
 
 const COMMAND = 'stash:push'
+const STASH_RERUN = 'the command that stashed (`run:pause`, `stash:push`, `latest:if-required`)'
 
 const STASHED_VERDICT = 'stashed'
 const CLEAN_VERDICT = 'clean'
@@ -40,7 +42,15 @@ type PushVerdict = typeof STASHED_VERDICT | typeof CLEAN_VERDICT
 
 // The decision and the push without the printing, so a caller that chains a pop on `stashed`
 // (`josh latest:if-required`) reads the verdict instead of parsing stdout.
+// An index with unresolved paths is refused before the push: `git stash` cannot set them aside, and
+// the way out is closing the merge, not a stash (joshuafolkken/kit#4769).
 async function set_aside(request: Request): Promise<PushVerdict> {
+	const unmerged = await git_stash.unmerged_paths(request.dir)
+
+	if (unmerged.length > 0) {
+		throw new Error(main_merge_guard.unresolved_message(COMMAND, unmerged, STASH_RERUN))
+	}
+
 	if (!(await git_stash.has_stashable_changes(request.dir))) return CLEAN_VERDICT
 
 	await git_stash.push(request.message, request.dir, git_stash.STASHABLE_PATHSPEC)

package/scripts/hooks/batch-guard.ts

@@ -1,4 +1,5 @@
-import { hook_decision } from '#scripts/josh/hook-decision'
+import { will_refuse as will_investigation_refuse } from '#scripts/delegation/investigation-guard'
+import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
 import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
 import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 
@@ -40,29 +41,39 @@ function is_batch_candidate(call: GuardedCall): boolean {
 
 // **How the batching guard behaves for the session in hand, decided from the one-place enumeration**.
 // Outside a lane child the mode is `refuse` and the guard is exactly what it always was; in a dispatched
-// lane child it is `notice` — kit#2178 took it to `off` after kit#2164's generic notice did not move the
-// density, and kit#2276 restores it as a notice that names the concrete recent calls and recurs every
-// single-call turn, the two things #2164's notice lacked, so the density can be re-measured with the
-// notice actually firing where it is measured. The wrappers below are three-valued so this needs no
-// change beyond the enumeration. The enumeration reads `is_child_of` — the dispatch mark against this
-// checkout's own issue — only for a guard whose mode it would actually change, so a person working in a
-// lane sees the guard unchanged.
+// lane child the general rule is `off` and only the `search-batching` row still refuses — a chain of
+// searches issued one per turn, the largest share of the child's single-call pairs (kit#5342). The
+// enumeration reads `is_child_of` — the dispatch mark against this checkout's own issue — only for a
+// guard whose mode it would actually change, so a person working in a lane sees the guard unchanged.
 function batching_mode(): LaneGuardMode {
 	return lane_guard_policy.mode_here('batching')
 }
 
-// A guard the enumeration turns fully `off` says nothing at all. The lane-child mode and its reason
-// live in `lane-guard-policy.ts`; on the main line the mode is `refuse`.
+function is_search_refused_here(): boolean {
+	return lane_guard_policy.mode_here('search-batching') === 'refuse'
+}
+
+// Where the general rule is `off`, only a search the narrower refusal judges is read for. The
+// lane-child modes and their reasons live in `lane-guard-policy.ts`; on the main line both are `refuse`.
 function is_candidate(call: GuardedCall): boolean {
-	return is_batch_candidate(call) && batching_mode() !== 'off'
+	if (batching_mode() !== 'off') return is_batch_candidate(call)
+
+	return is_search_refused_here() && time_batch_guard.is_search_chain_call(call)
 }
 
-// A refusable call is refused only where the mode is `refuse`. Under any other mode it is withheld the
-// refusal; why a lane child takes that mode is its `because` in `lane-guard-policy.ts`.
-function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
-	if (batching_mode() !== 'refuse') return false
+// A refusable call is refused only where the mode is `refuse`; elsewhere a search chain alone is, under
+// the `search-batching` row, standing aside for the investigation guard's refusal of the same call.
+// Why a lane child takes each mode is its `because` in `lane-guard-policy.ts`.
+function should_block_here(
+	tail: string,
+	call: GuardedCall,
+	refused_at_ms: number,
+	run: GuardRun,
+): boolean {
+	if (batching_mode() === 'refuse') return time_batch_guard.should_block(tail, call, refused_at_ms)
+	if (!is_search_refused_here() || will_investigation_refuse(tail, call, run)) return false
 
-	return time_batch_guard.should_block(tail, call, refused_at_ms)
+	return time_batch_guard.should_block_search_chain(tail, call, refused_at_ms)
 }
 
 // The whole-file write earns a notice on every run. The second branch turns a
@@ -81,9 +92,8 @@ function should_notify_here(tail: string, call: GuardedCall, notified_at_ms: num
 }
 
 // The wording each notice carries, with the concrete calls the run just issued one-per-turn appended.
-// The whole-file write keeps its own base text; the lane notice is reached
-// under the `notice`-mode guard batching takes in a lane child again since kit#2276, so a headless
-// child is shown *which* recent calls it could have batched rather than only told to batch.
+// The whole-file write keeps its own base text; the lane notice is reached only under a `notice`-mode
+// batching row, so a headless child would be shown *which* recent calls it could have batched.
 function notice_text(call: GuardedCall, tail: string): string {
 	const base = time_batch_guard.is_notice_call(call)
 		? time_batch_guard.NOTICE
@@ -99,8 +109,7 @@ const GUARD = hook_decision.create_transcript_guard({
 	should_block: should_block_here,
 	reason: time_batch_guard.REASON,
 	// The whole-file write is notified rather than refused, on a record of its own so it never spends
-	// the refusal's stamp; the lane-child refusable-call notice kit#2164 added
-	// here fires again since kit#2276 restored batching to `notice` in a lane child.
+	// the refusal's stamp; the refusable-call notice fires only under a `notice`-mode batching row.
 	notify: {
 		prefix: time_batch_guard.NOTICE_STAMP_PREFIX,
 		should_notify: should_notify_here,
@@ -117,6 +126,15 @@ const notice_refusal_path = hook_decision.create_refusal_stamp(
 	time_batch_guard.NOTICE_STAMP_PREFIX,
 ).path
 const { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision
+const STAMP = hook_decision.create_refusal_stamp(time_batch_guard.STAMP_PREFIX)
+
+// Whether this guard refuses the call in hand, asked with its real record — the rule guard stands
+// aside for it, so the two never decide apart.
+function will_refuse(tail: string, call: GuardedCall, run: GuardRun): boolean {
+	if (!is_enabled() || !is_candidate(call)) return false
+
+	return should_block_here(tail, call, STAMP.last_ms(STAMP.path(run.transcript)), run)
+}
 
 export {
 	batch_outcome,
@@ -126,6 +144,7 @@ export {
 	load_environment_file,
 	notice_refusal_path,
 	refusal_path,
+	will_refuse,
 	DISABLED_VALUES,
 	SWITCH_ENV_KEY,
 }

package/scripts/hooks/edited-cspell.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { resolve_local_bin } from '#scripts/build/local-bin'
 import { HOOK_PROCESS_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
@@ -38,15 +39,28 @@ const CSPELL_EXTENSIONS: ReadonlySet<string> = new Set([
 // exit code is ignored: cspell exits non-zero precisely when it found words, which is the case this
 // exists for.
 const CSPELL_ARGS: ReadonlyArray<string> = [
-	'exec',
-	'cspell',
 	'lint',
 	'--words-only',
 	'--unique',
 	'--no-progress',
 	'--no-summary',
 ]
+const CSPELL_BIN = 'cspell'
 const PNPM = 'pnpm'
+// The text arrives on stdin under the edited file's own name, so the project config — its ignore
+// list, its language per extension, its overrides — applies exactly as it does to the path. Reading
+// stdin rather than the file is what lets the check run beside the formatters
+// (joshuafolkken/kit#4596): they rewrite the file while it runs, and a read caught mid-write would
+// report on a truncated file.
+const STDIN_SCHEME = 'stdin://'
+
+interface CspellRequest {
+	file_path: string
+	project_root: string
+	text: string
+}
+
+type CspellRunner = (request: CspellRequest) => Promise<string>
 
 const HEADER =
 	'The edit hook found words cspell does not know; fix them or add them to `cspell.config.yaml` now rather than at the gate:'
@@ -54,8 +68,6 @@ const HEADER =
 const MAX_DIAGNOSTIC_CHARS = 4000
 const TRUNCATION_NOTICE = '\n…(unknown words truncated)'
 
-type CspellRunner = (file_path: string, project_root: string) => Promise<string>
-
 // One question before a process starts: is this a file under the project that spell-checking has
 // anything to say about?
 function is_checkable(file_path: string, project_root: string): boolean {
@@ -68,12 +80,24 @@ function is_checkable(file_path: string, project_root: string): boolean {
 	return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
 }
 
+// The project's own shim, spawned directly: `pnpm exec` costs a second process start on every edit,
+// and this check was the largest step of the edit hook (joshuafolkken/kit#4596). `pnpm exec` stays as
+// the route for a project whose binaries live somewhere other than the root's `node_modules/.bin`.
+function cspell_command(project_root: string): ReadonlyArray<string> {
+	const shim = resolve_local_bin(project_root, CSPELL_BIN)
+
+	return existsSync(shim) ? [shim] : [PNPM, 'exec', CSPELL_BIN]
+}
+
 // The live runner. `reject: false` because a non-zero exit is the ordinary way cspell reports words,
 // and stderr is ignored so a config note never reaches the model as if it were an unknown word.
-async function run_cspell(file_path: string, project_root: string): Promise<string> {
-	const result = await execa(PNPM, [...CSPELL_ARGS, file_path], {
+async function run_cspell(request: CspellRequest): Promise<string> {
+	const [bin = PNPM, ...prefix] = cspell_command(request.project_root)
+	const target = `${STDIN_SCHEME}${path.resolve(request.file_path)}`
+	const result = await execa(bin, [...prefix, ...CSPELL_ARGS, target], {
 		reject: false,
-		cwd: project_root,
+		cwd: request.project_root,
+		input: request.text,
 		stdout: 'pipe',
 		stderr: 'ignore',
 		timeout: HOOK_PROCESS_TIMEOUT_MS,
@@ -104,22 +128,24 @@ function format_unknown_words(stdout: string): string | undefined {
 
 // Never turns a successful edit into a failure: a runner that throws — cspell missing, a timeout — is
 // swallowed and reported as nothing to say, exactly as the lint half swallows a formatter that could
-// not start.
+// not start. `text` is the file's content as the caller read it, so the check does not depend on when
+// it runs against the formatters.
 async function spelling_diagnostics(
 	file_path: string | undefined,
 	project_root: string,
+	text: string,
 	runner: CspellRunner = run_cspell,
 ): Promise<string | undefined> {
 	if (file_path === undefined || !is_checkable(file_path, project_root)) return undefined
 
 	try {
-		return format_unknown_words(await runner(file_path, project_root))
+		return format_unknown_words(await runner({ file_path, project_root, text }))
 	} catch {
 		return undefined
 	}
 }
 
-const edited_cspell = { format_unknown_words, spelling_diagnostics }
+const edited_cspell = { cspell_command, format_unknown_words, run_cspell, spelling_diagnostics }
 
-export type { CspellRunner }
+export type { CspellRequest, CspellRunner }
 export { edited_cspell, MAX_DIAGNOSTIC_CHARS }