@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/git/git-push-transport.ts

@@ -1,6 +1,12 @@
 import { execa } from 'execa'
 import { git_utilities } from './constants'
-import { create_spawn_error, get_exit_code, has_timed_out } from './git-execa-error'
+import {
+	create_spawn_error,
+	get_exit_code,
+	has_timed_out,
+	TIMEOUT_EXIT_CODE,
+} from './git-execa-error'
+import { git_ssh_keepalive } from './git-ssh-keepalive'
 
 const MS_PER_SECOND = 1000
 
@@ -33,65 +39,10 @@ const PUSH_TIMEOUT_LABEL = `${String(PUSH_TIMEOUT_SECONDS)}s`
 // said no" are different diagnoses, and only the first one is worth retrying.
 const PUSH_TIMEOUT_MESSAGE = 'git push timed out'
 
-// A timeout has no exit code — the process was killed rather than allowed to exit — so `cause` says
-// so in the slot every other git failure puts a number in. `is_upstream_not_set_error` compares
-// against '128', which this can never equal, so a timed-out bare push is never mistaken for a
-// missing upstream and retried as `--set-upstream`.
-const PUSH_TIMEOUT_EXIT_CODE = 'timeout'
-
-// SSH's own liveness probe: three unanswered checks 15 seconds apart, so a connection that dies
-// mid-transfer is noticed in about 45 seconds instead of waiting on the TCP default. The budget
-// above bounds the damage either way; this is what makes the common case fail in seconds rather
-// than sit out the whole budget.
-const SSH_KEEPALIVE_OPTIONS = '-o ServerAliveInterval=15 -o ServerAliveCountMax=3'
-const SSH_COMMAND_VARIABLE = 'GIT_SSH_COMMAND'
-const SSH_LEGACY_VARIABLE = 'GIT_SSH'
-const KEEPALIVE_SSH_COMMAND = `ssh ${SSH_KEEPALIVE_OPTIONS}`
-const SSH_COMMAND_CONFIG_KEY = 'core.sshCommand'
+// `TIMEOUT_EXIT_CODE` is never '128', which `is_upstream_not_set_error` compares against, so a
+// timed-out bare push is never mistaken for a missing upstream and retried as `--set-upstream`.
 const PUSH_SUBCOMMAND = 'push'
 
-// Whatever already decides how ssh is invoked, or an empty string when nothing does. git reads three
-// sources in this order — `GIT_SSH_COMMAND`, `core.sshCommand`, then the legacy `GIT_SSH` — and the
-// last one has to be asked as well precisely because it loses: setting `GIT_SSH_COMMAND` on top of a
-// `GIT_SSH=plink.exe` outranks it, so the push would run an ssh binary the user did not choose.
-function to_environment_value(name: string): string {
-	return process.env[name]?.trim() ?? ''
-}
-
-function to_configured_ssh_command(): string {
-	const from_command = to_environment_value(SSH_COMMAND_VARIABLE)
-
-	return from_command === '' ? to_environment_value(SSH_LEGACY_VARIABLE) : from_command
-}
-
-// Whether any of those three sources answered. **A hit means hands off entirely.**
-//
-// Appending the options to a command someone else chose is not safe, because they are OpenSSH's:
-// `plink` and `TortoiseGitPlink` are supported ssh commands on the platform `get_git_command_for_spawn`
-// goes out of its way to handle, and a wrapper script with a fixed argument list is common on any
-// platform — each of them exits on a usage error rather than pushing. Setting the variable while
-// `core.sshCommand` is configured is the same mistake from the other side: the environment wins, so
-// a per-repository key would be silently replaced by a plain `ssh`.
-//
-// What those users lose is the keepalive, not the fix: the budget above still bounds their push, and
-// `ServerAliveInterval` belongs in their own ssh config where it applies to every tool they run.
-async function has_configured_ssh_command(): Promise<boolean> {
-	if (to_configured_ssh_command() !== '') return true
-
-	try {
-		const git_command_bin = git_utilities.get_git_command_for_spawn()
-		// execa runs the binary directly with an argument array and no `shell` option, so CLI
-		// args cannot break out of a shell sandbox; the git command and args are internally
-		// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
-		const { stdout } = await execa(git_command_bin, ['config', '--get', SSH_COMMAND_CONFIG_KEY]) // NOSONAR
-
-		return stdout.trim() !== ''
-	} catch {
-		// `git config --get` exits 1 when the key is unset, which is the answer rather than a failure.
-		return false
-	}
-}
-
 interface PushOptions {
 	stdio: 'inherit'
 	timeout: number
@@ -99,12 +50,10 @@ interface PushOptions {
 }
 
 async function to_push_options(): Promise<PushOptions> {
-	const should_keep_alive = !(await has_configured_ssh_command())
-
 	return {
 		stdio: 'inherit',
 		timeout: PUSH_TIMEOUT_MS,
-		env: should_keep_alive ? { [SSH_COMMAND_VARIABLE]: KEEPALIVE_SSH_COMMAND } : {},
+		env: await git_ssh_keepalive.to_environment(),
 	}
 }
 
@@ -142,7 +91,7 @@ function to_retry_notice(arguments_list: Array<string>): string {
 function create_timeout_error(arguments_list: Array<string>): Error {
 	const message = `${PUSH_TIMEOUT_MESSAGE} twice (${PUSH_TIMEOUT_LABEL} each). Re-run it by hand: ${to_manual_command(arguments_list)}`
 
-	return new Error(message, { cause: { exit_code: PUSH_TIMEOUT_EXIT_CODE } })
+	return new Error(message, { cause: { exit_code: TIMEOUT_EXIT_CODE } })
 }
 
 // One push, bounded and retried once — and **only** on a timeout. A push the remote rejected (a
@@ -164,10 +113,4 @@ const git_push_transport = {
 }
 
 export { git_push_transport }
-export {
-	KEEPALIVE_SSH_COMMAND,
-	PUSH_TIMEOUT_MESSAGE,
-	PUSH_TIMEOUT_MS,
-	SSH_COMMAND_VARIABLE,
-	SSH_LEGACY_VARIABLE,
-}
+export { PUSH_TIMEOUT_MESSAGE, PUSH_TIMEOUT_MS }

package/scripts/git/git-push.ts

@@ -1,4 +1,4 @@
-import { animation_helpers, create_git_operation_config } from './animation-helpers'
+import { animation_helpers, create_git_operation_config } from '#scripts/lib/animation-helpers'
 import { git_command } from './git-command'
 
 async function push(): Promise<void> {

package/scripts/git/git-spawn.ts

@@ -1,6 +1,13 @@
 import { execa } from 'execa'
 import { git_utilities } from './constants'
-import { create_spawn_error, get_exit_code } from './git-execa-error'
+import {
+	create_spawn_error,
+	get_exit_code,
+	has_timed_out,
+	TIMEOUT_EXIT_CODE,
+} from './git-execa-error'
+import { PUSH_TIMEOUT_MS } from './git-push-transport'
+import { git_ssh_keepalive } from './git-ssh-keepalive'
 
 // The one place the ordinary git commands are spawned from (joshuafolkken/kit#1640). It sits in a
 // module of its own rather than inside `git-command.ts` so that a second command module —
@@ -9,8 +16,8 @@ import { create_spawn_error, get_exit_code } from './git-execa-error'
 // `CLAUDE.md` prohibits, so a new caller imports this one instead of growing its own.
 //
 // **`git-push-transport.ts` is the one deliberate exception among the command modules** and is not a
-// second helper of this kind: a push needs a timeout and a transport-fault retry that no other
-// command has, so it spawns git itself. Those two files are the spawn sites of the ordinary command
+// second helper of this kind: a push needs a transport-fault retry that no other command has, so it
+// spawns git itself. The timeout it carries is shared here by `read_remote` / `with_output_remote`. Those two files are the spawn sites of the ordinary command
 // modules — the claim stops there. Other parts of this package spawn git for their own purposes
 // (`scripts/run/run-progress-clock.ts`, `scripts/propagate/propagate-git.ts`,
 // `scripts/doctor/doctor-io.ts`, `scripts/git/git-fixture-workspace.ts`), and an audit of how the git
@@ -26,6 +33,73 @@ async function read(arguments_: Array<string>): Promise<string> {
 	return stdout.trimEnd()
 }
 
+// The budget for a git call that talks to the remote — `fetch` and `pull` (joshuafolkken/kit#2942).
+// `read` and `with_output` wait without end, and a `git fetch --prune` under `josh main:sync` sat on
+// a dead ssh connection for 37 minutes, stalling the unattended backlog driver whose merge step runs
+// it. The push's budget is reused rather than a second number chosen: both transfer objects over the
+// same transport, and that one is already read off what a healthy transfer costs here.
+const REMOTE_TIMEOUT_MS = PUSH_TIMEOUT_MS
+const MS_PER_SECOND = 1000
+
+// A budget kill is reported as a timeout, never as whatever the killed process printed first, and
+// `cause` carries the same `TIMEOUT_EXIT_CODE` a timed-out push does. Unlike the push it is not
+// retried here: what the issue needed is that the wait ends, and a failure then surfaces to the
+// caller — `run:merge` raises a failed `main:sync` — instead of a second budget doubling the wait.
+function to_remote_error(command: string, error: unknown, timeout_ms: number): Error {
+	if (!has_timed_out(error)) return create_spawn_error(command, get_exit_code(error))
+
+	const seconds = String(Math.round(timeout_ms / MS_PER_SECOND))
+
+	return new Error(`git ${command} timed out after ${seconds}s`, {
+		cause: { exit_code: TIMEOUT_EXIT_CODE },
+	})
+}
+
+interface RemoteOptions {
+	stdio?: 'inherit'
+	timeout: number
+	env: Record<string, string>
+}
+
+// One remote call, bounded and kept alive. execa kills git on the budget; the ssh keepalive is what
+// makes ssh — which git does not kill with itself — exit on a dead connection as well.
+async function spawn_remote(arguments_: Array<string>, options: RemoteOptions): Promise<string> {
+	const git_cmd = git_utilities.get_git_command_for_spawn()
+
+	try {
+		// execa runs the binary directly with an argument array and no `shell` option, so CLI
+		// args cannot break out of a shell sandbox; the git command and args are internally
+		// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
+		const { stdout } = await execa(git_cmd, arguments_, options) // NOSONAR
+
+		return typeof stdout === 'string' ? stdout.trimEnd() : ''
+	} catch (error) {
+		throw to_remote_error(arguments_[0] ?? '', error, options.timeout)
+	}
+}
+
+// `read` for a call that reaches the remote. The budget is a parameter only so a test can hold it to
+// seconds; every production caller takes the default.
+async function read_remote(
+	arguments_: Array<string>,
+	timeout_ms: number = REMOTE_TIMEOUT_MS,
+): Promise<string> {
+	return await spawn_remote(arguments_, {
+		timeout: timeout_ms,
+		env: await git_ssh_keepalive.to_environment(),
+	})
+}
+
+// `with_output` for a call that reaches the remote — the output stays on the terminal, as a pull's
+// progress and a credential prompt need.
+async function with_output_remote(command: string, arguments_list: Array<string>): Promise<void> {
+	await spawn_remote([command, ...arguments_list], {
+		stdio: 'inherit',
+		timeout: REMOTE_TIMEOUT_MS,
+		env: await git_ssh_keepalive.to_environment(),
+	})
+}
+
 async function with_output(command: string, arguments_list: Array<string>): Promise<void> {
 	const git_command_bin = git_utilities.get_git_command_for_spawn()
 
@@ -41,7 +115,9 @@ async function with_output(command: string, arguments_list: Array<string>): Prom
 
 const git_spawn = {
 	read,
+	read_remote,
 	with_output,
+	with_output_remote,
 }
 
 export { git_spawn }

package/scripts/git/git-ssh-keepalive.ts

@@ -0,0 +1,74 @@
+import { execa } from 'execa'
+import { git_utilities } from './constants'
+
+// The ssh environment every git network call runs under (joshuafolkken/kit#2942). It began inside
+// `git-push-transport.ts` as the push's own (joshuafolkken/kit#1251), and moved here when the fetch
+// and pull of `josh main:sync` turned out to need the same thing: a dead connection under a `git
+// fetch` was waited on for 37 minutes, stalling the unattended backlog driver behind it.
+//
+// SSH's own liveness probe: three unanswered checks 15 seconds apart, so a connection that dies
+// mid-transfer is noticed in about 45 seconds instead of waiting on the TCP default. The caller's
+// timeout bounds the damage either way; this is what makes the common case fail in seconds rather
+// than sit out the whole budget — and, because ssh exits on its own, it is also what leaves no ssh
+// behind: git does not kill its transport child when it is itself killed on a timeout.
+const SSH_KEEPALIVE_OPTIONS = '-o ServerAliveInterval=15 -o ServerAliveCountMax=3'
+const SSH_COMMAND_VARIABLE = 'GIT_SSH_COMMAND'
+const SSH_LEGACY_VARIABLE = 'GIT_SSH'
+const KEEPALIVE_SSH_COMMAND = `ssh ${SSH_KEEPALIVE_OPTIONS}`
+const SSH_COMMAND_CONFIG_KEY = 'core.sshCommand'
+
+// Whatever already decides how ssh is invoked, or an empty string when nothing does. git reads three
+// sources in this order — `GIT_SSH_COMMAND`, `core.sshCommand`, then the legacy `GIT_SSH` — and the
+// last one has to be asked as well precisely because it loses: setting `GIT_SSH_COMMAND` on top of a
+// `GIT_SSH=plink.exe` outranks it, so git would run an ssh binary the user did not choose.
+function to_environment_value(name: string): string {
+	return process.env[name]?.trim() ?? ''
+}
+
+function to_configured_ssh_command(): string {
+	const from_command = to_environment_value(SSH_COMMAND_VARIABLE)
+
+	return from_command === '' ? to_environment_value(SSH_LEGACY_VARIABLE) : from_command
+}
+
+// Whether any of those three sources answered. **A hit means hands off entirely.**
+//
+// Appending the options to a command someone else chose is not safe, because they are OpenSSH's:
+// `plink` and `TortoiseGitPlink` are supported ssh commands on the platform `get_git_command_for_spawn`
+// goes out of its way to handle, and a wrapper script with a fixed argument list is common on any
+// platform — each of them exits on a usage error rather than connecting. Setting the variable while
+// `core.sshCommand` is configured is the same mistake from the other side: the environment wins, so
+// a per-repository key would be silently replaced by a plain `ssh`.
+//
+// What those users lose is the keepalive, not the fix: the caller's timeout still bounds the call,
+// and `ServerAliveInterval` belongs in their own ssh config where it applies to every tool they run.
+async function has_configured_ssh_command(): Promise<boolean> {
+	if (to_configured_ssh_command() !== '') return true
+
+	try {
+		const git_command_bin = git_utilities.get_git_command_for_spawn()
+		// execa runs the binary directly with an argument array and no `shell` option, so CLI
+		// args cannot break out of a shell sandbox; the git command and args are internally
+		// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
+		const { stdout } = await execa(git_command_bin, ['config', '--get', SSH_COMMAND_CONFIG_KEY]) // NOSONAR
+
+		return stdout.trim() !== ''
+	} catch {
+		// `git config --get` exits 1 when the key is unset, which is the answer rather than a failure.
+		return false
+	}
+}
+
+// The `env` a git network spawn passes to execa: the keepalive command, or nothing at all.
+async function to_environment(): Promise<Record<string, string>> {
+	const should_keep_alive = !(await has_configured_ssh_command())
+
+	return should_keep_alive ? { [SSH_COMMAND_VARIABLE]: KEEPALIVE_SSH_COMMAND } : {}
+}
+
+const git_ssh_keepalive = {
+	to_environment,
+}
+
+export { git_ssh_keepalive }
+export { KEEPALIVE_SSH_COMMAND, SSH_COMMAND_VARIABLE, SSH_LEGACY_VARIABLE }

package/scripts/git/git-staging.ts

@@ -62,6 +62,7 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 	if (files.length === 0) return
 
 	for (const file of files) {
+		// eslint-disable-next-line no-await-in-loop -- git add holds the index lock, so two at once fail
 		await git_command.add_path(file)
 	}
 

package/scripts/git/git-status.ts

@@ -1,4 +1,4 @@
-import { animation_helpers, type AnimationOptions } from './animation-helpers'
+import { animation_helpers, type AnimationOptions } from '#scripts/lib/animation-helpers'
 import { REQUIRED_STATUS_LENGTH, STAGED_STATUS_INDEX, UNTRACKED_FILE_PREFIX } from './constants'
 import { git_command } from './git-command'
 

package/scripts/git/git-workflow.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 import { parseArgs } from 'node:util'
+import { git_pr } from '#scripts/gh/git-pr'
 import { cli_body } from '#scripts/josh/cli-body'
 import { test_red_commit } from '#scripts/test/test-red-commit'
 import { git_branch } from './git-branch'
 import { git_commit } from './git-commit'
 import { git_error } from './git-error'
 import { git_issue, type IssueInfo } from './git-issue'
-import { git_pr } from './git-pr'
 import { git_preflight } from './git-preflight'
 import { git_prompt, type WorkflowConfirmations } from './git-prompt'
 import { git_push } from './git-push'

package/scripts/git/gone-branch.ts

@@ -89,6 +89,7 @@ async function delete_each(names: ReadonlyArray<string>): Promise<PruneResult> {
 
 	for (const name of names) {
 		try {
+			// eslint-disable-next-line no-await-in-loop -- branch deletions write the same refs, one at a time
 			await git_spawn.read(['branch', '-d', name])
 			result.deleted.push(name)
 		} catch {
@@ -100,9 +101,10 @@ async function delete_each(names: ReadonlyArray<string>): Promise<PruneResult> {
 }
 
 // `fetch --prune` first, because `[gone]` is read from the remote-tracking refs and those outlive the
-// remote branch until something prunes them.
+// remote branch until something prunes them. The fetch is the one call here that reaches the remote,
+// so it is the one bounded (joshuafolkken/kit#2942).
 async function prune(default_branch: string): Promise<PruneResult> {
-	await git_spawn.read(['fetch', '--prune'])
+	await git_spawn.read_remote(['fetch', '--prune'])
 
 	return await delete_each(await read_candidates(default_branch))
 }

package/scripts/git/listing-cutoff.ts

@@ -1,4 +1,4 @@
-import { MAX_SCANNED } from './git-gh-issue-list'
+import { MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 
 // Why an open-issue listing stopped short of the end of the backlog, or that it did not
 // (joshuafolkken/kit#1067).

package/scripts/git/main-merge.ts

@@ -114,7 +114,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const main_merge = { COMMAND_NAME, main, run }
+const main_merge = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/git/main-sync.ts

@@ -70,9 +70,27 @@ async function prune_quietly(default_branch: string): Promise<void> {
 	}
 }
 
+// **The local default branch is fast-forwarded before it is checked out** (joshuafolkken/kit#2979).
+// A run's ledger file is committed on its feature branch and merged; a line appended afterwards leaves
+// it dirty, and git refuses to check out a stale default branch that lacks the file — so `run:tail`'s
+// sync failed exactly when the flush after it had work. Once fast-forwarded, the default branch holds
+// the committed file and the checkout carries the dirty lines over (the same step the flush takes,
+// joshuafolkken/kit#2462). Skipped on the default branch, where `fetch` refuses to update the checked-out
+// ref; a refusal elsewhere — a local default ahead of origin — is left to the checkout and pull to judge.
+async function fast_forward_quietly(default_branch: string): Promise<void> {
+	if ((await git_command.branch()) === default_branch) return
+
+	try {
+		await git_command.fast_forward_local(default_branch)
+	} catch {
+		// The checkout and `pull --ff-only` below decide, exactly as before this step existed.
+	}
+}
+
 async function synchronize(): Promise<number> {
 	const default_branch = await git_command.get_default_branch()
 
+	await fast_forward_quietly(default_branch)
 	await git_command.checkout(default_branch)
 	await git_command.pull_fast_forward()
 	await prune_quietly(default_branch)
@@ -115,7 +133,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const main_sync = { COMMAND_NAME, LANE_REFUSAL, main, run }
+const main_sync = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/git/parse-json-array.ts

@@ -87,10 +87,7 @@ function parse_json_object_safe<T>(raw_json: string, schema: z.ZodType<T>): T |
 }
 
 const parse_json = {
-	parse_json_array_safe,
-	parse_json_array_or_undefined,
 	parse_json_object_safe,
-	read_json_listing,
 }
 
 export {

package/scripts/git/repository-lock.ts

@@ -2,7 +2,9 @@ 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 { process_owner_schema, type ProcessOwner } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 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
@@ -14,32 +16,29 @@ import { git_common_directory } from './git-common-directory'
 
 const POLL_INTERVAL_MS = 200
 
-interface LockOwner {
-	pid: number
-	process_start?: string
-}
-
-type IsGone = (owner: LockOwner) => boolean
+type IsGone = (owner: ProcessOwner) => boolean
 
-function lock_path(prefix: string, cwd: string = process.cwd()): string {
-	return stamp_file.stamp_path(prefix, git_common_directory.repository(cwd) ?? cwd)
+// Without a `cwd` the read keeps the inherited git location variables, as every other git call of the
+// running process does; an explicit `cwd` clears them so that directory is the one answered for.
+function lock_path(prefix: string, cwd?: string): string {
+	return stamp_file.stamp_path(prefix, git_common_directory.repository(cwd) ?? cwd ?? process.cwd())
 }
 
-function parse_owner(raw: string | undefined): LockOwner | undefined {
+// A record that is not JSON, or is JSON of any other shape — `null`, an array, an object with no
+// numeric `pid` — is unreadable rather than an owner, so it is never judged and never cleared.
+function parse_owner(raw: string | undefined): ProcessOwner | undefined {
 	if (raw === undefined) return undefined
 
-	try {
-		return JSON.parse(raw) as LockOwner
-	} catch {
-		return undefined
-	}
+	const parsed = process_owner_schema.safeParse(json_value.parse_or_undefined(raw))
+
+	return parsed.success ? parsed.data : undefined
 }
 
-function read_owner(target: string): LockOwner | undefined {
+function read_owner(target: string): ProcessOwner | undefined {
 	return parse_owner(stamp_file.read_stamp_text(target))
 }
 
-function is_owner_gone(owner: LockOwner): boolean {
+function is_owner_gone(owner: ProcessOwner): boolean {
 	return process_identity.is_same_process(owner.pid, owner.process_start) === false
 }
 
@@ -111,6 +110,7 @@ async function acquire(target: string, max_wait_ms: number): Promise<boolean> {
 
 	while (!claim(target)) {
 		if (Date.now() >= deadline) return false
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_INTERVAL_MS)
 	}
 

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

@@ -1,4 +1,4 @@
-import { git_spawn } from './git-spawn'
+import { git_spawn } from '#scripts/git/git-spawn'
 
 // The one place a sanctioned `git stash pop` is targeted by its message rather than its stack
 // position (joshuafolkken/kit#2050). The stash is a single repository-wide stack shared by every

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

@@ -47,7 +47,7 @@ function to_request(parsed: ParsedValues): Request | undefined {
 	return { message, dir: parsed.values.dir }
 }
 
-const stash_pop_args = { USAGE, message_of, read_arguments, to_request }
+const stash_pop_args = { USAGE, read_arguments, to_request }
 
 export type { Request }
 export { stash_pop_args }

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

@@ -97,7 +97,6 @@ const stash_pop_cli = {
 	CONFLICTED_VERDICT,
 	NO_MATCH_VERDICT,
 	POPPED_VERDICT,
-	main,
 	run,
 }
 

package/scripts/git/{stash-sweep-lock.ts → stash/stash-sweep-lock.ts}

@@ -1,4 +1,4 @@
-import { repository_lock } from './repository-lock'
+import { repository_lock } from '#scripts/git/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
@@ -11,7 +11,7 @@ const LOCK_PREFIX = 'josh-stash-sweep-lock-'
 // 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 {
+function lock_path(cwd?: string): string {
 	return repository_lock.lock_path(LOCK_PREFIX, cwd)
 }
 
@@ -25,6 +25,6 @@ async function with_lock<T>(
 	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 }
+const stash_sweep_lock = { clear_stale: repository_lock.clear_stale, with_lock }
 
 export { stash_sweep_lock }

package/scripts/hooks/codex-hook-adapter.ts

@@ -146,7 +146,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const codex_hook_adapter = {
 	format_posttool_payloads,
-	patch_paths,
 	posttool_payloads,
 	pretool_outcome,
 	pretool_payload,

package/scripts/hooks/edited-cspell.ts

@@ -122,7 +122,7 @@ async function spelling_diagnostics(
 	}
 }
 
-const edited_cspell = { format_unknown_words, is_checkable, spelling_diagnostics }
+const edited_cspell = { format_unknown_words, spelling_diagnostics }
 
 export type { CspellRunner }
 export { edited_cspell, MAX_DIAGNOSTIC_CHARS }

package/scripts/hooks/format-edited-cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { report_no_payload, run_hook } from './format-edited-file'
+
+// The `PostToolUse` hook's entry, kept apart from `format-edited-file.ts` for the reason
+// `pretool-guard-cli.ts` gives (joshuafolkken/kit#2922): `codex-hook-adapter.ts` imports that module,
+// so a self-invoke left in it lands in a shared chunk and the bundled hook never runs.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) {
+		report_no_payload()
+	} else {
+		await run_hook(await text(process.stdin))
+	}
+}

package/scripts/hooks/format-edited-file.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
 import { ESLINT_EDIT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
@@ -328,6 +327,7 @@ async function run_command(command: FormatCommand, project_root: string): Promis
 	let outcome: CommandOutcome = { exit_code: 0, stdout: '' }
 
 	for (const invocation of resolve_invocations(command, project_root)) {
+		// eslint-disable-next-line no-await-in-loop -- a fallback route runs only when the previous one failed to start
 		outcome = await spawn_invocation(invocation, project_root)
 		if (!is_start_failure(outcome)) return outcome
 	}
@@ -375,6 +375,7 @@ async function collect_unfixed(
 
 	for (const command of plan) {
 		try {
+			// eslint-disable-next-line no-await-in-loop -- formatters rewrite the same file, in plan order
 			unfixed = eslint_unfixed(command, await runner(command, project_root)) ?? unfixed
 		} catch {
 			// One formatter failing to start is not a reason to skip the next: prettier runs last, and
@@ -482,14 +483,6 @@ async function run_hook(payload: string): Promise<void> {
 	if (context !== undefined) process.stdout.write(`${build_envelope(context)}\n`)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) {
-		report_no_payload()
-	} else {
-		await run_hook(await text(process.stdin))
-	}
-}
-
 export {
 	build_envelope,
 	compose_context,
@@ -501,7 +494,9 @@ export {
 	plan_commands,
 	plan_daemon_restart,
 	relative_to_root,
+	report_no_payload,
 	resolve_invocations,
+	run_hook,
 	select_invocation,
 	ESLINT_DAEMON,
 	MAX_DIAGNOSTIC_CHARS,

package/scripts/hooks/pre-push-unit.ts

@@ -136,10 +136,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const pre_push_unit = {
 	FORCE_ENV,
-	format_skip,
-	forwarded_arguments,
-	read_push_tree,
-	reusable_green_push,
 	run_pre_push_unit,
 }