@joshuafolkken/kit 1.921.0 → 1.947.0

package/scripts/git/stash-orphans.ts

@@ -13,7 +13,11 @@ import type { StashEntry } from './git-stash'
 // opens with `N: ` is `git_stash.work_message`'s; and a lane branch (`On N-lane: …`) names it by where
 // the work was pushed from. A subject is `On <branch>: <message>` (or `WIP on <branch>: …` without
 // `-m`), and a branch name carries no `:`, so `(?:^|: )` anchors the message start either way.
-const MESSAGE_PATTERNS: ReadonlyArray<RegExp> = [/#(?<issue>\d+)\b/u, /(?:^|: )(?<issue>\d+): /u]
+const HASH_PATTERN = /#(?<issue>\d+)\b/u
+const LEADING_PATTERN = /(?:^|: )(?<issue>\d+): /u
+const MESSAGE_PATTERNS: ReadonlyArray<RegExp> = [HASH_PATTERN, LEADING_PATTERN]
+// Every `#N` in the message rather than the first, for `issues_named`.
+const ALL_ISSUE_PATTERN = new RegExp(HASH_PATTERN.source, 'gu')
 const BRANCH_PATTERN = /^(?:WIP on|On) (?<issue>\d+)-lane: /u
 // A stash pushed without `-m` lists as `WIP on <branch>: <sha> <HEAD's commit subject>` — text no run
 // wrote. This repository's commit subjects end in `#N` and merges read `Merge pull request #N`, so a
@@ -61,6 +65,24 @@ function issues_of(entries: ReadonlyArray<StashEntry>): Array<string> {
 	return [...new Set(issues.filter((issue): issue is string => issue !== undefined))]
 }
 
+function message_issues(subject: string): Array<string | undefined> {
+	const hashed = [...subject.matchAll(ALL_ISSUE_PATTERN)].map((match) => match.groups?.['issue'])
+
+	return [...hashed, LEADING_PATTERN.exec(subject)?.groups?.['issue']]
+}
+
+// Every issue a subject names, not just its owner (joshuafolkken/kit#2701): `backlogrun: paused #M for
+// prerequisite #N` is tied to both, and the `#N` of a `run:hold reclaimed before #N` entry — which
+// `issue_of` reads as no owner — still names the run the work was found by. A `WIP on` subject is
+// read by its branch alone, for the reason `WIP_PREFIX` records.
+function issues_named(subject: string): Array<string> {
+	const branch = BRANCH_PATTERN.exec(subject)?.groups?.['issue']
+	const named = subject.startsWith(WIP_PREFIX) ? [] : message_issues(subject)
+	const found = [...named, branch].filter((issue): issue is string => issue !== undefined)
+
+	return [...new Set(found)]
+}
+
 // An entry is reported when its issue is in `closed`, or when it names no issue at all — an entry with
 // no owner is exactly the one no run will ever pop. An open issue's entry is still some run's to resume.
 function orphans(
@@ -85,7 +107,7 @@ function format_report(found: ReadonlyArray<OrphanStash>): string | undefined {
 	return [HEADER, ...found.map((orphan) => format_line(orphan)), FOOTER].join(LINE_SEPARATOR)
 }
 
-const stash_orphans = { format_report, issue_of, issues_of, orphans }
+const stash_orphans = { format_report, issue_of, issues_named, issues_of, orphans }
 
 export type { OrphanStash }
 export { stash_orphans }

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

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto'
+import { linkSync, renameSync, rmSync } from 'node:fs'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { git_common_directory } from './git-common-directory'
+
+// One stash sweep at a time per repository (joshuafolkken/kit#2701). The stash is a single stack every
+// work tree shares, and a `backlogrun` runs one sweep per lane seat at once: two sweeps that each
+// resolve the same entry to `stash@{n}` and drop it would have the second drop land on whichever entry
+// moved into that position, and two that carry the same ledger lines would both append them. The lock
+// is keyed on the git common directory, so every work tree of one repository contends for one record.
+
+const LOCK_PREFIX = 'josh-stash-sweep-lock-'
+// The locked phase is local git and one file append per entry, so a holder finishes in well under the
+// wait; the cap only bounds a holder that hung, and a sweep that gives up keeps its entries.
+const POLL_INTERVAL_MS = 200
+const MAX_WAIT_MS = 30_000
+
+interface LockOwner {
+	pid: number
+	process_start?: string
+}
+
+function lock_path(cwd: string = process.cwd()): string {
+	return stamp_file.stamp_path(LOCK_PREFIX, git_common_directory.repository(cwd) ?? cwd)
+}
+
+type IsGone = (owner: LockOwner) => boolean
+
+function parse_owner(raw: string | undefined): LockOwner | undefined {
+	if (raw === undefined) return undefined
+
+	try {
+		return JSON.parse(raw) as LockOwner
+	} catch {
+		return undefined
+	}
+}
+
+function read_owner(target: string): LockOwner | undefined {
+	return parse_owner(stamp_file.read_stamp_text(target))
+}
+
+function is_owner_gone(owner: LockOwner): boolean {
+	return process_identity.is_same_process(owner.pid, owner.process_start) === false
+}
+
+// Put back a record that turned out not to be the stale one. `linkSync` refuses an existing path, so
+// a lock someone claimed in the meantime is never overwritten.
+function restore(aside: string, target: string): void {
+	try {
+		linkSync(aside, target)
+	} catch {
+		// Another claim already holds the path; the record set aside is dropped below.
+	}
+}
+
+// The record's text when its owner is certainly gone, else `undefined`.
+function stale_record(target: string, is_gone: IsGone): string | undefined {
+	const raw = stamp_file.read_stamp_text(target)
+	const owner = parse_owner(raw)
+
+	return owner !== undefined && is_gone(owner) ? raw : undefined
+}
+
+// The path the record was moved to, or `undefined` when another sweep moved it first.
+function move_aside(target: string): string | undefined {
+	const aside = `${target}.${String(process.pid)}.${randomUUID()}`
+
+	try {
+		renameSync(target, aside)
+
+		return aside
+	} catch {
+		return undefined
+	}
+}
+
+// A record whose process is certainly gone is a crashed sweep's, and is cleared before the claim; an
+// unreadable record or an uncertain answer is left in place, since clearing a live holder's lock is the
+// very race the lock exists to close. **The clear is a rename, then a compare**: two sweeps can both
+// judge the same record stale, and the slower one's plain remove would delete the lock the faster one
+// had just claimed. Renaming moves exactly one file aside atomically, and only a record byte-identical
+// to the one judged stale is discarded — any other is a fresh claim and goes back.
+function clear_stale(target: string, is_gone: IsGone = is_owner_gone): void {
+	const raw = stale_record(target, is_gone)
+
+	if (raw === undefined) return
+
+	const aside = move_aside(target)
+
+	if (aside === undefined) return
+	if (stamp_file.read_stamp_text(aside) !== raw) restore(aside, target)
+	rmSync(aside, { force: true })
+}
+
+function claim(target: string): boolean {
+	clear_stale(target)
+
+	return stamp_file.create_stamp(target, process_identity.own_fields())
+}
+
+function release(target: string): void {
+	const owner = read_owner(target)
+
+	if (owner !== undefined && process_identity.is_own_process(owner.pid, owner.process_start)) {
+		stamp_file.remove_stamp(target)
+	}
+}
+
+async function acquire(target: string, max_wait_ms: number): Promise<boolean> {
+	const deadline = Date.now() + max_wait_ms
+
+	while (!claim(target)) {
+		if (Date.now() >= deadline) return false
+		await sleep(POLL_INTERVAL_MS)
+	}
+
+	return true
+}
+
+// Runs `work` holding the lock and answers its result, or `undefined` without running it when another
+// sweep held the lock for the whole wait.
+async function with_lock<T>(
+	work: () => Promise<T>,
+	target: string = lock_path(),
+	max_wait_ms: number = MAX_WAIT_MS,
+): Promise<T | undefined> {
+	if (!(await acquire(target, max_wait_ms))) return undefined
+
+	try {
+		return await work()
+	} finally {
+		release(target)
+	}
+}
+
+const stash_sweep_lock = { clear_stale, lock_path, with_lock }
+
+export { stash_sweep_lock }

package/scripts/hooks/stop-guard.ts

@@ -8,6 +8,7 @@ import { hook_decision } from '#scripts/josh/hook-decision'
 import { session_language } from '#scripts/josh/session-language'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { filing_cap } from '#scripts/rules/filing-cap'
+import { lane_background } from '#scripts/rules/lane-background'
 import { lane_park } from '#scripts/rules/lane-park'
 import { stop_rules, type StopContext, type StopOutcome } from '#scripts/rules/stop-rules'
 import { run_cut } from '#scripts/run/run-cut'
@@ -76,6 +77,7 @@ async function build_context(
 		headless_waiting: await run_headless.must_keep_waiting(),
 		headless_refusals: stop_rules.count_headless_refusals(tail),
 		lane_child: lane_child_marker.is_child_of(process.cwd()),
+		background_pending: lane_background.pending_background_ids(tail).length > 0,
 		session_lang: session_lang(),
 	}
 }

package/scripts/init/init-actions.ts

@@ -218,8 +218,9 @@ function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
 		build_eslint_action(),
 		build_action(
 			PRETTIER_CONFIG_JS,
-			() => init_logic.generate_prettier_config(),
-			(existing) => init_logic.merge_prettier_config(existing),
+			() =>
+				init_logic.generate_prettier_config(init_logic.detect_tailwind_stylesheet(PROJECT_ROOT)),
+			(existing) => init_logic.merge_prettier_config(existing, PROJECT_ROOT),
 		),
 		build_playwright_action(),
 		...build_config_file_actions().filter(

package/scripts/init/init-ai-copy.ts

@@ -28,7 +28,13 @@ const STATIC_AI_FILES = [
 	GIT_ATTRIBUTES,
 	CODE_OF_CONDUCT,
 	SECURITY_MD,
+	WORKSPACE_YAML,
 ]
+// A static project gets its own template for these, not kit's development copy (joshuafolkken/kit#2693).
+const STATIC_SOURCES: Readonly<Record<string, string>> = {
+	[PRETTIER_IGNORE]: 'templates/prettierignore.static',
+	[WORKSPACE_YAML]: 'templates/pnpm-workspace.static.yaml',
+}
 const GITHUB_FILES = new Set([CODE_OF_CONDUCT, SECURITY_MD])
 const STATIC_POINTER_MAPPING = { src: 'templates/cursorrules.static', dest: '.cursorrules' }
 const PULL_REQUEST_TEMPLATE = '.github/pull_request_template.md'
@@ -112,11 +118,8 @@ function did_skip_workspace_yaml_copy(source_path: string, destination_path: str
 }
 
 function did_skip_ai_file_copy(filename: string, shape?: ProjectShape): boolean {
-	const source_path = package_path(
-		filename === PRETTIER_IGNORE && shape?.profile === 'static'
-			? 'templates/prettierignore.static'
-			: filename,
-	)
+	const static_source = shape?.profile === 'static' ? STATIC_SOURCES[filename] : undefined
+	const source_path = package_path(static_source ?? filename)
 	const destination_path = path.join(PROJECT_ROOT, filename)
 
 	if (filename === WORKSPACE_YAML) {

package/scripts/init/init-logic-migrate.ts

@@ -1,3 +1,6 @@
+import { safe_chain_preinstall } from '#scripts/safe-chain/preinstall-command'
+
+const PREINSTALL_KEY = 'preinstall'
 const JF_PREFIX = 'jf-'
 const JOSH_PREFIX = 'josh '
 
@@ -47,9 +50,15 @@ function migrate_jf_value(value: string): string {
 	return `${JOSH_PREFIX}${value.slice(JF_PREFIX.length)}`
 }
 
+function migrate_script(key: string, value: string): string {
+	const migrated = migrate_jf_value(value)
+
+	return key === PREINSTALL_KEY ? safe_chain_preinstall.migrate_preinstall(migrated) : migrated
+}
+
 function apply_jf_migrations(scripts: Record<string, string>): Record<string, string> {
 	return Object.fromEntries(
-		Object.entries(scripts).map(([key, value]) => [key, migrate_jf_value(value)]),
+		Object.entries(scripts).map(([key, value]) => [key, migrate_script(key, value)]),
 	)
 }
 

package/scripts/init/init-logic-templates.ts

@@ -1,4 +1,5 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
 import { package_path } from './init-paths'
 
 const ESLINT_VANILLA = `import { create_vanilla_config } from '@joshuafolkken/kit/eslint/vanilla'
@@ -111,20 +112,38 @@ function merge_eslint_config(existing: string): string {
 	return apply_rules_template(rules_blocks.join(',\n'))
 }
 
-function generate_prettier_config(stylesheet: string = DEFAULT_TAILWIND_STYLESHEET): string {
+// The default is SvelteKit's stylesheet, and prettier-plugin-tailwindcss aborts every format when
+// the named file is missing — so it is written only for a project that has it (joshuafolkken/kit#2710).
+function detect_tailwind_stylesheet(project_root: string): string | undefined {
+	return existsSync(path.join(project_root, DEFAULT_TAILWIND_STYLESHEET))
+		? DEFAULT_TAILWIND_STYLESHEET
+		: undefined
+}
+
+function generate_prettier_config(stylesheet?: string): string {
+	const stylesheet_line = stylesheet === undefined ? '' : `\ttailwindStylesheet: '${stylesheet}',\n`
+
 	return `import { config } from '@joshuafolkken/kit/prettier'
 
 export default {
 \t...config,
-\ttailwindStylesheet: '${stylesheet}',
-}
+${stylesheet_line}}
 `
 }
 
-function merge_prettier_config(existing: string): string {
-	const match = TAILWIND_STYLESHEET_PATTERN.exec(existing)
+// A named stylesheet is kept only while it exists: kit ≤1.929 wrote the SvelteKit default into every
+// node project, and keeping that line would leave `josh sync` unable to repair the aborting format.
+function existing_stylesheet(existing: string, project_root: string): string | undefined {
+	const named = TAILWIND_STYLESHEET_PATTERN.exec(existing)?.[1]
+
+	return named !== undefined && existsSync(path.resolve(project_root, named)) ? named : undefined
+}
+
+function merge_prettier_config(existing: string, project_root: string): string {
+	const stylesheet =
+		existing_stylesheet(existing, project_root) ?? detect_tailwind_stylesheet(project_root)
 
-	return generate_prettier_config(match?.[1] ?? DEFAULT_TAILWIND_STYLESHEET)
+	return generate_prettier_config(stylesheet)
 }
 
 function generate_playwright_config(): string {
@@ -134,6 +153,7 @@ function generate_playwright_config(): string {
 const init_logic_templates = {
 	generate_eslint_config,
 	merge_eslint_config,
+	detect_tailwind_stylesheet,
 	generate_prettier_config,
 	merge_prettier_config,
 	generate_playwright_config,

package/scripts/init/init-logic-workspace.ts

@@ -42,16 +42,100 @@ function remove_deprecated_yaml_keys(content: string): string {
 	return `${result.trimEnd()}\n`
 }
 
+// pnpm 11+ writes this placeholder into `allowBuilds` for every build script it ignored, and fails
+// every later install until it is answered. `pnpm add -D @joshuafolkken/kit` before `josh init`
+// leaves one for esbuild, and the key-level merge below keeps an existing `allowBuilds` whole, so a
+// placeholder the template decides is answered here (joshuafolkken/kit#2693).
+const BUILD_PLACEHOLDER_PATTERN = /^([ \t]+)([^\s:#][^:#]*): set this to true or false$/gmu
+const TEMPLATE_BUILD_PATTERN = /^[ \t]+(?<key>[^\s:#][^:#]*):[ \t]*(?<value>true|false)\b/u
+
+function unquote(key: string): string {
+	return key.trim().replaceAll(/^['"]|['"]$/gu, '')
+}
+
+function template_build_values(template: string): Map<string, string> {
+	const lines = extract_yaml_block(template, 'allowBuilds').split('\n')
+
+	return new Map(
+		lines.flatMap((line) => {
+			const { key, value } = TEMPLATE_BUILD_PATTERN.exec(line)?.groups ?? {}
+
+			return key && value ? [[unquote(key), value] as const] : []
+		}),
+	)
+}
+
+function answer_build_placeholders(existing: string, template: string): string {
+	const values = template_build_values(template)
+
+	return existing.replaceAll(BUILD_PLACEHOLDER_PATTERN, (line, indent: string, key: string) => {
+		const value = values.get(unquote(key))
+
+		return value === undefined ? line : `${indent}${key}: ${value}`
+	})
+}
+
+const BUILD_ENTRY_KEY_PATTERN = /^[ \t]+(?<key>[^\s:#][^:#]*):/u
+
+function build_entry_key(line: string): string | undefined {
+	const key = BUILD_ENTRY_KEY_PATTERN.exec(line)?.groups?.['key']
+
+	return key === undefined ? undefined : unquote(key)
+}
+
+function build_entry_keys(block: string): Set<string> {
+	return new Set(block.split('\n').flatMap((line) => build_entry_key(line) ?? []))
+}
+
+// The key-level merge keeps an existing `allowBuilds` whole, and `pnpm add -D @joshuafolkken/kit`
+// before `josh init` always leaves one (esbuild's), so without this the template's other approvals
+// never landed and the first `pnpm install` failed on the next build script, e.g. unrs-resolver's
+// (joshuafolkken/kit#2710). Entries the project already answered keep their value.
+// Only a block mapping can take appended entry lines; a flow map (`allowBuilds: { … }`) is left whole.
+const BLOCK_MAPPING_HEADER_PATTERN = /^allowBuilds:[ \t]*(?:#[^\n]*)?(?:\n|$)/u
+const LEADING_INDENT_PATTERN = /^[ \t]+/u
+
+// Appended lines take the indent of the block's own entries: a mapping whose items start at
+// different columns is invalid YAML, so a four-space block must not gain two-space lines.
+function block_entry_indent(block: string): string | undefined {
+	const entry = block.split('\n').find((line) => build_entry_key(line) !== undefined)
+
+	return entry === undefined ? undefined : LEADING_INDENT_PATTERN.exec(entry)?.[0]
+}
+
+function reindent(line: string, indent: string | undefined): string {
+	return indent === undefined ? line : line.replace(LEADING_INDENT_PATTERN, () => indent)
+}
+
+function add_missing_build_entries(existing: string, template: string): string {
+	const block = extract_yaml_block(existing, 'allowBuilds')
+	if (!BLOCK_MAPPING_HEADER_PATTERN.test(block)) return existing
+	const present = build_entry_keys(block)
+	const indent = block_entry_indent(block)
+	const missing = extract_yaml_block(template, 'allowBuilds')
+		.split('\n')
+		.filter((line) => {
+			const key = build_entry_key(line)
+
+			return key !== undefined && !present.has(key)
+		})
+		.map((line) => reindent(line, indent))
+	if (missing.length === 0) return existing
+
+	return existing.replace(block, () => [block, ...missing].join('\n'))
+}
+
 function merge_workspace_yaml(existing: string, template: string): string {
 	if (!existing.trim()) return template
 	const normalized = existing.endsWith('\n') ? existing : `${existing}\n`
-	const without_deprecated = remove_deprecated_yaml_keys(normalized)
-	if (!without_deprecated.trim()) return template
-	const existing_keys = new Set(extract_yaml_top_level_keys(without_deprecated))
+	const answered = answer_build_placeholders(remove_deprecated_yaml_keys(normalized), template)
+	const cleaned = add_missing_build_entries(answered, template)
+	if (!cleaned.trim()) return template
+	const existing_keys = new Set(extract_yaml_top_level_keys(cleaned))
 	const new_keys = extract_yaml_top_level_keys(template).filter((k) => !existing_keys.has(k))
-	if (new_keys.length === 0) return without_deprecated
+	if (new_keys.length === 0) return cleaned
 
-	return append_user_blocks(without_deprecated, new_keys, template)
+	return append_user_blocks(cleaned, new_keys, template)
 }
 
 const init_logic_workspace = { merge_workspace_yaml }

package/scripts/init/init-logic.ts

@@ -1,5 +1,6 @@
 import { json_format } from '#scripts/config-merge/json-format'
 import { vscode_settings_schema } from '#scripts/lib/schemas'
+import { safe_chain_preinstall } from '#scripts/safe-chain/preinstall-command'
 import { distributed_paths } from './distributed-paths'
 import { init_logic_deploy_vps } from './init-logic-deploy-vps'
 import { init_logic_json_merge } from './init-logic-json-merge'
@@ -27,7 +28,7 @@ const NPMRC_LINES: ReadonlyArray<string> = [
 const CSPELL_IMPORT = '@joshuafolkken/kit/cspell'
 
 const LEFTHOOK_INSTALL_CMD = 'lefthook install'
-const SAFE_CHAIN_CMD = 'pnpm dlx @aikidosec/safe-chain setup-ci'
+const { SAFE_CHAIN_CMD } = safe_chain_preinstall
 const FIX_GH_PACKAGES_CMD = 'tsx node_modules/@joshuafolkken/kit/scripts/gh/fix-gh-packages.ts'
 // Marker identifying a consumer script that already runs the fix-gh-packages command.
 const FIX_GH_PACKAGES_MARKER = 'fix-gh-packages'
@@ -90,6 +91,7 @@ const AI_COPY_FILES: ReadonlyArray<string> = [
 	'.github/workflows/auto-tag.yml',
 	'.github/workflows/production.yml',
 	'.github/workflows/sonar-qube.yml',
+	'.github/workflows/pr-classification.yml',
 	'.github/pull_request_template.md',
 	'.github/release.yml',
 	'.github/dependabot.yml',
@@ -228,9 +230,12 @@ const PRETTIER_PLUGIN_DEV_DEPS: Record<string, string> = {
 // format_json rather than JSON.stringify: it lays arrays out the way prettier does — inline while
 // they fit within printWidth, one element per line once they do not — so the file kit writes is
 // `prettier --check`-clean in the consumer whatever the entry count happens to be (#660).
+// TypeScript 6 defaults `types` to `[]`, so a node project sees no `process` global — not even in the
+// generated `playwright.config.ts` — until the Node types are named (joshuafolkken/kit#2710).
 function generate_tsconfig(): string {
 	return json_format.format_json({
 		extends: TSCONFIG_EXTENDS,
+		compilerOptions: { types: ['node'] },
 		[TSCONFIG_EXCLUDE_FIELD]: TSCONFIG_EXCLUDE,
 	})
 }
@@ -451,6 +456,7 @@ const init_logic = {
 	strip_kit_only_vscode_settings,
 	strip_kit_only_vscode_settings_content,
 	VSCODE_EXTENSIONS_FILENAME,
+	SAFE_CHAIN_CMD,
 	GUARDED_LEFTHOOK_CMD,
 	upgrade_prepare_lefthook_warning,
 	get_npmrc_lines,

package/scripts/init/init-static.ts

@@ -36,7 +36,10 @@ function merge_static_manifest(
 	versions: StaticVersions,
 ): string {
 	const with_profile = with_recorded_profile(content, shape.profile)
-	const with_script = init_logic.merge_package_scripts(with_profile, { josh: 'josh' })
+	const with_script = init_logic.merge_package_scripts(with_profile, {
+		preinstall: init_logic.SAFE_CHAIN_CMD,
+		josh: 'josh',
+	})
 	const with_kit = init_logic.merge_development_dependencies(with_script, {
 		[KIT_PACKAGE_NAME]: versions.kit,
 	})

package/scripts/init/init.ts

@@ -27,6 +27,7 @@ const LEFTHOOK_BIN = 'lefthook'
 const SAMPLE_INDENT_WIDTH = 4
 const ARGUMENT_START_INDEX = 2
 const SAMPLE_INDENT = ' '.repeat(SAMPLE_INDENT_WIDTH)
+const INSTALL_HINT = '→ run `pnpm install` to install what package.json lists'
 
 function write_new_file(action: FileAction, destination_path: string): void {
 	mkdirSync(path.dirname(destination_path), { recursive: true })
@@ -77,12 +78,25 @@ function execute_file_action(action: FileAction): void {
 	merge_existing_file(action.merge, destination_path, action.dest)
 }
 
-function get_kit_package_manager(): string | undefined {
-	const { packageManager: package_manager } = with_package_manager_schema.parse(
-		init_actions.read_package_json(PACKAGE_JSON),
-	)
+const engine_pin_schema = z.looseObject({ name: z.string(), version: z.string() })
+
+const published_development_engines_schema = z.looseObject({
+	devEngines: z.looseObject({ packageManager: engine_pin_schema.optional() }).optional(),
+})
+
+// pnpm strips `packageManager` from a published manifest, so the kit a consumer installs carries its
+// pin only in `devEngines`. Falling back to that exact version keeps the consumer off the bare
+// `>=12.1.0` range, which every later `pnpm` call rejects as an invalid packageManager specification.
+function resolve_kit_package_manager(manifest: unknown): string | undefined {
+	const { packageManager: package_manager } = with_package_manager_schema.parse(manifest)
+	if (package_manager !== undefined && package_manager.length > 0) return package_manager
+	const pin = published_development_engines_schema.parse(manifest).devEngines?.packageManager
 
-	return package_manager !== undefined && package_manager.length > 0 ? package_manager : undefined
+	return pin === undefined ? undefined : `${pin.name}@${pin.version}`
+}
+
+function get_kit_package_manager(): string | undefined {
+	return resolve_kit_package_manager(init_actions.read_package_json(PACKAGE_JSON))
 }
 
 function get_kit_development_engines(): Record<string, unknown> {
@@ -97,21 +111,34 @@ function get_kit_self_dependency(): Record<string, string> {
 	return { [KIT_PACKAGE_NAME]: version }
 }
 
-function get_eslint_development_dependencies(): Record<string, string> {
+// Each config `init` generates runs a CLI or imports types the consumer has to resolve itself:
+// `prettier.config.js` → prettier, `cspell.config.yaml` → cspell, `playwright.config.ts` →
+// @types/node (with @playwright/test among the peers), `lefthook.yml` → lefthook. Without them the
+// first `josh gate` after `pnpm install` fails (joshuafolkken/kit#2710).
+const TOOL_DEVELOPMENT_DEPENDENCIES = ['prettier', 'cspell', '@types/node']
+const LEFTHOOK_DEVELOPMENT_DEPENDENCY = 'lefthook'
+
+function tool_dependency_names(has_git: boolean): ReadonlyArray<string> {
+	return has_git
+		? [...TOOL_DEVELOPMENT_DEPENDENCIES, LEFTHOOK_DEVELOPMENT_DEPENDENCY]
+		: TOOL_DEVELOPMENT_DEPENDENCIES
+}
+
+// Versions mirror kit's own devDependencies, so the consumer runs the toolchain kit is verified with.
+function get_toolchain_development_dependencies(has_git: boolean): Record<string, string> {
 	const manifest = z
 		.object({
 			peerDependencies: z.record(z.string(), z.string()),
 			devDependencies: z.record(z.string(), z.string()),
 		})
 		.parse(init_actions.read_package_json(PACKAGE_JSON))
-	const entries = Object.keys(manifest.peerDependencies)
-		.filter((name) => name !== '@playwright/test')
-		.map((name): [string, string] => {
-			const version = manifest.devDependencies[name]
-			if (version === undefined) throw new Error(`Missing development version for ${name}`)
+	const names = [...Object.keys(manifest.peerDependencies), ...tool_dependency_names(has_git)]
+	const entries = names.map((name): [string, string] => {
+		const version = manifest.devDependencies[name]
+		if (version === undefined) throw new Error(`Missing development version for ${name}`)
 
-			return [name, version]
-		})
+		return [name, version]
+	})
 
 	return Object.fromEntries(entries)
 }
@@ -126,11 +153,11 @@ function apply_dependency_merges(content: string, has_git = true): string {
 			: Object.fromEntries(Object.entries(suggested).filter(([key]) => key !== 'prepare')),
 	)
 	const with_prettier = init_logic.merge_prettier_plugin_development_deps(merged)
-	const with_eslint = init_logic.merge_development_dependencies(
+	const with_toolchain = init_logic.merge_development_dependencies(
 		with_prettier,
-		get_eslint_development_dependencies(),
+		get_toolchain_development_dependencies(has_git),
 	)
-	const with_secretlint = init_logic.merge_secretlint_development_deps(with_eslint)
+	const with_secretlint = init_logic.merge_secretlint_development_deps(with_toolchain)
 
 	return init_logic.merge_development_dependencies(with_secretlint, get_kit_self_dependency())
 }
@@ -191,12 +218,25 @@ function merge_project_package_json(shape: ProjectShape): void {
 
 	writeFileSync(package_json_path, merged)
 	console.info(`  ✔ ${is_existing ? 'updated' : 'created'}   package.json`)
+	// `init` writes the manifest but installs nothing, so a tool it just listed is absent until the
+	// user installs it — and `josh lint` then fails on it rather than skipping it
+	// (joshuafolkken/kit#2709). Saying so here is what tells the user the next step.
+	console.info(`    ${INSTALL_HINT}`)
 }
 
-function install_lefthook(): void {
+// A fresh project runs `init` before its first `pnpm install`, so lefthook — added to devDependencies
+// above — is not there yet; the `prepare` script installs the hooks once it is.
+function install_lefthook(project_root: string = PROJECT_ROOT): void {
 	console.info('\nLefthook:')
-	const bin = resolve_local_bin(PROJECT_ROOT, LEFTHOOK_BIN)
-	const result = execaSync(bin, ['install'], { cwd: PROJECT_ROOT, stdio: 'inherit', reject: false })
+	const bin = resolve_local_bin(project_root, LEFTHOOK_BIN)
+
+	if (!existsSync(bin)) {
+		console.info('  ℹ lefthook is not installed yet — `pnpm install` installs the git hooks')
+
+		return
+	}
+
+	const result = execaSync(bin, ['install'], { cwd: project_root, stdio: 'inherit', reject: false })
 
 	if (result.exitCode === undefined) {
 		console.warn('  ⚠ lefthook install failed — run it manually: lefthook install')
@@ -281,6 +321,7 @@ const init = {
 	copy_ai_file: init_ai_copy.copy_ai_file,
 	apply_package_json_merges,
 	install_lefthook,
+	resolve_kit_package_manager,
 }
 
 // `init` is the entry point; `main` is exported for its own unit test, the way `sync.ts` exports the