@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,4 +1,5 @@
 import { git_spawn } from '#scripts/git/git-spawn'
+import { LEDGER_EXCLUSION_PATHSPEC } from '#scripts/observations/observation-ledger'
 
 // The one place a sanctioned `git stash pop` is targeted by its message rather than its stack
 // position. The stash is a single repository-wide stack shared by every
@@ -87,24 +88,52 @@ 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
 // `push` below carries with `-u`, so the two agree on what "work" means.
-async function has_changes(directory?: string): Promise<boolean> {
-	return (await git_spawn.read(git_args(directory, ['status', '--porcelain']))) !== ''
+// A `pathspec` narrows both to the same paths, so a push never finds nothing where this found work.
+async function has_changes(
+	directory?: string,
+	pathspec: ReadonlyArray<string> = [],
+): Promise<boolean> {
+	const status = await git_spawn.read(git_args(directory, ['status', '--porcelain', ...pathspec]))
+
+	return status !== ''
+}
+
+// What `josh stash:push` sets aside: everything but the observation ledger, whose lines ride on the
+// run's own commit (`stash-push-cli.ts`).
+const STASHABLE_PATHSPEC: ReadonlyArray<string> = ['--', ...LEDGER_EXCLUSION_PATHSPEC]
+
+// Whether `josh stash:push` would push anything — the question to ask before telling someone to run it,
+// so a ledger-only tree is never sent to a push that answers `clean`.
+async function has_stashable_changes(directory?: string): Promise<boolean> {
+	return await has_changes(directory, STASHABLE_PATHSPEC)
 }
 
 // Push with a message `josh stash:pop` can later target — the stack is shared by every work tree, so an
 // entry pushed from a lane outlives the lane's own tree.
-async function push(message: string, directory?: string): Promise<void> {
-	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message]))
+async function push(
+	message: string,
+	directory?: string,
+	pathspec: ReadonlyArray<string> = [],
+): Promise<void> {
+	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message, ...pathspec]))
 }
 
 // The stack keyed by commit rather than position: a sweep that reads the
@@ -181,6 +210,7 @@ const git_stash = {
 	drop_by_hash,
 	has_changes,
 	has_conflict,
+	has_stashable_changes,
 	list,
 	list_by_hash,
 	matches,
@@ -188,6 +218,8 @@ const git_stash = {
 	pop,
 	push,
 	select,
+	STASHABLE_PATHSPEC,
+	unmerged_paths,
 	work_message,
 }
 

package/scripts/git/stash/{stash-pop-args.ts → stash-args.ts}

@@ -1,13 +1,12 @@
 import { cli_flags } from '#scripts/lib/cli-flags'
 
-// `josh stash:pop` turns its `argv` into a single request: the message of the stash to pop. Parsing
-// lives here, acting on the stack lives in `stash-pop-cli.ts`, and a malformed command line is
-// `undefined` rather than a guessed intent — a pop run on a misread argument would take the wrong
-// entry off a stack shared by every lane.
+// `josh stash:push` and `josh stash:pop` turn their `argv` into a single request: the message of the
+// stash to push or pop. Parsing lives here, acting on the stack lives in each command's cli, and a
+// malformed command line is `undefined` rather than a guessed intent — a pop run on a misread argument
+// would take the wrong entry off a stack shared by every lane, and a push without its message would
+// leave an entry nothing can target.
 
-const USAGE = 'Usage: josh stash:pop "<message>" [--dir <path>]'
-
-// `--dir` points the pop at a lane's work tree; without it the pop lands in the current checkout.
+// `--dir` points the command at a lane's work tree; without it, it acts on the current checkout.
 const OPTIONS = { dir: { type: 'string' } } as const
 
 interface ParsedValues {
@@ -20,12 +19,16 @@ interface Request {
 	dir: string | undefined
 }
 
+function usage(command: string): string {
+	return `Usage: josh ${command} "<message>" [--dir <path>]`
+}
+
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
 	return cli_flags.arguments_of(argv, OPTIONS)
 }
 
 // The message is the sole positional and must be a non-empty string: an empty message matches every
-// stash pushed without a message, which is exactly the ambiguity this command exists to refuse.
+// stash pushed without a message, which is exactly the ambiguity `stash:pop` exists to refuse.
 function message_of(positionals: ReadonlyArray<string>): string | undefined {
 	if (positionals.length !== 1) return undefined
 
@@ -42,7 +45,7 @@ function to_request(parsed: ParsedValues): Request | undefined {
 	return { message, dir: parsed.values.dir }
 }
 
-const stash_pop_args = { USAGE, read_arguments, to_request }
+const stash_args = { read_arguments, to_request, usage }
 
 export type { Request }
-export { stash_pop_args }
+export { stash_args }

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

@@ -1,7 +1,6 @@
-import { fileURLToPath } from 'node:url'
 import { error_text } from '#scripts/lib/error-message'
 import { git_stash } from './git-stash'
-import { stash_pop_args, type Request } from './stash-pop-args'
+import { stash_args, type Request } from './stash-args'
 
 // `josh stash:pop "<message>"` — pop the stash whose message matches, and no other.
 // The stash stack is shared by every working tree of the repository, so a
@@ -9,6 +8,8 @@ import { stash_pop_args, type Request } from './stash-pop-args'
 // selector from the message and pops that entry alone; no match and more than one match are both
 // refusals rather than a guess at which was meant.
 
+const COMMAND = 'stash:pop'
+
 const POPPED_VERDICT = 'popped'
 const CONFLICTED_VERDICT = 'conflicted'
 const NO_MATCH_VERDICT = 'no-match'
@@ -16,7 +17,6 @@ const AMBIGUOUS_VERDICT = 'ambiguous'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 
 function report(verdict: string, detail: string, code: number): number {
 	console.info(verdict)
@@ -26,7 +26,7 @@ function report(verdict: string, detail: string, code: number): number {
 }
 
 function refuse(): number {
-	console.error(stash_pop_args.USAGE)
+	console.error(stash_args.usage(COMMAND))
 
 	return FAILURE_EXIT_CODE
 }
@@ -73,11 +73,11 @@ function report_unknown(error: unknown): number {
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const parsed = stash_pop_args.read_arguments(argv)
+	const parsed = stash_args.read_arguments(argv)
 
 	if (parsed === undefined) return refuse()
 
-	const request = stash_pop_args.to_request(parsed)
+	const request = stash_args.to_request(parsed)
 
 	if (request === undefined) return refuse()
 
@@ -88,10 +88,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const stash_pop_cli = {
 	AMBIGUOUS_VERDICT,
 	CONFLICTED_VERDICT,
@@ -100,6 +96,4 @@ const stash_pop_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { stash_pop_cli }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { stash_pop_cli } from './stash-pop-cli'
+
+// The `josh stash:pop` entry, kept apart from `stash-pop-cli.ts` because `latest-if-required-cli.ts`
+// imports that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await stash_pop_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -0,0 +1,86 @@
+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'
+
+// `josh stash:push "<message>"` — the one way a workflow sets its working tree aside, paired with
+// `josh stash:pop "<message>"` that brings it back. Two rules fix what it takes:
+//
+// - **Untracked files go with it (`-u`).** Work in progress almost always includes a new, untracked
+//   `*.test.ts`; a stash that leaves it behind leaves it for the next `pnpm josh ms` to refuse.
+// - **The observation ledger stays** — every path `observation_ledger.is_ledger_path` names, legacy
+//   ones included (`git_stash.STASHABLE_PATHSPEC`). A run appends its own lines to `.josh/observations/` and they
+//   ride on that run's commit; a stash would take them off the tree before the commit or the
+//   batch-end flush could see them.
+//
+// A tree with nothing outside the ledger to set aside pushes nothing and says `clean`, so a procedure
+// 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'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+function report(verdict: string, detail: string): number {
+	console.info(verdict)
+	console.error(detail)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function refuse(): number {
+	console.error(stash_args.usage(COMMAND))
+
+	return FAILURE_EXIT_CODE
+}
+
+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)
+
+	return STASHED_VERDICT
+}
+
+async function answer(request: Request): Promise<number> {
+	if ((await set_aside(request)) === CLEAN_VERDICT) {
+		return report(CLEAN_VERDICT, 'Nothing to stash.')
+	}
+
+	return report(STASHED_VERDICT, `Stashed as "${request.message}".`)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = stash_args.read_arguments(argv)
+	const request = parsed === undefined ? undefined : stash_args.to_request(parsed)
+
+	if (request === undefined) return refuse()
+
+	try {
+		return await answer(request)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+const stash_push_cli = { CLEAN_VERDICT, STASHED_VERDICT, run, set_aside }
+
+export { stash_push_cli }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { stash_push_cli } from './stash-push-cli'
+
+// The `josh stash:push` entry, kept apart from `stash-push-cli.ts` because `run-pause.ts` and
+// `latest-if-required-cli.ts` import that one: a bundle is one file, so a main guard there would fire
+// for every command that carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await stash_push_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/hooks/batch-guard.ts

@@ -1,7 +1,5 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
-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'
 
@@ -43,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
@@ -84,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
@@ -102,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,
@@ -120,10 +126,14 @@ 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
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('batch:guard')
-	else hook_decision.write_outcome(await text(process.stdin), batch_outcome)
+	return should_block_here(tail, call, STAMP.last_ms(STAMP.path(run.transcript)), run)
 }
 
 export {
@@ -134,6 +144,7 @@ export {
 	load_environment_file,
 	notice_refusal_path,
 	refusal_path,
+	will_refuse,
 	DISABLED_VALUES,
 	SWITCH_ENV_KEY,
 }

package/scripts/hooks/check-commit-message-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_check } from './check-commit-message'
+
+// The `josh check-commit-message` entry, kept apart from `check-commit-message.ts` because
+// `main-merge.ts` imports that one: a bundle is one file, so a main guard there would fire for every
+// command that carries it (joshuafolkken/kit#4186). The message file is read from `process.argv`.
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = await run_check()

package/scripts/hooks/check-commit-message.ts

@@ -1,8 +1,6 @@
-#!/usr/bin/env tsx
 import { readFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
 import { issue_cite } from '#scripts/issue/issue-cite'
 
@@ -122,16 +120,15 @@ async function check_commit_message(): Promise<CheckResult> {
 	}
 }
 
-async function main(): Promise<void> {
+// The `commit-msg` hook's run: the check's message, and a failure exit when it refused.
+async function run_check(): Promise<number> {
 	const result = await check_commit_message()
 
 	console.info(result.message)
 
-	if (!result.success) process.exit(1)
+	return result.success ? 0 : 1
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-export { check_commit_message, extract_issue_number, is_safe_commit_message_path }
+export { check_commit_message, extract_issue_number, is_safe_commit_message_path, run_check }
 
 export type { CheckResult }

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 }