@joshuafolkken/kit 1.1035.0 → 1.1050.0

package/scripts/git/git-next-issues.ts

@@ -1,12 +1,14 @@
 import { git_gh_command } from './git-gh-command'
 import { has_any_label, NOT_DIRECTLY_RUNNABLE_LABELS } from './issue-labels'
+import { issue_rank, type DependencyRow } from './issue-rank'
 import { parse_json_array_safe } from './parse-json-array'
 import { open_issue_schema, type OpenIssueData } from './schemas'
 
 // The next-issues display printed when a workflow completes (#821): up to five open issues in
 // priority order, so the user picks the next run from the completion output instead of opening the
 // issue list. Priority is recency — a newer issue usually encodes the most current understanding
-// of the backlog — with the label-based exclusions below.
+// of the backlog — with the label-based exclusions below, under the ranking keys `issue-rank.ts`
+// defines (joshuafolkken/kit#2928).
 //
 // `prioritize` is also the order `epicrun` picks up `auto-ok` issues in (joshuafolkken/kit#906).
 // The two ask one question — which open issue outside an epic is run next — so they share one
@@ -37,6 +39,34 @@ function compare_newest_first(first: OpenIssueData, second: OpenIssueData): numb
 	return first.createdAt < second.createdAt ? 1 : -1
 }
 
+// A row's blockers by number. **Lossy across repositories**: a blocker elsewhere sharing a number
+// with a row here counts as one of its dependents. The listings this ranks are one repository's own,
+// and `backlog:next` re-ranks its offer from the qualified graph (`backlog-rank.ts`), so the cost is a
+// display row placed one slot off rather than a run started early.
+function dependency_row(issue: OpenIssueData): DependencyRow {
+	return {
+		key: String(issue.number),
+		blockers: (issue.blockedBy?.nodes ?? []).map((blocker) => String(blocker.number)),
+	}
+}
+
+// Every candidate in rank order, uncapped. `backlog:next` takes this rather than `prioritize`, so the
+// `run:solo` gate sees the whole ranking before anything is cut (joshuafolkken/kit#2928).
+function order(
+	issues: ReadonlyArray<OpenIssueData>,
+	completed_issue_number?: number,
+): Array<OpenIssueData> {
+	const candidates = issues
+		.filter((issue) => is_candidate(issue, completed_issue_number))
+		.toSorted(compare_newest_first)
+	const dependents = issue_rank.count_dependents(candidates.map((issue) => dependency_row(issue)))
+
+	return issue_rank.rank(candidates, (issue) => ({
+		labels: (issue.labels ?? []).map((label) => label.name),
+		dependents: dependents.get(String(issue.number)) ?? 0,
+	}))
+}
+
 // **This display deliberately does not drop a blocked issue, and the `auto-ok` pickup deliberately
 // does.** They share this ordering and differ on the set, which reads as an inconsistency and is not
 // one (joshuafolkken/kit#1005).
@@ -50,10 +80,7 @@ function prioritize(
 	issues: ReadonlyArray<OpenIssueData>,
 	completed_issue_number?: number,
 ): Array<OpenIssueData> {
-	return issues
-		.filter((issue) => is_candidate(issue, completed_issue_number))
-		.toSorted(compare_newest_first)
-		.slice(0, DISPLAY_LIMIT)
+	return order(issues, completed_issue_number).slice(0, DISPLAY_LIMIT)
 }
 
 // Empty input yields no lines at all — a bare header with nothing under it reads as an error.
@@ -90,6 +117,8 @@ async function fetch_next_issue_lines(completed_issue_number?: number): Promise<
 }
 
 const git_next_issues = {
+	DISPLAY_LIMIT,
+	order,
 	prioritize,
 	format_lines,
 	fetch_next_issue_lines,

package/scripts/git/git-preflight.ts

@@ -117,19 +117,37 @@ function refusal(problems: ReadonlyArray<string>): Error {
 	)
 }
 
-async function check(input: PreflightInput): Promise<void> {
+interface PreflightAnswer {
+	pr_target: Target | undefined
+	problems: Array<string>
+}
+
+async function answer(input: PreflightInput): Promise<PreflightAnswer> {
 	const { target, problems } = await resolve_target(input.cli_input)
 	// The classification and the evidence belong to the pull request, so a `--skip-pr` run asks neither.
 	const pr_target = input.will_open_pr ? target : undefined
 	const pr_problems = pr_target === undefined ? [] : await classification_problems(pr_target)
-	const all_problems = [...problems, ...pr_problems]
 
-	if (all_problems.length > 0) throw refusal(all_problems)
+	return { pr_target, problems: [...problems, ...pr_problems] }
+}
+
+// joshuafolkken/kit#2946: the unmet preconditions as a list, so `josh ship` can ask them before its
+// review and gate start instead of meeting the refusal at the commit stage.
+async function problems_of(input: PreflightInput): Promise<Array<string>> {
+	const { problems } = await answer(input)
+
+	return problems
+}
+
+async function check(input: PreflightInput): Promise<void> {
+	const { pr_target, problems } = await answer(input)
+
+	if (problems.length > 0) throw refusal(problems)
 
 	if (pr_target !== undefined) await announce_evidence(pr_target.branch_name)
 }
 
-const git_preflight = { check }
+const git_preflight = { check, problems_of }
 
 export type { PreflightInput }
 export { git_preflight }

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-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/gone-branch.ts

@@ -100,9 +100,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/issue-labels.ts

@@ -19,6 +19,11 @@ const RUN_SOLO_LABEL = 'run:solo'
 // (joshuafolkken/kit#2779). Without it an issue lacking `run:solo` could mean "judged parallel" or
 // "never judged", and `backlog:next` withholds the second (`epic-triage.ts`).
 const RUN_LANE_LABEL = 'run:lane'
+// Puts an issue at the head of the backlog's ranking (joshuafolkken/kit#2928). A person or a run may
+// apply it — a run only where it can cite a deadline or a stated urgency, or a policy a person wrote
+// (`backlogrun-steps.md`) — and **only a person removes it**: a run that could clear it could undo
+// the person's ordering. Read by `issue-rank.ts`, the one place the ranking keys are decided.
+const PRIORITY_HIGH_LABEL = 'priority:high'
 // Opts one issue outside any epic into unattended execution (joshuafolkken/kit#906). **Only a
 // person applies it.** `epicrun #<E>` approves the merges inside `#<E>`; this label is the only way
 // a person extends that approval past the epic's edge, so a label an AI could apply to itself would
@@ -212,6 +217,11 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: '0e8a16',
 		description: 'Judged safe to run beside others in a backlogrun',
 	},
+	{
+		name: PRIORITY_HIGH_LABEL,
+		color: 'e99695',
+		description: 'Offered first in a backlogrun; only a person removes it',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -322,6 +332,7 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	AUTO_OK_LABEL,
 	NEEDS_HUMAN_REVIEW_LABEL,
 	ALREADY_DONE_LABEL,
+	PRIORITY_HIGH_LABEL,
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
@@ -364,6 +375,7 @@ export {
 	NEEDS_HUMAN_REVIEW_LABEL,
 	NOT_DIRECTLY_RUNNABLE_LABELS,
 	OTHER_CHANGE_LABEL,
+	PRIORITY_HIGH_LABEL,
 	RELEASE_CLASSIFICATION_LABELS,
 	RELEASE_CLASSIFICATION_NAMES,
 	REPOSITORY_LABELS,

package/scripts/git/issue-rank.ts

@@ -0,0 +1,89 @@
+import {
+	BUG_LABEL,
+	has_label_name,
+	INTERRUPT_ROUTE_LABEL,
+	PRIORITY_HIGH_LABEL,
+	RUN_SOLO_LABEL,
+} from './issue-labels'
+
+// The keys that decide which open issue is offered first (joshuafolkken/kit#2928), defined once for
+// every ranking that asks: the `🗒 Next issues` display, the `auto-ok` pickup and `backlog:next`.
+//
+// In order: `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or
+// `route:interrupt`), then how many other open issues wait on it. Below those, the caller's own order
+// stands — the sort is stable, so recency and the defect-rate adjustment survive as the last key.
+//
+// **`run:solo` alone is not a key.** It means "runs alone", not "runs first": tidying that only touches
+// the verification path carries it too, and a low-priority one is not owed a place ahead of the queue.
+// Only a defect on that path is, because `wip-cap.md` holds a batch until it has merged.
+
+interface RankRow {
+	labels: ReadonlyArray<string>
+	dependents: number
+}
+
+// One open issue as its key and the keys of the issues it is blocked by. The caller names the key
+// format, so a ranking over listing rows and one over graph children each count in their own terms.
+interface DependencyRow {
+	key: string
+	blockers: ReadonlyArray<string>
+}
+
+const NO_DEPENDENTS = 0
+
+function flag(is_set: boolean): number {
+	return is_set ? 1 : 0
+}
+
+function is_priority(labels: ReadonlyArray<string>): boolean {
+	return has_label_name(labels, PRIORITY_HIGH_LABEL)
+}
+
+function is_verification_defect(labels: ReadonlyArray<string>): boolean {
+	if (has_label_name(labels, INTERRUPT_ROUTE_LABEL)) return true
+
+	return has_label_name(labels, BUG_LABEL) && has_label_name(labels, RUN_SOLO_LABEL)
+}
+
+// Negated so that the larger value sorts first under an ascending comparison.
+function keys_of(row: RankRow): ReadonlyArray<number> {
+	return [
+		-flag(is_priority(row.labels)),
+		-flag(is_verification_defect(row.labels)),
+		-row.dependents,
+	]
+}
+
+function compare(first: RankRow, second: RankRow): number {
+	const second_keys = keys_of(second)
+	const differences = keys_of(first).map((key, index) => key - (second_keys[index] ?? 0))
+
+	return differences.find((difference) => difference !== 0) ?? 0
+}
+
+// How many of the rows wait on each key. A blocker outside the rows counts nothing, because only an
+// open issue in the same pool can be held back by it.
+function count_dependents(rows: ReadonlyArray<DependencyRow>): ReadonlyMap<string, number> {
+	const counts = new Map<string, number>()
+
+	for (const row of rows) {
+		const blockers = new Set(row.blockers)
+
+		for (const blocker of blockers) counts.set(blocker, (counts.get(blocker) ?? NO_DEPENDENTS) + 1)
+	}
+
+	return counts
+}
+
+// The items in rank order, ties kept in the order they arrived.
+function rank<T>(items: ReadonlyArray<T>, row_of: (item: T) => RankRow): Array<T> {
+	return items
+		.map((item) => ({ item, row: row_of(item) }))
+		.toSorted((first, second) => compare(first.row, second.row))
+		.map((entry) => entry.item)
+}
+
+const issue_rank = { compare, count_dependents, is_priority, is_verification_defect, rank }
+
+export { issue_rank }
+export type { DependencyRow, RankRow }

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'
@@ -482,14 +481,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 +492,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/pretool-guard-cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { pretool_outcome_async } from './pretool-guard'
+
+// The `PreToolUse` hook's entry, kept apart from the composition in `pretool-guard.ts`
+// (joshuafolkken/kit#2922). The hook bundles are built with `splitting: true`, which moves a module
+// imported by two entries into a shared chunk — and `codex-hook-adapter.ts` imports `pretool-guard.ts`.
+// Its self-invoke went into that chunk, whose `import.meta.url` never equals the launched
+// `dist/hooks/pretool-guard.js`, so the bundled hook ran no guard at all and every refusal failed open.
+// An entry nothing imports keeps the self-invoke in the file that is actually launched.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
+	else {
+		const raw_payload = await text(process.stdin)
+
+		hook_decision.load_environment_file()
+		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
+	}
+}