@joshuafolkken/kit 1.929.0 → 1.953.0

package/scripts/git/git-gh-pr-rollup.ts

@@ -29,7 +29,9 @@ const check_runs_page_schema = z.looseObject({
 	// answer an empty rollup — which `git-pr-followup.ts` reports as "this branch has no checks".
 	check_runs: z.array(rollup_element_schema),
 })
-const check_run_app_schema = z.object({ id: z.number() })
+
+// Both `app` and `check_suite` are objects carrying a numeric `id`, and so is a check run itself.
+const id_holder_schema = z.object({ id: z.number() })
 
 const status_page_schema = z.looseObject({
 	statuses: z.array(rollup_element_schema),
@@ -51,37 +53,75 @@ function read_pages<T>(raw_json: string, schema: z.ZodType<T>, message: string):
 	return pages
 }
 
+const NO_SUITE = -1
+
+interface RunRank {
+	suite: number
+	run: number
+}
+
+function read_id(value: unknown): number | undefined {
+	const parsed = id_holder_schema.safeParse(value)
+
+	return parsed.success ? parsed.data.id : undefined
+}
+
 function check_run_group_key(run: RollupElement): string | undefined {
-	const { name, app: raw_app } = run
+	const { name, app } = run
 	if (typeof name !== 'string') return undefined
-	const app = check_run_app_schema.safeParse(raw_app)
 
-	return JSON.stringify([name, app.success ? app.data.id : undefined])
+	return JSON.stringify([name, read_id(app)])
+}
+
+function read_rank(run: RollupElement): RunRank | undefined {
+	const id = read_id(run)
+	if (id === undefined) return undefined
+
+	return { suite: read_id(run['check_suite']) ?? NO_SUITE, run: id }
+}
+
+// **The newest check suite decides a name, not the newest check run** — the rule GitHub's merge box
+// applies. The endpoint's default `filter=latest` already keeps only the newest run of each name
+// *within* a suite (a re-run job lands in the suite it re-runs), so what is left is one run per
+// suite. Across suites GitHub takes the one from the newer suite: PR #2717's cancelled suite was the
+// older one and GitHub read the pull request `CLEAN`, while PR #2698's cancelled suite was the newer
+// one and GitHub held it `BLOCKED`. Ranking by run id alone (joshuafolkken/kit#2644) picked #2698's
+// older, successful suite — its jobs had queued later — so `followup` read green beside a `BLOCKED`
+// pull request and waited out its whole budget (joshuafolkken/kit#2700).
+function is_ranked_above(candidate: RunRank, current: RunRank): boolean {
+	if (candidate.suite !== current.suite) return candidate.suite > current.suite
+
+	return candidate.run > current.run
+}
+
+function should_replace(previous: RollupElement | undefined, rank: RunRank): boolean {
+	const previous_rank = previous === undefined ? undefined : read_rank(previous)
+
+	return previous_rank === undefined || is_ranked_above(rank, previous_rank)
 }
 
-function remember_newest_run(run: RollupElement, latest_ids: Map<string, number>): void {
+function remember_newest_run(run: RollupElement, newest: Map<string, RollupElement>): void {
 	const key = check_run_group_key(run)
-	const { id } = run
-	if (key === undefined || typeof id !== 'number') return
-	const previous_id = latest_ids.get(key)
-	if (previous_id === undefined || id > previous_id) latest_ids.set(key, id)
+	const rank = read_rank(run)
+	if (key === undefined || rank === undefined) return
+	if (should_replace(newest.get(key), rank)) newest.set(key, run)
 }
 
-function is_newest_run(run: RollupElement, latest_ids: Map<string, number>): boolean {
+// A run with no name or id cannot be ranked, so it is kept rather than guessed to be superseded.
+function is_newest_run(run: RollupElement, newest: Map<string, RollupElement>): boolean {
 	const key = check_run_group_key(run)
-	const { id } = run
-	if (key === undefined || typeof id !== 'number') return true
+	if (key === undefined || read_rank(run) === undefined) return true
 
-	return id === latest_ids.get(key)
+	return newest.get(key) === run
 }
 
 function to_check_run_items(check_runs_json: string): Array<RollupElement> {
 	const pages = read_pages(check_runs_json, check_runs_page_schema, NOT_A_CHECK_RUNS_LISTING)
 	const runs = pages.flatMap((page) => page.check_runs)
-	const latest_ids = new Map<string, number>()
-	for (const run of runs) remember_newest_run(run, latest_ids)
+	const newest = new Map<string, RollupElement>()
+	for (const run of runs) remember_newest_run(run, newest)
 
-	return runs.filter((run) => is_newest_run(run, latest_ids))
+	return runs.filter((run) => is_newest_run(run, newest))
 }
 
 function to_status_context_items(status_json: string): Array<RollupElement> {

package/scripts/git/git-staging.ts

@@ -1,6 +1,6 @@
 import {
 	observation_ledger,
-	OBSERVATION_LEDGER_PATH,
+	OBSERVATION_LEDGER_PATHS,
 } from '#scripts/observations/observation-ledger'
 import { git_command } from './git-command'
 import { git_prompt } from './git-prompt'
@@ -73,10 +73,12 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 // entirely — a diff a reviewer has no reason to question. Excluding it here covers every entry
 // point, because this is the one staging step all of them go through;
 // `pnpm josh observations:flush` is what commits it, on a branch of its own.
-const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = [OBSERVATION_LEDGER_PATH]
+// Both of its paths are excluded (joshuafolkken/kit#2724): a run on the old code still appends at
+// the old one until `observation-ledger-migrate.ts` moves it.
+const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = OBSERVATION_LEDGER_PATHS
 
 function is_stageable(file_path: string): boolean {
-	return !PATHS_EXCLUDED_FROM_STAGING.includes(file_path)
+	return !observation_ledger.is_ledger_path(file_path)
 }
 
 // **Said out loud, because the alternative is an unexplained failure.** With the ledger the only
@@ -84,7 +86,7 @@ function is_stageable(file_path: string): boolean {
 // step dies on git's empty index with `Failed to commit changes` — a message naming nothing that
 // caused it. This line is what turns that into a diagnosis.
 //
-// **The paths are parsed rather than matched as substrings**: `docs/observations.md.bak` contains the
+// **The paths are parsed rather than matched as substrings**: `docs/maintainers/observations.md.bak` contains the
 // ledger's path, and a hint naming a file the exclusion never touched is a hint that teaches the
 // reader to ignore it.
 function report_excluded_paths(status_output: string): void {

package/scripts/git/git-stash.ts

@@ -14,6 +14,12 @@ const FIELD_SEPARATOR = '\u{0}'
 // stash pushed with `-m`); `%x00` emits the NUL the fields are split on.
 const LIST_FORMAT = '--format=%gd%x00%gs'
 const SUBJECT_MESSAGE_SEPARATOR = ': '
+// `%H` is the entry's commit hash; the second format pairs it with the position a drop needs.
+const HASH_FORMAT = '--format=%H%x00%gs'
+const HASH_POSITION_FORMAT = '--format=%H%x00%gd'
+const NAME_ONLY_FLAG = '--name-only'
+const ADDED_PREFIX = '+'
+const FILE_HEADER_PREFIX = '+++'
 
 interface StashEntry {
 	selector: string
@@ -84,7 +90,7 @@ async function pop(selector: string, directory?: string): Promise<void> {
 // 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> {
 	const unmerged = await git_spawn.read(
-		git_args(directory, ['diff', '--name-only', '--diff-filter=U']),
+		git_args(directory, ['diff', NAME_ONLY_FLAG, '--diff-filter=U']),
 	)
 
 	return unmerged !== ''
@@ -102,6 +108,68 @@ async function push(message: string, directory?: string): Promise<void> {
 	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message]))
 }
 
+// The stack keyed by commit rather than position (joshuafolkken/kit#2701): a sweep that reads the
+// stack, asks GitHub about each entry and only then drops one would drop whatever another lane pushed
+// on top in the meantime if it kept the `stash@{n}` it read first. The `selector` of each entry here is
+// its commit hash, which never moves.
+async function list_by_hash(directory?: string): Promise<Array<StashEntry>> {
+	return parse_entries(await git_spawn.read(git_args(directory, ['stash', 'list', HASH_FORMAT])))
+}
+
+// The paths an entry carries, untracked files included — `push` stashes with `-u`.
+async function changed_paths(hash: string, directory?: string): Promise<Array<string>> {
+	const raw = await git_spawn.read(
+		git_args(directory, ['stash', 'show', '--include-untracked', NAME_ONLY_FLAG, hash]),
+	)
+
+	return raw === '' ? [] : raw.split(ENTRY_SEPARATOR)
+}
+
+// A path untracked when the entry was pushed with `-u` lives in its third parent, not in its diff, so
+// every line of it is an added one; a path absent from that parent reads as none.
+async function untracked_lines(
+	hash: string,
+	file: string,
+	directory?: string,
+): Promise<Array<string>> {
+	try {
+		const raw = await git_spawn.read(git_args(directory, ['show', `${hash}^3:${file}`]))
+
+		return raw === '' ? [] : raw.split(ENTRY_SEPARATOR)
+	} catch {
+		return []
+	}
+}
+
+// The lines an entry adds to one path, as a unified diff against the commit it was pushed on — or, for
+// a path that was untracked then, the whole file.
+async function added_lines(hash: string, file: string, directory?: string): Promise<Array<string>> {
+	const diff = await git_spawn.read(git_args(directory, ['diff', `${hash}^1`, hash, '--', file]))
+
+	if (diff === '') return await untracked_lines(hash, file, directory)
+
+	return diff
+		.split(ENTRY_SEPARATOR)
+		.filter((line) => line.startsWith(ADDED_PREFIX) && !line.startsWith(FILE_HEADER_PREFIX))
+		.map((line) => line.slice(ADDED_PREFIX.length))
+}
+
+// The position is resolved from the hash immediately before the drop, so an entry pushed since the
+// sweep's read cannot be dropped in its place; an entry already gone answers `false` rather than
+// throwing. Sweeps are serialized by `stash-sweep-lock`, but a plain `git stash push` or `pop` from
+// another command landing between the resolve and the drop still shifts the position — that window is
+// the length of two local git calls.
+async function drop_by_hash(hash: string, directory?: string): Promise<boolean> {
+	const raw = await git_spawn.read(git_args(directory, ['stash', 'list', HASH_POSITION_FORMAT]))
+	const entry = parse_entries(raw).find((candidate) => candidate.selector === hash)
+
+	if (entry === undefined) return false
+
+	await git_spawn.read(git_args(directory, ['stash', 'drop', entry.subject]))
+
+	return true
+}
+
 // The message uncommitted work is pushed with, keyed on the issue so `josh stash:pop` can target it and
 // on the occasion so two pushes for one issue — a lane close and an `already-done` read — stay apart.
 function work_message(issue: string, occasion: string): string {
@@ -109,9 +177,13 @@ function work_message(issue: string, occasion: string): string {
 }
 
 const git_stash = {
+	added_lines,
+	changed_paths,
+	drop_by_hash,
 	has_changes,
 	has_conflict,
 	list,
+	list_by_hash,
 	matches,
 	parse_entries,
 	pop,

package/scripts/git/git-worktree.ts

@@ -1,6 +1,7 @@
 import { PORCELAIN_FLAG } from './constants'
 import { ls_remote_branch_arguments } from './git-ls-remote'
 import { git_spawn } from './git-spawn'
+import { repository_lock } from './repository-lock'
 
 // The four worktree reads and writes a lane's lifecycle needs, plus the branch deletion that ends it
 // (joshuafolkken/kit#1490; split out of `git-command.ts` under joshuafolkken/kit#1640). They live
@@ -19,6 +20,36 @@ import { git_spawn } from './git-spawn'
 // (joshuafolkken/kit#1641; before it, `lane-start-point.ts` was the only reader and did both).
 const WORKTREE = 'worktree'
 
+// **Every call that writes `.git/worktrees/` runs under one repository-wide lock**
+// (joshuafolkken/kit#2736). `git worktree add` is not safe against itself: while one add is still
+// building `.git/worktrees/<id>/` — its `commondir` not yet written — a second add enumerates the
+// existing registrations, reads the half-built one and fails with `fatal: failed to read
+// .git/worktrees/<id>/commondir`. Two lanes opened at once do exactly that, and the per-seat lock in
+// `lane-open.ts` does not serialize them. `remove` and `prune` edit the same directory, so they take
+// the same lock. The lock wraps the git call alone; the slow steps a caller runs afterwards — a lane's
+// dependency install — stay outside it.
+const WORKTREE_LOCK_PREFIX = 'josh-worktree-lock-'
+// A holder runs one local git command, so the wait only bounds a checkout that hung; it is generous
+// because a large repository's checkout is itself several seconds, and several lanes queue behind it.
+const WORKTREE_LOCK_MAX_WAIT_MS = 120_000
+
+async function locked(arguments_: Array<string>): Promise<string> {
+	const target = repository_lock.lock_path(WORKTREE_LOCK_PREFIX)
+	const output = await repository_lock.with_lock(
+		async () => await git_spawn.read(arguments_),
+		target,
+		WORKTREE_LOCK_MAX_WAIT_MS,
+	)
+
+	if (output === undefined) {
+		throw new Error(
+			`git ${arguments_.join(' ')}: timed out waiting for the work-tree lock ${target}`,
+		)
+	}
+
+	return output
+}
+
 // Every registered work tree of this repository, in git's own machine-readable form: one `worktree
 // <path>` / `HEAD <sha>` / `branch <ref>` block per tree, blocks separated by a blank line. Parsing
 // it is the caller's, so this module keeps one shape for every reader.
@@ -50,14 +81,14 @@ async function worktree_add(
 ): Promise<string> {
 	const flags = start_point === undefined ? ['add'] : ['add', '--no-track', '-b', branch_name]
 
-	return await git_spawn.read([WORKTREE, ...flags, directory, start_point ?? branch_name])
+	return await locked([WORKTREE, ...flags, directory, start_point ?? branch_name])
 }
 
 // A throwaway tree at one commit, on no branch — `josh test:red` checks the merge-base out here, so
 // the pre-fix tree is built without creating a branch or touching the caller's tree and index
 // (joshuafolkken/kit#2448).
 async function worktree_add_detached(directory: string, commit: string): Promise<string> {
-	return await git_spawn.read([WORKTREE, 'add', '--detach', directory, commit])
+	return await locked([WORKTREE, 'add', '--detach', directory, commit])
 }
 
 // **`--force` is the point, not a convenience.** A lane is closed after a park, a failure or an
@@ -65,13 +96,13 @@ async function worktree_add_detached(directory: string, commit: string): Promise
 // or untracked work. Refusing to remove it there would leave exactly the debris the close exists to
 // prevent.
 async function worktree_remove(directory: string): Promise<string> {
-	return await git_spawn.read([WORKTREE, 'remove', '--force', directory])
+	return await locked([WORKTREE, 'remove', '--force', directory])
 }
 
 // Drops the registrations whose directories are already gone — what makes a lane whose directory was
 // deleted by hand recoverable rather than a permanent `worktree add` refusal on that path.
 async function worktree_prune(): Promise<string> {
-	return await git_spawn.read([WORKTREE, 'prune'])
+	return await locked([WORKTREE, 'prune'])
 }
 
 // **Asked of the remote itself, because nothing prunes the remote-tracking refs**

package/scripts/git/repository-lock.ts

@@ -0,0 +1,138 @@
+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 holder at a time per repository, for work that every work tree of that repository shares
+// (joshuafolkken/kit#2701 for the stash sweep, joshuafolkken/kit#2736 for `git worktree add`). The
+// record is keyed on the git common directory, so every work tree of one repository contends for one
+// record per lock name, and it lives in the platform temp root beside the other stamps rather than
+// inside `.git`. Each caller names its own lock with a prefix, so two unrelated kinds of work never
+// wait on each other.
+
+const POLL_INTERVAL_MS = 200
+
+interface LockOwner {
+	pid: number
+	process_start?: string
+}
+
+type IsGone = (owner: LockOwner) => boolean
+
+function lock_path(prefix: string, cwd: string = process.cwd()): string {
+	return stamp_file.stamp_path(prefix, git_common_directory.repository(cwd) ?? cwd)
+}
+
+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 claimant 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 holder'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 claimants 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 at `target` and answers its result, or `undefined` without running it
+// when another holder kept the lock for the whole wait.
+async function with_lock<T>(
+	work: () => Promise<T>,
+	target: string,
+	max_wait_ms: number,
+): Promise<T | undefined> {
+	if (!(await acquire(target, max_wait_ms))) return undefined
+
+	try {
+		return await work()
+	} finally {
+		release(target)
+	}
+}
+
+const repository_lock = { clear_stale, lock_path, with_lock }
+
+export { repository_lock }

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,30 @@
+import { repository_lock } from './repository-lock'
+
+// 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
+// locking itself is `repository-lock.ts`, shared with the work-tree writes (joshuafolkken/kit#2736).
+
+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 MAX_WAIT_MS = 30_000
+
+function lock_path(cwd: string = process.cwd()): string {
+	return repository_lock.lock_path(LOCK_PREFIX, cwd)
+}
+
+// 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> {
+	return await repository_lock.with_lock(work, target, max_wait_ms)
+}
+
+const stash_sweep_lock = { clear_stale: repository_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-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,