@joshuafolkken/kit 1.1035.0 → 1.1050.0

package/scripts/backlog/backlog-pool.ts

@@ -37,6 +37,9 @@ const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALRE
 // `tracked` is the narrowed set `epic_index.withheld_children` builds, not every child an epic
 // tracks (joshuafolkken/kit#1668) — the narrowing itself is defined there, once, for this half and
 // `auto-ok:next` alike.
+// The part of the context that decides which rows the standalone half considers at all.
+type ConsideredContext = Pick<StandaloneContext, 'tracked' | 'exclude' | 'repo'>
+
 interface StandaloneContext {
 	tracked: ReadonlyMap<number, number>
 	exclude: ReadonlyArray<number>
@@ -135,26 +138,28 @@ function standalone_rows(issues: ReadonlyArray<OpenIssueData>): ReadonlyArray<Op
 // are actually going to offer their children and applied here for the same reason. Which rows those
 // are is `epic_index.withheld_children`'s answer, not a second test made here. A row the caller
 // excluded is out of the pool entirely rather than merely unoffered: it has just merged.
-function is_considered(issue: OpenIssueData, context: StandaloneContext): boolean {
+function is_considered(issue: OpenIssueData, context: ConsideredContext): boolean {
 	return !context.tracked.has(issue.number) && !context.exclude.includes(issue.number)
 }
 
 // The standalone half, in the buckets the verdict is read from.
 //
-// The order is `git_next_issues.prioritize`'s and not a second one — the same ranking the
-// `🗒 Next issues` display and `auto-ok:next` already answer with, cap included, so the three cannot
-// disagree about what comes next. Anything it withholds is still open work: `needs-decision` is
-// waiting on a person, and everything else — a standing blocker, a run already in progress, a row
-// past the cap — resolves on its own and is waiting on time. **The cap is one of those**: a sixth
-// runnable standalone issue is reported as waiting rather than offered, and the next ask offers it
-// once one of the five above it merges, so the backlog drains without it ever being lost. That is
-// the cost of having one ranking rather than two, and `docs/josh-commands.md` states it.
+// The order is `git_next_issues.order`'s and not a second one — the same ranking the
+// `🗒 Next issues` display and `auto-ok:next` already answer with, so the three cannot disagree about
+// what comes next. Anything it withholds is still open work: `needs-decision` is waiting on a person,
+// and everything else — a standing blocker, a run already in progress — resolves on its own and is
+// waiting on time.
+//
+// **The display's cap is not applied here** (joshuafolkken/kit#2928). Cut at this point, a sixth
+// runnable `run:solo` issue never reached the gate that holds back what is ranked below it, so the
+// cap is applied after that gate instead (`backlog-rank.ts`). A row past it is still reported as
+// waiting and offered by a later ask, so the backlog drains without it ever being lost.
 function classify_standalone(
 	issues: ReadonlyArray<OpenIssueData>,
 	context: StandaloneContext,
 ): Classification {
 	const considered = issues.filter((issue) => is_considered(issue, context))
-	const runnable = git_next_issues.prioritize(
+	const runnable = git_next_issues.order(
 		considered.filter((issue) => auto_ok_cli.is_runnable(issue, context.tracked, context.exclude)),
 	)
 	const offered = new Set(runnable.map((issue) => issue.number))
@@ -301,11 +306,26 @@ function merge_classifications(left: Classification, right: Classification): Cla
 	}
 }
 
+// The keys of the rows the standalone half considers — the rows the offer's cap bounds. An issue an
+// opted-in epic tracks is that epic's child here, and never capped, exactly as before.
+function standalone_keys(
+	issues: ReadonlyArray<OpenIssueData>,
+	context: ConsideredContext,
+): ReadonlySet<string> {
+	return keys_of(
+		to_children(
+			standalone_rows(issues).filter((issue) => is_considered(issue, context)),
+			context.repo,
+		),
+	)
+}
+
 const backlog_pool = {
 	classify_standalone,
 	cross_epic_cycles,
 	running_set,
 	settle_standalone,
+	standalone_keys,
 	drop_excluded,
 	epic_classification,
 	is_epic_row,
@@ -319,4 +339,4 @@ const backlog_pool = {
 }
 
 export { backlog_pool }
-export type { StandaloneContext }
+export type { ConsideredContext, StandaloneContext }

package/scripts/backlog/backlog-rank.ts

@@ -0,0 +1,106 @@
+import type { BusyRead } from '#scripts/epic/epic-busy'
+import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
+import { epic_rank } from '#scripts/epic/epic-rank'
+import type { EpicNextResult } from '#scripts/epic/epic-report'
+import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
+import { git_next_issues } from '#scripts/git/git-next-issues'
+
+// What the backlog offers, in the order it is decided (joshuafolkken/kit#2928): rank, then the
+// `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
+// plan's first wave is what the run starts into an idle repository rather than an order the run never
+// takes.
+//
+// **The cap comes last.** It used to be applied while the standalone half was classified, before the
+// gate, so a `run:solo` issue ranked sixth or lower was cut before the gate could see it — and the
+// issues below it were offered past it. Cut after the gate, the cap only ever removes what the gate
+// would have offered, so it cannot hide a waiting `run:solo` issue from it. It still bounds only the
+// standalone rows, as it always has; an epic's children were never capped.
+
+// Every child the classification placed, in the order it placed them: the ranked candidates first,
+// then the waiting ones, then the ones waiting on a person.
+function everything_in(result: EpicNextResult): ReadonlyArray<EpicChild> {
+	const candidates = result.candidates.flatMap((bundle) => bundle.children)
+
+	return [...candidates, ...result.waiting, ...result.blocked_on_people]
+}
+
+// The ranking is `epic_rank.rank`, shared with a named epic's lanes.
+const { rank } = epic_rank
+
+// This repository's candidates re-ranked inside the result, so `backlog:plan` prints the order the
+// offer is decided in.
+function rank_result(result: EpicNextResult, repo: string): EpicNextResult {
+	if (result.verdict !== 'run') return result
+
+	const pool = everything_in(result)
+
+	return {
+		...result,
+		candidates: result.candidates.map((bundle) =>
+			bundle.repo === repo ? { ...bundle, children: rank(bundle.children, pool) } : bundle,
+		),
+	}
+}
+
+// The standalone rows past the cap, in offer order.
+function overflow_of(
+	offered: ReadonlyArray<EpicChild>,
+	standalone: ReadonlySet<string>,
+): ReadonlySet<string> {
+	const keys = offered.map((child) => epic_graph.key_of(child)).filter((key) => standalone.has(key))
+
+	return new Set(keys.slice(git_next_issues.DISPLAY_LIMIT))
+}
+
+function is_in(child: EpicChild, keys: ReadonlySet<string>): boolean {
+	return keys.has(epic_graph.key_of(child))
+}
+
+function cap(selection: SoloSelection, standalone: ReadonlySet<string>): SoloSelection {
+	const overflow = overflow_of(selection.offered, standalone)
+
+	if (overflow.size === 0) return selection
+
+	return {
+		...selection,
+		offered: selection.offered.filter((child) => !is_in(child, overflow)),
+		withheld: [
+			...selection.offered.filter((child) => is_in(child, overflow)),
+			...selection.withheld,
+		],
+	}
+}
+
+interface OfferInput {
+	candidates: ReadonlyArray<EpicChild>
+	pool: ReadonlyArray<EpicChild>
+	read: BusyRead
+	repo: string
+	// The keys of the standalone rows — the ones the cap bounds.
+	standalone: ReadonlySet<string>
+}
+
+function select(input: OfferInput): SoloSelection {
+	const ranked = rank(input.candidates, input.pool)
+
+	return cap(epic_solo.select(ranked, input.read, input.repo), input.standalone)
+}
+
+// `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.
+function gate(
+	result: EpicNextResult,
+	read: BusyRead,
+	repo: string,
+	standalone: ReadonlySet<string>,
+): SoloGate {
+	const pool = everything_in(result)
+
+	return epic_solo.gate(result, read, repo, (candidates) =>
+		select({ candidates, pool, read, repo, standalone }),
+	)
+}
+
+const backlog_rank = { everything_in, gate, rank, rank_result, select }
+
+export { backlog_rank }
+export type { OfferInput }

package/scripts/backlog/backlog-waves.ts

@@ -4,9 +4,9 @@ import { epic_cross_repo } from '#scripts/epic/epic-cross-repo'
 import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
-import { epic_solo } from '#scripts/epic/epic-solo'
 import { has_label_name, IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
 import { backlog_plan, type PlanContext } from './backlog-plan'
+import { backlog_rank } from './backlog-rank'
 
 // The order a `backlogrun` takes, wave by wave, before it starts (joshuafolkken/kit#2778).
 //
@@ -14,13 +14,13 @@ import { backlog_plan, type PlanContext } from './backlog-plan'
 // made from, so the order past the first answer was left for a person to work out by hand. This plays
 // the asks forward under one assumption: **every issue of a wave merges before the next wave starts**.
 //
-// **No rule is written twice.** The first wave is `epic_solo.select` over the very candidates
-// `backlog:next` resolves, asked of an idle repository — so it is what `backlog:next` prints when
-// nothing is running. Each later wave marks the earlier waves closed and re-classifies the same pool
+// **No rule is written twice.** The first wave is `backlog_rank.select` — rank, `run:solo` gate, cap —
+// over the very candidates `backlog:next` resolves, asked of an idle repository — so it is what
+// `backlog:next` prints when nothing is running (joshuafolkken/kit#2928). Each later wave marks the earlier waves closed and re-classifies the same pool
 // through `epic_classify.classify_children` with the resolver `epic:next` sorted it with the first
 // time — `epic_cross_repo.resolve_cross_repo`, so a blocker in another repository still waits for its
 // release rather than counting as done on close — then puts the runnable set through
-// `epic_solo.select` again.
+// `backlog_rank.select` again.
 
 const IDLE: BusyRead = { kind: 'idle' }
 const CLOSED = 'CLOSED'
@@ -45,14 +45,6 @@ function is_running(child: EpicChild): boolean {
 	return has_label_name(child.labels, IN_PROGRESS_LABEL)
 }
 
-// Every child the classification placed, in the order it placed them: the ranked candidates first,
-// then the waiting ones, then the ones waiting on a person.
-function everything_in(result: EpicNextResult): ReadonlyArray<EpicChild> {
-	const candidates = result.candidates.flatMap((bundle) => bundle.children)
-
-	return [...candidates, ...result.waiting, ...result.blocked_on_people]
-}
-
 function as_closed(child: EpicChild, done: ReadonlySet<string>): EpicChild {
 	return done.has(epic_graph.key_of(child)) ? { ...child, state: CLOSED } : child
 }
@@ -63,24 +55,35 @@ interface WavePool {
 	children: ReadonlyArray<EpicChild>
 	running: ReadonlySet<string>
 	repo: string
+	standalone: ReadonlySet<string>
 }
 
-function pool_of(result: EpicNextResult, repo: string): WavePool {
-	const all = everything_in(result)
+function pool_of(result: EpicNextResult, repo: string, standalone: ReadonlySet<string>): WavePool {
+	const all = backlog_rank.everything_in(result)
 
 	return {
 		children: all.filter((child) => !is_running(child)),
 		running: epic_outside_blocker.running_keys(all),
 		repo,
+		standalone,
 	}
 }
 
-function offer(runnable: ReadonlyArray<EpicChild>, repo: string): ReadonlyArray<EpicChild> {
-	return epic_solo.select(runnable, IDLE, repo).offered
+function offer(
+	candidates: ReadonlyArray<EpicChild>,
+	children: ReadonlyArray<EpicChild>,
+	pool: WavePool,
+): ReadonlyArray<EpicChild> {
+	const { repo, standalone } = pool
+
+	return backlog_rank.select({ candidates, pool: children, read: IDLE, repo, standalone }).offered
 }
 
-function first_wave(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
-	return offer(epic_report.candidates_for_repo(result, repo), repo)
+// Ranked against the whole result, exactly as `backlog:next` ranks it, so the two agree.
+function first_wave(result: EpicNextResult, pool: WavePool): ReadonlyArray<EpicChild> {
+	const candidates = epic_report.candidates_for_repo(result, pool.repo)
+
+	return offer(candidates, backlog_rank.everything_in(result), pool)
 }
 
 function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<EpicChild> {
@@ -93,25 +96,31 @@ function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<Epi
 
 	return offer(
 		runnable.filter((child) => child.repo === pool.repo),
-		pool.repo,
+		children,
+		pool,
 	)
 }
 
 // Each wave is closed before the next is asked for; a wave that offers nothing ends the plan, which
-// the pool's size bounds because every wave closes at least one child.
-function build(result: EpicNextResult, repo: string): WavePlan {
-	const pool = pool_of(result, repo)
+// the pool's size bounds because every wave closes at least one child. `standalone` names the rows the
+// offer's cap bounds; left empty, no wave is capped.
+function build(
+	result: EpicNextResult,
+	repo: string,
+	standalone: ReadonlySet<string> = new Set(),
+): WavePlan {
+	const pool = pool_of(result, repo, standalone)
 	const done = new Set<string>()
 	const waves: Array<ReadonlyArray<EpicChild>> = []
 
-	for (let wave = first_wave(result, repo); wave.length > 0; wave = next_wave(pool, done)) {
+	for (let wave = first_wave(result, pool); wave.length > 0; wave = next_wave(pool, done)) {
 		waves.push(wave)
 		for (const child of wave) done.add(epic_graph.key_of(child))
 	}
 
-	const unreached = everything_in(result).filter(
-		(child) => child.repo === repo && !done.has(epic_graph.key_of(child)),
-	)
+	const unreached = backlog_rank
+		.everything_in(result)
+		.filter((child) => child.repo === repo && !done.has(epic_graph.key_of(child)))
 
 	return { waves, unreached }
 }
@@ -139,10 +148,14 @@ function unreached_lines(plan: WavePlan, context: PlanContext): Array<string> {
 	)
 }
 
-function format_waves(result: EpicNextResult, context: PlanContext): string {
+function format_waves(
+	result: EpicNextResult,
+	context: PlanContext,
+	standalone: ReadonlySet<string> = new Set(),
+): string {
 	if (result.verdict === 'error') return backlog_plan.format_unusable(result)
 
-	const plan = build(result, context.repo)
+	const plan = build(result, context.repo, standalone)
 	const waves = plan.waves.map((wave, index) => wave_line(wave, index, context.repo))
 
 	return [

package/scripts/build/build-hooks.ts

@@ -20,6 +20,11 @@ const OUT_DIR = path.join(PACKAGE_DIR, 'dist', 'hooks')
 // splitting keeps every entry in its own file with its own `import.meta.url`, so an imported guard's
 // `import.meta.url` never equals `argv[1]` and only the file actually launched runs its main.
 //
+// **The flip side: an entry another entry imports loses its main** (joshuafolkken/kit#2922). Splitting
+// moves a module two entries share into a chunk, so a launched hook whose own module is imported
+// elsewhere becomes a re-export stub that runs nothing. Each launched hook is therefore a `*-cli.ts`
+// file holding only the self-invoke, which no other module imports.
+//
 // `packages: 'external'` keeps bare dependencies as runtime imports the consumer resolves from kit's
 // node_modules, exactly as the library bundles do, while kit's internal `#scripts/*` graph is inlined.
 // No shebang banner is added: unlike `dist/josh.js` (the `bin.josh` entry, executed directly), a hook
@@ -35,9 +40,9 @@ interface HookBundle {
 // `delivered-rules` (the fourth guard) has no self-invoke, so it stays inlined.
 const HOOK_BUNDLES: ReadonlyArray<HookBundle> = [
 	{ source: 'scripts/hooks/codex-hook-adapter.ts', out: 'codex-hook-adapter' },
-	{ source: 'scripts/hooks/pretool-guard.ts', out: 'pretool-guard' },
+	{ source: 'scripts/hooks/pretool-guard-cli.ts', out: 'pretool-guard' },
 	{ source: 'scripts/hooks/stop-guard.ts', out: 'stop-guard' },
-	{ source: 'scripts/hooks/format-edited-file.ts', out: 'format-edited' },
+	{ source: 'scripts/hooks/format-edited-cli.ts', out: 'format-edited' },
 	{ source: 'scripts/josh/session-language-cli.ts', out: 'session-lang' },
 	{ source: 'scripts/hooks/batch-guard.ts', out: 'batch-guard' },
 	{ source: 'scripts/delegation/investigation-guard.ts', out: 'investigation-guard' },

package/scripts/delegation/delegation-policy.ts

@@ -92,6 +92,17 @@ const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
 		verifier:
 			'the parent opens the cited lines; a conclusion those lines do not support fails there, and reading a handful of cited regions costs far less than redoing the reading. The unit reports what the code does and never what to change — deciding that is `diagnosis`, which stays kept, so a unit returning a root cause would be delegating the rejected row under this name',
 	},
+	{
+		name: 'lane-failure-investigation',
+		// The `backlogrun` parent's counterpart of `investigation` (joshuafolkken/kit#2947). The parent
+		// orchestrates and never implements, yet it read a failed lane's logs, records and sources in its
+		// own context — about 150 grep / cat / sed calls on 2026-10-02 — and every later request of the
+		// batch re-read them. The verifier is `investigation`'s, and so is the boundary: the unit reports
+		// what happened, and what the parent does about it (park, re-dispatch, file) stays its own call.
+		does: "find out why a lane's child stopped, failed or conflicted — its output log, run records, PR checks and the files they name — and return the conclusion plus the `file:line` or log-line citations that support it, never the text read, so the batch parent's context stays the size its orchestration needs",
+		verifier:
+			'the parent opens the cited lines and re-reads the child with `pnpm josh issue:state`; a conclusion those do not support fails there. The unit reports what happened and never what to do — parking, re-dispatching or filing stays with the parent, so a wrong account is caught before it is acted on',
+	},
 ]
 
 // Steps that were considered and are **not** delegatable, kept as a list rather than dropped: the

package/scripts/document/document-byte-budget.ts

@@ -73,7 +73,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/issue-comments.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/issue-fold-existing.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/needs-human-review.md', bytes: 8192 },
-	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 28_672 },
+	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 24_576 },
 	// `pre-gate-cut.md` left this per-document budget in joshuafolkken/kit#2289: it became a point-of-use
 	// document, so its bytes are now held by every entry's total read (`entry-read-budget.ts`) and the
 	// two budgets must not hold it twice — the reachability line moved it from `unreached` to
@@ -81,7 +81,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands.md', bytes: 180_224 },
+	{ path: 'docs/josh-commands.md', bytes: 184_320 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/cross-repo-epic.md', bytes: 4096 },
@@ -100,11 +100,11 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow/proposal-request.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 28_672 },
 	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 57_344 },
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 45_056 },
 	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 20_480 },
 	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 16_384 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
 	{ path: 'prompts/review-rubric.md', bytes: 20_480 },
 	{ path: 'prompts/review.md', bytes: 20_480 },

package/scripts/document/entry-read-budget.ts

@@ -77,11 +77,12 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// planning entries): kickoff has no headroom, so the addition was offset by tightening that file's
 	// heartbeat prose, keeping every entry within its existing block.
 	// joshuafolkken/kit#2762 moved the rationale of five point-of-use documents to
-	// `docs/maintainers/*-rationale.md`, and the ratchet holds the reduction.
+	// `docs/maintainers/*-rationale.md`, and the ratchet holds the reduction. joshuafolkken/kit#2895 did
+	// the same for eight more, lowering fullrun, halfrun and backlogrun one block each.
 	{ entry: 'kickoff', bytes: 229_376 },
-	{ entry: 'fullrun', bytes: 229_376 },
-	{ entry: 'halfrun', bytes: 229_376 },
-	{ entry: 'backlogrun', bytes: 233_472 },
+	{ entry: 'fullrun', bytes: 225_280 },
+	{ entry: 'halfrun', bytes: 225_280 },
+	{ entry: 'backlogrun', bytes: 229_376 },
 	{ entry: LANE_CHILD, bytes: 77_824 },
 ]
 

package/scripts/epic/epic-lane-offer.ts

@@ -6,6 +6,7 @@ import {
 	type RepoAnswer,
 } from './epic-candidate-confirm'
 import { epic_graph, type EpicChild } from './epic-graph'
+import { epic_rank } from './epic-rank'
 import type { EpicVerdict } from './epic-report'
 import { epic_solo } from './epic-solo'
 import { epic_triage, type TriageVerdict } from './epic-triage'
@@ -107,6 +108,15 @@ function candidates_in(pool: RepoPool, repo: string): RepoPool {
 	return { ...pool, candidates: pool.candidates.filter((child) => child.repo === repo) }
 }
 
+// A pool's candidates for the repository in `epic_rank.rank` order — the ranking `backlog:next` offers
+// in (joshuafolkken/kit#2928), counted against the pool's own graph. **Within a pool, not across
+// pools**: the pool order is the order a person named the epics in, and that stays the outer key.
+function ranked_in(pool: RepoPool, repo: string): RepoPool {
+	const scoped = candidates_in(pool, repo)
+
+	return { ...scoped, candidates: epic_rank.rank(scoped.candidates, pool.context.children) }
+}
+
 // One pool's candidates, minus every one an earlier pool already carries. `seen` is mutated rather
 // than rebuilt because the earlier pools' claim is what the later one is filtered against.
 function unseen_candidates(pool: RepoPool, seen: Set<string>): RepoPool {
@@ -184,24 +194,6 @@ function solo_offer(
 	return { ...answer, children: offered, notice: offered_notice(offered, read, request) }
 }
 
-// The confirmation walk stops at the free-lane count, so a `run:solo` candidate ranked past it — or
-// in a pool past it — would never reach `solo_offer` to be preferred. Into an idle repository the
-// first pool holding one is asked first, with it at its head through the same `epic_solo.prefer` the
-// offer applies (joshuafolkken/kit#2778). The candidate stays in its own pool, because a pool carries
-// the graph it is confirmed against.
-function solo_first(pools: ReadonlyArray<RepoPool>, read: BusyRead): ReadonlyArray<RepoPool> {
-	if (read.kind !== 'idle') return pools
-
-	const index = pools.findIndex((pool) => pool.candidates.some((child) => epic_solo.is_solo(child)))
-	const pool = pools[index]
-
-	if (pool === undefined) return pools
-
-	const lifted = { ...pool, candidates: epic_solo.prefer(pool.candidates, read) }
-
-	return [lifted, ...pools.filter((other) => other !== pool)]
-}
-
 // The repository is asked how full it is **before** any candidate is confirmed, for the reason
 // joshuafolkken/kit#1121 records: a repository with no free lane is handed nothing, so the relations
 // request that would confirm a candidate there buys an answer nobody reads — and a polling `epicrun`
@@ -247,10 +239,7 @@ async function offer_for_repo(
 		}
 	}
 
-	const for_repo = solo_first(
-		dedupe_pools(pools.map((pool) => candidates_in(pool, request.repo))),
-		read,
-	)
+	const for_repo = dedupe_pools(pools.map((pool) => ranked_in(pool, request.repo)))
 
 	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request)
 }

package/scripts/epic/epic-rank.ts

@@ -0,0 +1,37 @@
+import { issue_rank } from '#scripts/git/issue-rank'
+import { epic_graph, type EpicChild } from './epic-graph'
+
+// `issue-rank.ts`'s keys over graph children (joshuafolkken/kit#2928), for both offer paths that hand
+// out children: `backlog:next` (`backlog-rank.ts`) and a named epic's `epic:next --lanes`
+// (`epic-lane-offer.ts`). One ranking, so the two cannot disagree about which child goes first.
+
+const CLOSED = 'CLOSED'
+
+// How many open issues of the pool wait on each child. Only the pool is counted: it is every issue the
+// caller may run, and an issue outside it is not one this ranking can start sooner.
+function dependents_of(pool: ReadonlyArray<EpicChild>): ReadonlyMap<string, number> {
+	return issue_rank.count_dependents(
+		pool
+			.filter((child) => child.state !== CLOSED)
+			.map((child) => ({
+				key: epic_graph.key_of(child),
+				blockers: child.blocked_by.map((blocker) => epic_graph.blocker_key(blocker)),
+			})),
+	)
+}
+
+function rank(
+	children: ReadonlyArray<EpicChild>,
+	pool: ReadonlyArray<EpicChild>,
+): Array<EpicChild> {
+	const dependents = dependents_of(pool)
+
+	return issue_rank.rank(children, (child) => ({
+		labels: child.labels,
+		dependents: dependents.get(epic_graph.key_of(child)) ?? 0,
+	}))
+}
+
+const epic_rank = { dependents_of, rank }
+
+export { epic_rank }

package/scripts/epic/epic-solo.ts

@@ -21,12 +21,11 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // it, so it is not starved by the lanes it is waiting on. A listing that could not be read is not an
 // idle repository — the same fail-safe answer `epic_busy` gives.
 //
-// **An idle repository takes its first `run:solo` candidate ahead of the ranking**
-// (joshuafolkken/kit#2778). An issue carries the label because its defect reaches the verification
-// path, and `wip-cap.md` resumes a batch only once that has merged — so an ordinary candidate ranked
-// ahead of it would spend a whole wave running alone, then hold the fix back behind its own merge.
-// While lanes are running the ranking stands: nothing overtakes a waiting `run:solo` candidate, and
-// the ones ahead of it keep their lanes.
+// **The label does not move a candidate up the ranking** (joshuafolkken/kit#2928, reversing
+// joshuafolkken/kit#2778). `run:solo` means "runs alone", and tidying that merely touches the
+// verification path carries it as well as a defect that breaks it. Which of them goes first is the
+// ranking's question — `issue-rank.ts` puts a verification-path defect at the head — so an idle
+// repository takes the candidates in rank order like any other.
 
 const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
 
@@ -75,32 +74,21 @@ function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelect
 	return { offered: [], withheld: [...children], notice }
 }
 
-// The ranking with the first `run:solo` candidate moved to the head — but only into an idle
-// repository, the one place it may start. Anywhere else the ranking is returned as it was.
-function prefer(children: ReadonlyArray<EpicChild>, read: BusyRead): ReadonlyArray<EpicChild> {
-	const solo = children.find((child) => is_solo(child))
-
-	if (solo === undefined || read.kind !== 'idle') return children
-
-	return [solo, ...children.filter((child) => child !== solo)]
-}
-
 // Where the first `run:solo` candidate sits decides what starts: everything when there is none, the
-// candidates ahead of it when lanes are running, and it alone into an idle repository.
+// candidates ahead of it when it is not first, and it alone once it heads an idle repository's ranking.
 function select_candidates(
 	children: ReadonlyArray<EpicChild>,
 	read: BusyRead,
 	repo: string,
 ): SoloSelection {
-	const ordered = prefer(children, read)
-	const index = ordered.findIndex((child) => is_solo(child))
-	const solo = ordered[index]
+	const index = children.findIndex((child) => is_solo(child))
+	const solo = children[index]
 
-	if (solo === undefined) return first_of(ordered, ordered.length)
-	if (index > 0) return first_of(ordered, index)
-	if (read.kind === 'idle') return first_of(ordered, 1)
+	if (solo === undefined) return first_of(children, children.length)
+	if (index > 0) return first_of(children, index)
+	if (read.kind === 'idle') return first_of(children, 1)
 
-	return none_of(ordered, waiting_message(solo.number, repo))
+	return none_of(children, waiting_message(solo.number, repo))
 }
 
 // An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
@@ -129,11 +117,24 @@ function withhold(result: EpicNextResult, repo: string, selection: SoloSelection
 	}
 }
 
+// What decides the selection. `select` by default; `backlog:next` passes one that ranks before it and
+// caps after it (`backlog-rank.ts`), so the gate itself is written once.
+type SoloSelector = (
+	children: ReadonlyArray<EpicChild>,
+	read: BusyRead,
+	repo: string,
+) => SoloSelection
+
 // Only a `run` answer offers anything, so every other verdict passes through untouched.
-function gate(result: EpicNextResult, read: BusyRead, repo: string): SoloGate {
+function gate(
+	result: EpicNextResult,
+	read: BusyRead,
+	repo: string,
+	selector: SoloSelector = select,
+): SoloGate {
 	if (result.verdict !== 'run') return { result }
 
-	const selection = select(epic_report.candidates_for_repo(result, repo), read, repo)
+	const selection = selector(epic_report.candidates_for_repo(result, repo), read, repo)
 	const gated = withhold(result, repo, selection)
 
 	return selection.notice === undefined
@@ -141,7 +142,7 @@ function gate(result: EpicNextResult, read: BusyRead, repo: string): SoloGate {
 		: { result: gated, notice: selection.notice }
 }
 
-const epic_solo = { gate, is_solo, prefer, select }
+const epic_solo = { gate, is_solo, select }
 
-export type { SoloGate, SoloSelection }
+export type { SoloGate, SoloSelection, SoloSelector }
 export { epic_solo }

package/scripts/git/git-command.ts

@@ -418,7 +418,7 @@ async function push(): Promise<void> {
 // has diverged is a state to fail loudly on rather than to grow a merge commit over. The name says
 // which of the two this is, as `merge_fast_forward` does beside `merge_branch`.
 async function pull_fast_forward(): Promise<void> {
-	await git_spawn.with_output('pull', ['--ff-only'])
+	await git_spawn.with_output_remote('pull', ['--ff-only'])
 }
 
 // Every local branch matching a `git branch --list` pattern, one name per line. The boolean below is

package/scripts/git/git-execa-error.ts

@@ -22,6 +22,11 @@ function has_timed_out(error: unknown): boolean {
 	return error.timedOut === true
 }
 
+// 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. Shared by every git spawn that carries a
+// budget: the push (`git-push-transport.ts`) and the fetch and pull (`git-spawn.ts`).
+const TIMEOUT_EXIT_CODE = 'timeout'
+
 // The error a spawned git command fails with. The exit code is carried on `cause` as well as in the
 // message, because callers branch on it rather than parse it: `git_command.push` reads 128 there to
 // decide whether to retry with `--set-upstream`.
@@ -32,4 +37,4 @@ function create_spawn_error(command: string, exit_code: number | undefined): Err
 	return new Error(error_message, { cause: { exit_code: exit_code_string } })
 }
 
-export { create_spawn_error, get_exit_code, has_timed_out }
+export { create_spawn_error, get_exit_code, has_timed_out, TIMEOUT_EXIT_CODE }