@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/backlog/backlog-drive-cli.ts

@@ -4,13 +4,11 @@ import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
-import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
 import { lane_registry } from '#scripts/lane/lane-registry'
-import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
-import { run_carry, type RunCarry } from '#scripts/run/run-carry'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
-import { run_merge_cli, type MergeResult } from '#scripts/run/run-merge-cli'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_merge_cli, type MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { z } from 'zod'
 import {
 	backlog_drive,
@@ -19,7 +17,9 @@ import {
 	type LoopPorts,
 	type OfferRead,
 } from './backlog-drive'
+import { backlog_drive_args, type DriveContext } from './backlog-drive-args'
 import { backlog_drive_finish } from './backlog-drive-finish'
+import { backlog_drive_launch } from './backlog-drive-launch'
 import { backlog_drive_named } from './backlog-drive-named'
 import { backlog_drive_named_offer } from './backlog-drive-named-offer'
 import { backlog_drive_offer_argv } from './backlog-drive-offer-argv'
@@ -44,114 +44,7 @@ const FAILURE_EXIT_CODE = 1
 const should_forward_stderr = true
 const POLL_MS = 5000
 const OFFER_MS = 60_000
-const MS_PER_MINUTE = 60_000
 const FIRST_LINE = 0
-const LIST_SEPARATOR = ','
-const COUNT_PATTERN = /^\d+$/u
-const ISSUE_PATTERN = /^[1-9]\d*$/u
-const USAGE =
-	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>] [--stopped <n>]'
-
-const OPTIONS = {
-	active: { type: 'string' },
-	await: { type: 'string' },
-	exclude: { type: 'string' },
-	idle: { type: 'string' },
-	max: { type: 'string' },
-	only: { type: 'boolean' },
-	owner: { type: 'string' },
-	stopped: { type: 'string' },
-	window: { type: 'string' },
-} as const
-
-interface DriveContext {
-	owner: string
-	active: string | undefined
-	// Flags forwarded to `backlog:offer` unchanged — the declared budgets.
-	forwarded: ReadonlyArray<string>
-	exclude: ReadonlyArray<string>
-	awaited: ReadonlyArray<string>
-	window_ms: number | undefined
-	window: string | undefined
-	is_only: boolean
-	// The child whose merge answered `stop` before the hand-back: the resumed run starts already stopping.
-	stopped: string | undefined
-}
-
-type Values = Partial<Record<Exclude<keyof typeof OPTIONS, 'only'>, string>> & { only?: boolean }
-
-function read_values(argv: ReadonlyArray<string>): Values | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-// A comma list of issue numbers; one entry that is not an issue number refuses the whole list.
-function to_issues(raw: string | undefined): ReadonlyArray<string> | undefined {
-	if (raw === undefined) return []
-
-	const issues = raw.split(LIST_SEPARATOR)
-
-	return issues.some((issue) => !ISSUE_PATTERN.test(issue)) ? undefined : issues
-}
-
-function forwarded_of(values: Values): ReadonlyArray<string> | undefined {
-	const pairs = (['max', 'idle'] as const).filter((name) => values[name] !== undefined)
-
-	if (pairs.some((name) => !COUNT_PATTERN.test(values[name] ?? ''))) return undefined
-
-	return pairs.flatMap((name) => [`--${name}`, values[name] ?? ''])
-}
-
-// An absent window is no bound; a present one must be a count, which `is_valid_window` checks first.
-function window_of(raw: string | undefined): number | undefined {
-	return raw === undefined ? undefined : Number(raw) * MS_PER_MINUTE
-}
-
-function is_valid_window(raw: string | undefined): boolean {
-	return raw === undefined || COUNT_PATTERN.test(raw)
-}
-
-function is_valid_single(values: Values): boolean {
-	const is_valid_stopped = values.stopped === undefined || ISSUE_PATTERN.test(values.stopped)
-
-	return is_valid_stopped && is_valid_window(values.window)
-}
-
-function owner_of(values: Values | undefined): string | undefined {
-	const owner = values?.owner
-
-	return owner !== undefined && COUNT_PATTERN.test(owner) ? owner : undefined
-}
-
-function to_context(values: Values, owner: string): DriveContext | undefined {
-	if (!is_valid_single(values)) return undefined
-
-	const forwarded = forwarded_of(values)
-	const exclude = to_issues(values.exclude)
-	const awaited = to_issues(values.await)
-
-	if (forwarded === undefined || exclude === undefined || awaited === undefined) return undefined
-
-	const window_ms = window_of(values.window)
-
-	return {
-		owner,
-		active: values.active,
-		forwarded,
-		exclude,
-		awaited,
-		window_ms,
-		window: values.window,
-		is_only: values.only === true,
-		stopped: values.stopped,
-	}
-}
-
-function parse(argv: ReadonlyArray<string>): DriveContext | undefined {
-	const values = read_values(argv)
-	const owner = owner_of(values)
-
-	return values === undefined || owner === undefined ? undefined : to_context(values, owner)
-}
 
 // The `--json` object `backlog:offer` prints, keyed under its `JSON_KEY`.
 const offer_read_schema = z.object({
@@ -235,14 +128,6 @@ async function merge(issue: string, owner: string): Promise<MergeResult> {
 	return result
 }
 
-async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
-	await backlog_drive_owner.assert_current(owner)
-
-	const outcome = await lane_launch_cli.launch_lane({ issue, stash: undefined })
-
-	return outcome.kind
-}
-
 // `lane:await`'s re-confirmed check, one state per child. A child already gone when the loop starts —
 // a restart after it ended — is read as having appeared, so it is collected after the re-confirm window
 // rather than waited on until the never-appeared timeout. One that never appeared is collected too:
@@ -278,17 +163,6 @@ async function open_lanes(): Promise<ReadonlyArray<string>> {
 	return lanes.filter((lane) => !lane.is_stranded).map((lane) => lane.issue)
 }
 
-function resume_line(state: DriveState, context: DriveContext): string {
-	const exclude = [...new Set([...context.exclude, ...state.exclude])]
-	const flags = ['--owner', context.owner, '--active', state.active, ...context.forwarded]
-
-	if (exclude.length > 0) flags.push('--exclude', exclude.join(LIST_SEPARATOR))
-	if (context.window !== undefined) flags.push('--window', context.window)
-	if (state.stopped_by !== undefined) flags.push('--stopped', state.stopped_by)
-
-	return `resume: ${flags.join(' ')}`
-}
-
 function end_line(end: DriveEnd): string {
 	const token = end.token === undefined || end.token === end.reason ? [] : [end.token]
 	const issue = end.issue === undefined ? [] : [`#${end.issue}`]
@@ -306,7 +180,7 @@ function ports_of(
 		is_finished: finished_checker(seeded),
 		merge: async (issue) => await merge(issue, context.owner),
 		offer: async (state) => await read_offer(state, context),
-		launch: async (issue) => await launch(issue, context.owner),
+		launch: async (issue) => await backlog_drive_launch.launch(issue, context.owner),
 		free_lanes: backlog_ready.drive_free_lane_count,
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
@@ -345,7 +219,7 @@ async function drive(context: DriveContext): Promise<number> {
 	const end = await backlog_drive.run_loop(last.state, config, ports_of(context, seeded, last))
 
 	console.info(end_line(end))
-	console.info(resume_line(last.state, context))
+	console.info(backlog_drive_args.resume_line(last.state, context))
 
 	return SUCCESS_EXIT_CODE
 }
@@ -361,10 +235,10 @@ async function run_safe(context: DriveContext): Promise<number> {
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const context = parse(argv)
+	const context = backlog_drive_args.parse(argv)
 
 	if (context === undefined) {
-		console.error(USAGE)
+		console.error(backlog_drive_args.USAGE)
 
 		return FAILURE_EXIT_CODE
 	}
@@ -384,8 +258,8 @@ const backlog_drive_cli = {
 	merge,
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
-	parse,
-	resume_line,
+	parse: backlog_drive_args.parse,
+	resume_line: backlog_drive_args.resume_line,
 	to_offer,
 }
 

package/scripts/backlog/backlog-drive-launch.ts

@@ -0,0 +1,39 @@
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import { backlog_drive_owner } from './backlog-drive-owner'
+
+// The driver's lane launch (joshuafolkken/kit#3272). The parent that ran `josh latest` in the primary
+// checkout leaves its rewritten lock file in a stash under this message — `backlogrun-lanes.md` →
+// "Once per repository, before the first lane opens" — and the lane that pops it carries the update
+// into its pull request. **The stash itself is the "first lane" marker**: each launch asks whether it
+// is still on the stack, and the pop that `lane:launch --stash` runs consumes it, so the first launch
+// after the push takes it and every later one finds nothing. A restarted driver needs no memory of
+// which lane was first. Two entries under the message are a state a person resolves, so neither is
+// guessed at — the launch goes ahead without one, as `stash:pop` would refuse it anyway. That skip is
+// said on stderr, because `stash:pop` refusing would have been heard and a silent skip would let the
+// update never reach a pull request.
+const LATEST_STASH_MESSAGE = 'backlogrun: josh latest before lanes'
+
+async function latest_stash(): Promise<string | undefined> {
+	const selection = git_stash.select(await git_stash.list(), LATEST_STASH_MESSAGE)
+
+	if (selection.kind === 'ambiguous') {
+		console.error(
+			`Launching without the "${LATEST_STASH_MESSAGE}" stash: ${selection.selectors.join(', ')} all match — keep one.`,
+		)
+	}
+
+	return selection.kind === 'match' ? LATEST_STASH_MESSAGE : undefined
+}
+
+async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
+	await backlog_drive_owner.assert_current(owner)
+
+	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
+
+	return outcome.kind
+}
+
+const backlog_drive_launch = { LATEST_STASH_MESSAGE, launch }
+
+export { backlog_drive_launch }

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -1,8 +1,8 @@
 import { EPIC_LABEL, has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
-import type { RunCarry } from '#scripts/run/run-carry'
-import type { MergeResult } from '#scripts/run/run-merge-cli'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_named } from './backlog-drive-named'
@@ -58,9 +58,7 @@ function settled_outcome(state: IssueState): MergeResult['outcome'] | undefined
 async function classify(issue: string, named: OfferRead, owner: string): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
-	if (result.kind !== 'state') {
-		return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
-	}
+	if (result.kind !== 'state') return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
 
 	const outcome = settled_outcome(result.state)
 

package/scripts/backlog/backlog-drive-named.ts

@@ -1,8 +1,8 @@
 import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
-import { run_carry, type RunCarry } from '#scripts/run/run-carry'
-import type { RunEvent } from '#scripts/run/run-event-stream'
-import type { MergeResult } from '#scripts/run/run-merge-cli'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_restore } from './backlog-drive-restore'
 import { backlog_named } from './backlog-named'

package/scripts/backlog/backlog-drive-offer-argv.ts

@@ -1,4 +1,4 @@
-import type { RunCarry } from '#scripts/run/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import type { DriveState } from './backlog-drive'
 
 const LIST_SEPARATOR = ','

package/scripts/backlog/backlog-drive-owner.ts

@@ -1,4 +1,4 @@
-import { run_carry, type RunCarry } from '#scripts/run/run-carry'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 
 function owns_record(carry: RunCarry, owner: string): boolean {
 	const current = run_carry.owner_of(Number(owner))

package/scripts/backlog/backlog-drive-restore.ts

@@ -1,4 +1,4 @@
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 const ISSUE_IN_EVENT = /#([1-9]\d*)\b/u
 const SETTLED_KINDS: ReadonlySet<string> = new Set([

package/scripts/backlog/backlog-drive-retrospective.ts

@@ -1,6 +1,6 @@
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { find_package_directory } from '#scripts/josh/josh-logic'
-import type { RunCarry } from '#scripts/run/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_retrospective } from '#scripts/run/run-retrospective'
 
 // Whether a drain owes the retrospective, read through the owed rule `run:step` reads, so a drain it

package/scripts/backlog/backlog-drive.ts

@@ -17,7 +17,7 @@
 // without a process, a network or a clock.
 
 import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
-import type { MergeResult } from '#scripts/run/run-merge-cli'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 
 const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'

package/scripts/backlog/backlog-next.ts

@@ -146,6 +146,19 @@ function report(result: EpicNextResult, context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
+// The settled set the views were classified against, so a standalone row and an epic child weigh the
+// same blocker the same way.
+function running_of(
+	views: ReadonlyArray<EpicView>,
+	graphs: ReadonlyArray<ReadonlyArray<EpicChild>>,
+	context: PoolContext,
+): ReadonlySet<string> {
+	return (
+		views[0]?.running ??
+		backlog_pool.running_set(graphs, context.opted_in.issues, context.repo, context.tracking.index)
+	)
+}
+
 // The two halves as one result. The epic half is already classified by `epic:next`; the standalone
 // half is classified here; the verdict is decided from the merge, so a backlog with a runnable epic
 // child and nothing else says `run` exactly as one with a runnable standalone issue does.
@@ -161,10 +174,7 @@ function combine(views: ReadonlyArray<EpicView>, context: PoolContext): EpicNext
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
 		exclude: context.exclude,
 		repo: context.repo,
-		// The settled set the views were classified against, so a standalone row and an epic child weigh
-		// the same blocker the same way.
-		running:
-			views[0]?.running ?? backlog_pool.running_set(graphs, context.opted_in.issues, context.repo),
+		running: running_of(views, graphs, context),
 	})
 
 	// The same checkout map `epic:next` hands `build_result`. Without it every bundle heading reads
@@ -194,6 +204,7 @@ function settled_views(
 		views[0]?.running ?? running,
 		context.opted_in.issues,
 		context.repo,
+		context.tracking.index,
 	)
 
 	return settled.size === running.size ? views : settled_views(reads, settled, context)
@@ -212,7 +223,7 @@ function views_from(reads: ReadonlyArray<EpicRead>, context: PoolContext): Reado
 
 	return settled_views(
 		reads,
-		backlog_pool.running_set(graphs, context.opted_in.issues, context.repo),
+		backlog_pool.running_set(graphs, context.opted_in.issues, context.repo, context.tracking.index),
 		context,
 	)
 }

package/scripts/backlog/backlog-offer-cli.ts

@@ -3,8 +3,8 @@ import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { rule_value_cache } from '#scripts/rules/rule-value-cache'
-import { run_event_stream } from '#scripts/run/run-event-stream'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { z } from 'zod'
 import { backlog_offer, type OfferAnswer } from './backlog-offer'
 
@@ -74,8 +74,8 @@ function to_count(raw: string | undefined): number | undefined {
 
 // A count flag that was given but unreadable makes the invocation unreadable rather than defaulted —
 // the contract `backlog:budget` follows for its own counts.
-function count_of(raw: string | undefined, fallback: number): number | undefined {
-	return raw === undefined ? fallback : to_count(raw)
+function count_of(raw: string | undefined): number | undefined {
+	return raw === undefined ? DEFAULT_COUNT : to_count(raw)
 }
 
 interface OfferCounts {
@@ -86,8 +86,8 @@ interface OfferCounts {
 // The two counts the mapping needs: `--running` decides `wait`, `--retries` decides `retry`. Either
 // given but unreadable refuses the whole invocation.
 function counts_of(values: ParsedValues): OfferCounts | undefined {
-	const running = count_of(cli_flags.string_of(values.running), DEFAULT_COUNT)
-	const retries = count_of(cli_flags.string_of(values.retries), DEFAULT_COUNT)
+	const running = count_of(cli_flags.string_of(values.running))
+	const retries = count_of(cli_flags.string_of(values.retries))
 
 	if (running === undefined || retries === undefined) return undefined
 

package/scripts/backlog/backlog-offer.ts

@@ -5,7 +5,7 @@ import { backlog_next } from './backlog-next'
 // answered — its stdout tokens and its exit code — into the one word `backlog:budget` is then asked
 // with, plus the issue numbers to start and the consecutive-retry count carried to the next ask.
 //
-// **The mapping is `docs/josh-commands-automation.md` → "`josh backlog:offer`", held here so it cannot
+// **The mapping is `docs/josh-commands-backlog.md` → "`josh backlog:offer`", held here so it cannot
 // drift.** It fixes which `backlog:next` answer becomes which `backlog:budget` word, and it carries two
 // context branches an agent once applied by hand every iteration: `wait` is `blocked` while this run
 // has children in flight and `exhausted` when it has none, and `retry` is `blocked` until the third

package/scripts/backlog/backlog-plan-cli.ts

@@ -4,8 +4,8 @@ import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
 import { epic_index } from '#scripts/epic/epic-index'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_named } from './backlog-named'
 import { backlog_next, type OptedIn } from './backlog-next'

package/scripts/backlog/backlog-pool.ts

@@ -5,7 +5,7 @@ import { epic_index } from '#scripts/epic/epic-index'
 import { epic_issue } from '#scripts/epic/epic-issue'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
 import {
 	ALREADY_DONE_LABEL,
@@ -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.
+// Child number to every open epic whose task list names it — `epic_index.build_tracking_index`.
+type TrackingIndex = ReadonlyMap<number, ReadonlyArray<number>>
+
 // The part of the context that decides which rows the standalone half considers at all.
 type ConsideredContext = Pick<StandaloneContext, 'tracked' | 'exclude' | 'repo'>
 
@@ -69,24 +72,64 @@ function needs_person(issue: OpenIssueData, context: StandaloneContext): boolean
 	)
 }
 
+// Each open epic's key, read off the tracking index — child number to the epics listing it.
+function epic_keys_of(tracking: TrackingIndex, repo: string): ReadonlySet<string> {
+	return new Set([...tracking.values()].flat().map((number) => epic_graph.key_of({ repo, number })))
+}
+
+// The set with every epic that tracks a member added, nested epics included (joshuafolkken/kit#3289).
+// An epic is a container rather than work, so it is never run itself — but it closes once its children
+// do, so a row blocked by it waits on time exactly when one of those children is in this run.
+function with_tracking_epics(
+	running: ReadonlySet<string>,
+	tracking: TrackingIndex,
+	repo: string,
+): ReadonlySet<string> {
+	const tracking_epics = [...tracking]
+		.filter(([child]) => running.has(epic_graph.key_of({ repo, number: child })))
+		.flatMap(([, epics]) => epics.map((number) => epic_graph.key_of({ repo, number })))
+	const grown = new Set([...running, ...tracking_epics])
+
+	return grown.size === running.size ? running : with_tracking_epics(grown, tracking, repo)
+}
+
+// The epics re-derived from the members alone, so an epic whose last running child was just taken out
+// leaves with it rather than lingering from an earlier pass.
+function rooted(
+	running: ReadonlySet<string>,
+	tracking: TrackingIndex,
+	repo: string,
+): ReadonlySet<string> {
+	const epics = epic_keys_of(tracking, repo)
+	const members = new Set([...running].filter((key) => !epics.has(key)))
+
+	return with_tracking_epics(members, tracking, repo)
+}
+
+function is_stuck(issue: OpenIssueData, running: ReadonlySet<string>, repo: string): boolean {
+	return has_any_label(issue.labels, DECISION_LABELS) || waits_outside(issue, running, repo)
+}
+
 // The running set with every standalone row a person has to resolve taken out, repeated until a pass
 // removes nothing — a row waiting on such a row waits on that person too, however long the chain.
 function settle_standalone(
 	running: ReadonlySet<string>,
 	issues: ReadonlyArray<OpenIssueData>,
 	repo: string,
+	tracking: TrackingIndex,
 ): ReadonlySet<string> {
 	const settled = new Set(running)
 
-	// An epic row is never in the set, so deleting its key changes nothing and it needs no filter.
+	// An epic row is never a standalone row, so deleting its key here never happens; `rooted` decides it.
 	for (const issue of issues) {
-		const is_stuck =
-			has_any_label(issue.labels, DECISION_LABELS) || waits_outside(issue, running, repo)
-
-		if (is_stuck) settled.delete(epic_graph.key_of({ repo, number: issue.number }))
+		if (is_stuck(issue, running, repo)) {
+			settled.delete(epic_graph.key_of({ repo, number: issue.number }))
+		}
 	}
 
-	return settled.size === running.size ? running : settle_standalone(settled, issues, repo)
+	const next = rooted(settled, tracking, repo)
+
+	return next.size === running.size ? next : settle_standalone(next, issues, repo, tracking)
 }
 
 // An opted-in row as the graph's node type. Both halves of the pool are then the same shape, so one
@@ -182,18 +225,21 @@ function classify_standalone(
 // (joshuafolkken/kit#1943). A child is opted in through its epic's `auto-ok` even where it carries none
 // of its own, which is why the set is built from the graphs that were read rather than from labels. A
 // standalone row a person has to resolve is left out, so a row waiting on it waits for that person too;
-// an epic child in the same state is taken out by `epic_next_views.settle_views`.
+// an epic child in the same state is taken out by `epic_next_views.settle_views`. An open epic with a
+// child in the set is in it too, so a row blocked by that epic waits rather than needs a person. A
+// closed child is left out: it runs nothing, and kept in the set it would hold its epic there.
 function running_set(
 	graphs: ReadonlyArray<ReadonlyArray<EpicChild>>,
 	issues: ReadonlyArray<OpenIssueData>,
 	repo: string,
+	tracking: TrackingIndex,
 ): ReadonlySet<string> {
 	const running = epic_outside_blocker.running_keys([
-		...graphs.flat(),
+		...graphs.flat().filter((child) => child.state === 'OPEN'),
 		...to_children(standalone_rows(issues), repo),
 	])
 
-	return settle_standalone(running, issues, repo)
+	return settle_standalone(rooted(running, tracking, repo), issues, repo, tracking)
 }
 
 // A cycle no single epic can see, because its links cross from one graph into another. Each epic's own
@@ -336,4 +382,4 @@ const backlog_pool = {
 }
 
 export { backlog_pool }
-export type { ConsideredContext, StandaloneContext }
+export type { ConsideredContext, StandaloneContext, TrackingIndex }

package/scripts/backlog/backlog-ready.ts

@@ -3,7 +3,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry } from '#scripts/lane/lane-registry'
-import type { RunCarry } from '#scripts/run/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_stalled } from './backlog-stalled'

package/scripts/backlog/backlog-scope.ts

@@ -1,5 +1,5 @@
 import type { EpicNextResult } from '#scripts/epic/epic-report'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 
 // Which open issues the backlog will not run, and why (joshuafolkken/kit#1652).

package/scripts/backlog/backlog-stalled-detect.ts

@@ -1,6 +1,6 @@
 import { telegram_notify } from '#scripts/notify/telegram-notify'
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
 import { backlog_stalled, type StallReading, type StallVerdict } from './backlog-stalled'
 

package/scripts/backlog/backlog-stalled.ts

@@ -1,5 +1,5 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 // When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks
 // (joshuafolkken/kit#2359). This is the mechanical judge of that state: three facts read, never

package/scripts/build/build-codex-hooks.ts

@@ -10,7 +10,9 @@ const CODEX_HOOKS = path.join(REPO_ROOT, '.codex', 'hooks.json')
 
 // Regenerate `.codex/hooks.json` from `.claude/settings.json` (joshuafolkken/kit#2997). The output is
 // committed rather than gitignored: Codex reads it straight from a fresh clone of kit, before any
-// build has run, and `josh init` / `josh sync` copy it to consumers from the package.
+// build has run, and `josh init` / `josh sync` copy it to consumers from the package. It is run by
+// hand, never from `pnpm build`, so a build never rewrites a committed file (joshuafolkken/kit#3324):
+// `codex-project-config.test.ts` fails the gate when the committed copy has drifted.
 function build_codex_hooks(): string {
 	writeFileSync(CODEX_HOOKS, codex_hooks.codex_hooks_text(readFileSync(CLAUDE_SETTINGS, 'utf8')))