@joshuafolkken/kit 1.957.0 → 1.972.0

package/scripts/epic/epic-next.ts

@@ -16,7 +16,7 @@ import { epic_lane_offer, type LaneOffer, type LaneRequest } from './epic-lane-o
 import { epic_next_read, type EpicRead, type SnapshotReads } from './epic-next-read'
 import { epic_next_views, type EpicView } from './epic-next-views'
 import { epic_outside_blocker } from './epic-outside-blocker'
-import { epic_report, type EpicNextResult, type EpicVerdict } from './epic-report'
+import { epic_report, type EpicNextResult } from './epic-report'
 
 // `josh epic:next <E…>` — which of the named epics' children can be started right now, bundled per
 // repository, and what the rest are waiting on (joshuafolkken/kit#860).
@@ -210,7 +210,7 @@ function refuse(reason: string): number {
 // The verdict as it applies to *this* repository. `run` never reaches a caller here: it means some
 // other repository has work, which for this session is something to wait on rather than a state its
 // loop has a branch for. The whole-run timeout is what bounds that wait.
-function repo_verdict(verdict: EpicVerdict): EpicVerdict {
+function repo_verdict(verdict: LaneOffer['verdict']): LaneOffer['verdict'] {
 	return verdict === 'run' ? 'wait' : verdict
 }
 

package/scripts/epic/epic-solo.ts

@@ -0,0 +1,147 @@
+import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import { epic_busy, type BusyRead } from './epic-busy'
+import type { EpicChild } from './epic-graph'
+import { epic_report, type EpicNextResult } from './epic-report'
+
+// The `run:solo` gate on what a run is offered (joshuafolkken/kit#2776).
+//
+// `wip-cap.md`'s run-alone section says an issue whose defect reaches the verification path runs
+// alone, and until this gate that was a judgement made at dispatch — the offer handed such an issue
+// out beside others and `backlog:drive` launched every number it was given. The label records the
+// judgement once; this applies it to every ask, so it holds without an agent in the loop.
+//
+// **Both offer paths call `select`**: `backlog:next` (the pool drain, through `gate`) and
+// `epic:next --lanes` (a named epic's children, `epic-lane-offer.ts`). One rule, so the two cannot
+// disagree about what may start beside what.
+//
+// Three rules, all against the repository's `in-progress` holders (`epic_busy.read_repository`):
+// a running `run:solo` issue lets nothing new start; a `run:solo` candidate starts only into an idle
+// repository and then alone; and nothing ranked below a waiting `run:solo` candidate is offered past
+// 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.
+
+const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
+
+// Which of the ordered candidates may start, which are held back, and why when a reason is worth
+// saying. `offered` keeps the candidates' own order.
+interface SoloSelection {
+	offered: ReadonlyArray<EpicChild>
+	withheld: ReadonlyArray<EpicChild>
+	notice?: string
+}
+
+interface SoloGate {
+	result: EpicNextResult
+	notice?: string
+}
+
+function is_solo(child: EpicChild): boolean {
+	return has_label_name(child.labels, RUN_SOLO_LABEL)
+}
+
+function solo_holder(read: BusyRead): number | undefined {
+	if (read.kind !== 'busy') return undefined
+
+	return read.issues.find((issue) => has_any_label(issue.labels, SOLO_LABELS))?.number
+}
+
+function held_message(holder: number, repo: string): string {
+	return issue_citation.linkify(
+		`#${String(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
+		repo,
+	)
+}
+
+function waiting_message(solo: number, repo: string): string {
+	return issue_citation.linkify(
+		`#${String(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
+		repo,
+	)
+}
+
+function first_of(children: ReadonlyArray<EpicChild>, keep: number): SoloSelection {
+	return { offered: children.slice(0, keep), withheld: children.slice(keep) }
+}
+
+function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelection {
+	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.
+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]
+
+	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)
+
+	return none_of(ordered, waiting_message(solo.number, repo))
+}
+
+// An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
+// ruled out.
+function select(children: ReadonlyArray<EpicChild>, read: BusyRead, repo: string): SoloSelection {
+	if (read.kind === 'unreadable' || read.kind === 'truncated') {
+		return none_of(children, epic_busy.busy_reason(read, repo, 0))
+	}
+
+	const holder = solo_holder(read)
+
+	if (holder !== undefined) return none_of(children, held_message(holder, repo))
+
+	return select_candidates(children, read, repo)
+}
+
+// The offered candidates of `repo` stay; the withheld ones move to `waiting`, which is where the
+// report already lists children that time alone will release.
+function withhold(result: EpicNextResult, repo: string, selection: SoloSelection): EpicNextResult {
+	return {
+		...result,
+		candidates: result.candidates.map((bundle) =>
+			bundle.repo === repo ? { ...bundle, children: selection.offered } : bundle,
+		),
+		waiting: [...result.waiting, ...selection.withheld],
+	}
+}
+
+// Only a `run` answer offers anything, so every other verdict passes through untouched.
+function gate(result: EpicNextResult, read: BusyRead, repo: string): SoloGate {
+	if (result.verdict !== 'run') return { result }
+
+	const selection = select(epic_report.candidates_for_repo(result, repo), read, repo)
+	const gated = withhold(result, repo, selection)
+
+	return selection.notice === undefined
+		? { result: gated }
+		: { result: gated, notice: selection.notice }
+}
+
+const epic_solo = { gate, is_solo, prefer, select }
+
+export type { SoloGate, SoloSelection }
+export { epic_solo }

package/scripts/epic/epic-triage.ts

@@ -0,0 +1,47 @@
+import { has_label_name, RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import type { EpicChild } from './epic-graph'
+
+// The triage gate on what a run is offered (joshuafolkken/kit#2779).
+//
+// `run:solo` (joshuafolkken/kit#2776) records that an issue runs alone, but its absence said nothing:
+// "judged safe beside others" and "never judged" looked the same, and an issue opted in mid-run reached
+// `backlog:drive` without any agent reading it. `run:lane` records the other answer, so an issue with
+// neither label is one nobody has judged — and such an issue may be one that must run alone.
+//
+// **One untriaged candidate withholds every candidate**, not just itself: whether the others may start
+// depends on whether it is `run:solo`, which is exactly what is not known yet. The answer is the
+// `triage` verdict, which `backlog:drive` hands back to the parent rather than acting on.
+//
+// **Both offer paths call `untriaged`**: `backlog:next` (the pool drain) and `epic:next --lanes`
+// (a named epic's children, `epic-lane-offer.ts`) — the same pairing `epic_solo` keeps.
+
+type TriageVerdict = 'triage'
+
+const TRIAGE_VERDICT: TriageVerdict = 'triage'
+
+function is_triaged(child: EpicChild): boolean {
+	const { labels } = child
+
+	return has_label_name(labels, RUN_SOLO_LABEL) || has_label_name(labels, RUN_LANE_LABEL)
+}
+
+// The candidates nobody has judged, in the order they were given.
+function untriaged(children: ReadonlyArray<EpicChild>): ReadonlyArray<EpicChild> {
+	return children.filter((child) => !is_triaged(child))
+}
+
+// Names every untriaged number, so the parent reading standard error knows which issues to judge.
+function message(children: ReadonlyArray<EpicChild>, repo: string): string {
+	const numbers = children.map((child) => `#${String(child.number)}`).join(', ')
+
+	return issue_citation.linkify(
+		`Untriaged: ${numbers} carry neither \`${RUN_SOLO_LABEL}\` nor \`${RUN_LANE_LABEL}\` in ${repo}, so nothing is offered until each is judged. Read each one, record its blocked-by order and one of the two labels with a comment saying why, then ask again.`,
+		repo,
+	)
+}
+
+const epic_triage = { TRIAGE_VERDICT, is_triaged, message, untriaged }
+
+export type { TriageVerdict }
+export { epic_triage }

package/scripts/gate/hook-gate-reuse.ts

@@ -53,14 +53,13 @@ function is_force_requested(force_environment: string): boolean {
 // nothing" for "git could not be asked". Every predicate below treats the two differently.
 //
 // **The observation ledger is dropped from the reading, and it is the one line that may be**
-// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes the ledger from
-// what it stages, so a parent's appended line sits modified-but-never-staged for the whole interval
-// between the append and the next `pnpm josh observations:flush` — and every condition below reads a
-// non-empty status as "this operation carries a tree no check has read". Left in, one ledger line
-// would send every commit and every push in the primary checkout back to the full gate for days,
-// which is the reuse this module exists to grant. **Dropping it is sound because nothing can carry
-// it**: the exclusion means the index and the push are byte-for-byte the recorded tree whatever the
-// ledger says, and the ledger's own content is checked by the CI of the pull request the flush opens.
+// (joshuafolkken/kit#1756). Lines are appended throughout a run — a review's record lands after its
+// gate — and every condition below reads a non-empty status as "this operation carries a tree no
+// check has read". Left in, one ledger line would send every commit and every push in the primary
+// checkout back to the full gate, which is the reuse this module exists to grant. **Dropping it is
+// sound because the ledger is no code any check runs**: `pnpm josh git` stages it with the run's
+// commit only after its grammar has been parsed (joshuafolkken/kit#2763), and the rest of its content
+// is checked by the CI of the pull request that carries it.
 async function read_status_lines(): Promise<ReadonlyArray<string> | undefined> {
 	try {
 		const status = await git_command.status()

package/scripts/git/git-closes-keyword.ts

@@ -0,0 +1,15 @@
+// Captures the number, so the one pattern answers every question asked of a PR body: whether the
+// linked issue will auto-close, which issue that is when the invocation did not say
+// (joshuafolkken/kit#1539), and whether a merged pull request closes a child a `backlogrun` judged
+// unfinished (joshuafolkken/kit#2769). A second pattern would be two readings of "closes #N" to disagree.
+const CLOSES_PATTERN = /closes\s+#(\d+)/iu
+
+function parse_closes_issue_number(body: string | undefined): string | undefined {
+	if (body === undefined) return undefined
+
+	return CLOSES_PATTERN.exec(body)?.[1]
+}
+
+const git_closes_keyword = { parse_closes_issue_number }
+
+export { git_closes_keyword }

package/scripts/git/git-followup-flush.ts

@@ -5,12 +5,11 @@ import { git_command } from './git-command'
 import { git_followup_cleanup } from './git-followup-cleanup'
 import { main_sync } from './main-sync'
 
-// The observation ledger's only commit path is `pnpm josh observations:flush`, and until now no
-// command's procedure called it (joshuafolkken/kit#1810). The ledger is excluded from ordinary
-// staging (joshuafolkken/kit#1756), so an appended line stayed in the working tree until a person
-// remembered to flush it — the same "a run that had to remember is the run that forgets" defect the
-// staging side was built to avoid, left standing on the commit side. This wires the flush into
-// `pnpm josh followup`, the one step that knows the merge has landed.
+// The residual commit path for the observation ledger (joshuafolkken/kit#1810). A run's appended lines
+// ride its own commit (joshuafolkken/kit#2763), so after the merge the ledger is usually clean and this
+// short-circuits; what it still catches is a line appended after the commit — a second review round's
+// record — which would otherwise stay in the working tree until a person remembered to flush it. This
+// wires the flush into `pnpm josh followup`, the one step that knows the merge has landed.
 //
 // **It runs before the working-tree hold is released** (`scripts-ai/git-followup-finish.ts`, whose
 // `finish()` runs after `git_pr_followup.run()` returns), because a flush switches branches, and a

package/scripts/git/git-followup-issue-close.ts

@@ -0,0 +1,75 @@
+import { poll, type PollOptions } from '#scripts/lib/poll'
+import { z } from 'zod'
+import { git_epic_parse } from './git-epic-parse'
+import { git_gh_command } from './git-gh-command'
+import { parse_json_object_safe } from './parse-json-array'
+
+// **A merged pull request whose `closes #N` GitHub did not apply** (joshuafolkken/kit#2770). From
+// 2026-09-30 06:34Z every merge `followup` made left its issue open — seven in a row, where every
+// earlier one was closed by the pull request within a second — although the merge request, the
+// merging account and the `closes #N` first line were all the same as before. The run then reported
+// success, and a `backlogrun` read the still-open child as a failure and stopped.
+//
+// **The issue's state is what is checked, not `closingIssuesReferences`.** That field is GraphQL-only
+// (a cloud session is answered 403 there, joshuafolkken/kit#1022) and it is not the fact that failed:
+// PR #2768 answered it empty at the time and names #2761 now, while #2761 was never closed by it. The
+// observable defect is an issue left open, so that is what is read, and what is repaired.
+//
+// **A short wait first**, because GitHub applies the keyword asynchronously — the closes it did apply
+// landed within a second of the merge. Closing on the first read would take the close away from the
+// pull request on every run that merely raced it.
+const CLOSE_WAIT: PollOptions = { attempts: 3, interval_ms: 2000 }
+
+const CLOSE_RECOVERY = 'gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f state=closed'
+
+const state_read_schema = z.object({ state: z.string().optional() })
+
+async function is_issue_closed(issue_number: string): Promise<boolean> {
+	const raw = await git_gh_command.issue_get_state_and_relations(issue_number)
+	const parsed = raw === undefined ? undefined : parse_json_object_safe(raw, state_read_schema)
+
+	return git_epic_parse.is_state_closed(parsed?.state)
+}
+
+const FOLLOWUP_CLOSER = 'pnpm josh followup'
+
+// English, like every other string a script posts: the comment says why the close came from this
+// command rather than from the pull request, so a reader of the issue is not left guessing. `closer`
+// names the command that closed it — `followup` at the merge, or `run:merge` when a `backlogrun`
+// finds the child still open afterwards (joshuafolkken/kit#2769).
+function build_close_comment(pr_url: string | undefined, closer: string = FOLLOWUP_CLOSER): string {
+	return (
+		`Closed by \`${closer}\`: ${pr_url ?? 'the merged pull request'} merged, ` +
+		'but GitHub did not apply its ' +
+		'`closes #N` keyword (joshuafolkken/kit#2770).'
+	)
+}
+
+// **Throws when the issue is still open**, so the guard around it reports the failure with the
+// command that finishes it by hand — an issue left open after a merge is the one thing this step
+// exists to stop going unnoticed.
+async function ensure_issue_closed(
+	input: { issue_number: string | undefined; pr_url: string | undefined; closer?: string },
+	wait: PollOptions = CLOSE_WAIT,
+): Promise<void> {
+	const { issue_number } = input
+	const is_done =
+		issue_number === undefined ||
+		(await poll.poll_until(async () => await is_issue_closed(issue_number), wait))
+	if (is_done) return
+
+	console.warn(`⚠️  Issue #${issue_number} is still open after the merge — closing it.`)
+	const comment = build_close_comment(input.pr_url, input.closer)
+
+	if (!(await git_gh_command.issue_close(issue_number, comment))) {
+		throw new Error(`gh api could not close issue #${issue_number}`)
+	}
+}
+
+const git_followup_issue_close = {
+	ensure_issue_closed,
+	build_close_comment,
+	CLOSE_RECOVERY,
+}
+
+export { git_followup_issue_close }

package/scripts/git/git-pr-followup-wrapup.ts

@@ -1,6 +1,7 @@
 import { git_epic_close } from './git-epic-close'
 import { git_followup_cleanup } from './git-followup-cleanup'
 import { git_followup_flush } from './git-followup-flush'
+import { git_followup_issue_close } from './git-followup-issue-close'
 import { git_followup_label } from './git-followup-label'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
 import { git_gh_command } from './git-gh-command'
@@ -25,6 +26,9 @@ const IN_PROGRESS_RECOVERY = 'gh api -X DELETE repos/{owner}/{repo}/issues/<N>/l
 interface WrapupInput {
 	branch_name: string
 	issue_number: string | undefined
+	// The number the pull request body's `closes #N` names — the only issue the merge claimed to
+	// close, so the only one the merged-issue close may write to (joshuafolkken/kit#2770).
+	closes_number: string | undefined
 	notify_config: GitNotifyConfig | undefined
 	pr_url: string | undefined
 	should_merge: boolean
@@ -164,9 +168,30 @@ async function in_progress_step(input: WrapupInput): Promise<void> {
 	})
 }
 
+// **The merged issue's close, confirmed rather than assumed** (joshuafolkken/kit#2770): GitHub stopped
+// applying `closes #N` on some merges, and nothing noticed. The epic auto-close does not wait on it —
+// it already excludes the merged issue from its reads — so it runs beside the other steps. It acts on
+// the body's `closes #N` rather than the run's issue number: a pull request that closes nothing, or
+// another issue, never closes the one the invocation named.
+async function issue_close_step(input: WrapupInput): Promise<void> {
+	if (!input.should_merge) return
+
+	await git_followup_cleanup.run_guarded_step(input.should_merge, {
+		label: 'The merged issue close',
+		recovery: git_followup_issue_close.CLOSE_RECOVERY,
+		run: async () => {
+			await git_followup_issue_close.ensure_issue_closed({
+				issue_number: input.closes_number,
+				pr_url: input.pr_url,
+			})
+		},
+	})
+}
+
 // **The steps after the merge are issued together** (joshuafolkken/kit#1446). The completion
-// comment writes to the issue or the pull request, the auto-close reads the open epics, and the
-// label removal reads and writes the issue's labels; none needs another's answer, and measured
+// comment writes to the issue or the pull request, the auto-close reads the open epics, the label
+// removal reads and writes the issue's labels, and the merged-issue close reads and may close the
+// issue; none needs another's answer, and measured
 // serially the first two were 1.9 s and 3.1 s of `followup`'s own clock. Past the merge none can
 // reject another — `run_guarded_step` reports the failure and answers instead — so they settle
 // independently and the stage costs the longest of them rather than their sum.
@@ -178,9 +203,9 @@ async function in_progress_step(input: WrapupInput): Promise<void> {
 // (`git-followup-cleanup.ts`), which is easier to read as one sequence than as a settled set.
 //
 // **What the overlap costs, stated rather than glossed**: mutating requests now go out at once
-// against one repository — a comment write, an auto-close that comments on and closes epics, and a
-// label delete — which is what GitHub's secondary rate limit guidance is about. Past the merge all
-// of them are guarded, so the worst case is a cleanup reported as unfinished rather than a failed
+// against one repository — a comment write, an auto-close that comments on and closes epics, a label
+// delete, and the merged issue's close when GitHub did not apply it — which is what GitHub's
+// secondary rate limit guidance is about. Past the merge all of them are guarded, so the worst case is a cleanup reported as unfinished rather than a failed
 // run, and this is a handful of requests rather than a fan-out. **Their console output can
 // interleave too**: the guard's warning and its recovery line are printed as they happen, so an
 // auto-close progress line can land between them. The recovery line names its own command and stands
@@ -194,7 +219,12 @@ async function run_tail_steps(input: WrapupInput): Promise<void> {
 		return
 	}
 
-	await Promise.all([notify_step(input), epic_close_step(input), in_progress_step(input)])
+	await Promise.all([
+		notify_step(input),
+		epic_close_step(input),
+		in_progress_step(input),
+		issue_close_step(input),
+	])
 }
 
 async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {

package/scripts/git/git-pr-followup.ts

@@ -1,3 +1,4 @@
+import { git_closes_keyword } from './git-closes-keyword'
 import { git_followup_pending } from './git-followup-pending'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
 import { git_gh_command } from './git-gh-command'
@@ -15,10 +16,6 @@ import { telegram_notify, type TelegramSendInput, type TelegramTaskType } from '
 
 const { STAGE, lap } = git_followup_stages
 
-// Captures the number, so the one pattern answers both questions the run asks of a PR body: whether
-// the linked issue will auto-close, and — since joshuafolkken/kit#1539 — which issue that is when the
-// invocation did not say. A second pattern here would be two readings of "closes #N" to disagree.
-const CLOSES_PATTERN = /closes\s+#(\d+)/iu
 // Named so a test can pin the note without restating it (joshuafolkken/kit#999).
 const WATCH_FAILED_NOTE = 'pr checks --watch failed; falling through to polling'
 const REPO_NAME_SEPARATOR = '/'
@@ -69,11 +66,7 @@ interface FollowupInput {
 	should_merge: boolean
 }
 
-function parse_closes_issue_number(body: string | undefined): string | undefined {
-	if (body === undefined) return undefined
-
-	return CLOSES_PATTERN.exec(body)?.[1]
-}
+const { parse_closes_issue_number } = git_closes_keyword
 
 function has_closes_keyword(body: string | undefined): boolean {
 	return parse_closes_issue_number(body) !== undefined
@@ -234,6 +227,7 @@ async function read_issue_title(
 
 interface RunContext {
 	issue_number: string | undefined
+	closes_number: string | undefined
 	context: TelegramContext
 }
 
@@ -256,19 +250,17 @@ async function read_run_context(input: {
 	issue_number: string | undefined
 }): Promise<RunContext> {
 	const closes = warn_if_missing_closes(input.branch_name)
-	const owner = git_gh_command.repo_get_name_with_owner()
-	const url = git_gh_command.pr_get_url(input.branch_name)
-	const title = read_issue_title(input.issue_number, closes)
 	const [closes_number, name_with_owner, pr_url, issue_title] = await Promise.all([
 		closes,
-		owner,
-		url,
-		title,
+		git_gh_command.repo_get_name_with_owner(),
+		git_gh_command.pr_get_url(input.branch_name),
+		read_issue_title(input.issue_number, closes),
 	])
 	const issue_number = input.issue_number ?? closes_number
 
 	return {
 		issue_number,
+		closes_number,
 		context: {
 			repo_name: parse_repo_name(name_with_owner),
 			issue_title,
@@ -373,7 +365,7 @@ async function run_review_checks(
 // the epic close all name the same issue — and so the caller's own tail can record a run whose number
 // only the pull request knew.
 async function run_stages(input: FollowupInput, log: StageLog): Promise<string | undefined> {
-	const { issue_number, context } = await read_run_context(input)
+	const { issue_number, closes_number, context } = await read_run_context(input)
 
 	lap(log, STAGE.closes_and_context)
 	const checks = await run_review_checks(input, context, log)
@@ -385,6 +377,7 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 		{
 			branch_name: input.branch_name,
 			issue_number,
+			closes_number,
 			notify_config: input.notify_config,
 			pr_url: context.pr_url,
 			should_merge: input.should_merge,

package/scripts/git/git-staging.ts

@@ -2,6 +2,7 @@ import {
 	observation_ledger,
 	OBSERVATION_LEDGER_PATHS,
 } from '#scripts/observations/observation-ledger'
+import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { git_command } from './git-command'
 import { git_prompt } from './git-prompt'
 import { git_status } from './git-status'
@@ -67,18 +68,26 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 	for (const file of files) console.info(`   + ${file}`)
 }
 
-// **The observation ledger is never staged by an ordinary commit** (joshuafolkken/kit#1756). A
-// parent session appends to it in the primary checkout and nothing there commits it, so the next
-// `pnpm josh git` run in that checkout swept the line into a pull request about something else
-// entirely — a diff a reviewer has no reason to question. Excluding it here covers every entry
-// point, because this is the one staging step all of them go through;
-// `pnpm josh observations:flush` is what commits it, on a branch of its own.
-// Both of its paths are excluded (joshuafolkken/kit#2724): a run on the old code still appends at
-// the old one until `observation-ledger-migrate.ts` moves it.
-const PATHS_EXCLUDED_FROM_STAGING: ReadonlyArray<string> = OBSERVATION_LEDGER_PATHS
-
-function is_stageable(file_path: string): boolean {
-	return !observation_ledger.is_ledger_path(file_path)
+// **The observation ledger rides the run's own commit** (joshuafolkken/kit#2763). It used to be
+// excluded here (joshuafolkken/kit#1756) and committed afterwards by `pnpm josh observations:flush` as
+// a pull request of its own — a second branch, CI wait and merge behind every run that appended a
+// line, 144 of them in one month. Staged with the run instead, the lines are reviewed and merged with
+// the pull request whose run recorded them, while CI for that pull request is the only wait.
+//
+// **A line that breaks the grammar keeps the old exclusion** (joshuafolkken/kit#2123): the commit
+// goes ahead without the ledger, and `pnpm josh observations:flush` — which refuses the same line and
+// names it — is where it is repaired. The migration is run first, as the flush runs it, so a line
+// still on the old path (joshuafolkken/kit#2724) is committed at the new one. A lane has no ledger
+// line of its own to carry: its writers append to the primary checkout's.
+async function ledger_exclusions(): Promise<ReadonlyArray<string>> {
+	const broken = await observation_ledger_prepare.prepare(await git_command.repository_root())
+
+	return broken.length > 0 ? OBSERVATION_LEDGER_PATHS : []
+}
+
+// A migration claim is a copy mid-move, never the ledger itself, so it is never staged.
+function is_stageable(file_path: string, excluded: ReadonlyArray<string>): boolean {
+	return !observation_ledger.is_migration_claim(file_path) && !excluded.includes(file_path)
 }
 
 // **Said out loud, because the alternative is an unexplained failure.** With the ledger the only
@@ -89,27 +98,31 @@ function is_stageable(file_path: string): boolean {
 // **The paths are parsed rather than matched as substrings**: `docs/maintainers/observations.md.bak` contains the
 // ledger's path, and a hint naming a file the exclusion never touched is a hint that teaches the
 // reader to ignore it.
-function report_excluded_paths(status_output: string): void {
-	const excluded = status_output
+function report_excluded_paths(status_output: string, excluded: ReadonlyArray<string>): void {
+	const left_out = status_output
 		.split('\n')
 		.filter((line) => line.trim().length > 0)
 		.map((line) => observation_ledger.status_path(line))
-		.filter((file_path) => !is_stageable(file_path))
+		.filter((file_path) => excluded.includes(file_path))
 
-	for (const file_path of excluded) {
-		console.info(`💡 ${file_path} is not staged; commit it with \`pnpm josh observations:flush\`.`)
+	for (const file_path of left_out) {
+		console.info(
+			`💡 ${file_path} is not staged: a ledger line breaks the grammar; \`pnpm josh observations:flush\` names it.`,
+		)
 	}
 }
 
+// The status is read after the migration, so an old-path ledger it moved is not staged by its old name.
 async function stage_tracked_files(): Promise<void> {
+	const excluded = await ledger_exclusions()
 	const status_output = await git_command.status()
 	const untracked = git_status
 		.list_untracked_files(status_output)
-		.filter((file_path) => is_stageable(file_path))
+		.filter((file_path) => is_stageable(file_path, excluded))
 
-	await git_command.add_tracked(PATHS_EXCLUDED_FROM_STAGING)
+	await git_command.add_tracked(excluded)
 	console.info('💡 Auto-staged tracked modified files (git add -u).')
-	report_excluded_paths(status_output)
+	report_excluded_paths(status_output, excluded)
 	await stage_untracked_files(untracked)
 }
 

package/scripts/git/issue-labels.ts

@@ -10,6 +10,15 @@ const IN_PROGRESS_LABEL = 'in-progress'
 // it: a parked child is why a run reports "nothing left that time will fix" rather than waiting
 // forever (joshuafolkken/kit#860).
 const NEEDS_DECISION_LABEL = 'needs-decision'
+// Marks an issue whose defect reaches the verification path, so it runs with nothing beside it
+// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `wip-cap.md`;
+// `backlog:next` enforces it (`backlog-solo.ts`), so the rule no longer rests on a judgement at
+// dispatch time.
+const RUN_SOLO_LABEL = 'run:solo'
+// The other half of the same judgement: an issue a run read and found safe to run beside others
+// (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'
 // 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
@@ -191,6 +200,16 @@ const WORKFLOW_LABELS: ReadonlyArray<{
 		description: 'Tracks a batch of child issues from one split',
 	},
 	{ name: IN_PROGRESS_LABEL, color: '0075ca', description: 'Work is actively in progress' },
+	{
+		name: RUN_SOLO_LABEL,
+		color: 'b60205',
+		description: 'Runs alone in a backlogrun: nothing starts beside it',
+	},
+	{
+		name: RUN_LANE_LABEL,
+		color: '0e8a16',
+		description: 'Judged safe to run beside others in a backlogrun',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -269,6 +288,8 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
+	RUN_LANE_LABEL,
+	RUN_SOLO_LABEL,
 	SPLIT_ROUTE_LABEL,
 	TIER_A_ROUTE_LABEL,
 	DEPTH_0_LABEL,
@@ -301,6 +322,8 @@ export {
 	NOT_DIRECTLY_RUNNABLE_LABELS,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
+	RUN_LANE_LABEL,
+	RUN_SOLO_LABEL,
 	SPLIT_ROUTE_LABEL,
 	TIER_A_ROUTE_LABEL,
 	WORKFLOW_LABELS,