@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/backlog/backlog-idle.ts

@@ -0,0 +1,88 @@
+import { backlog_budget, type BudgetInput } from './backlog-budget'
+
+// The idle watch as a window a person can read: when the run began waiting on
+// an empty backlog, when the wait ends, and which bound ends it. Without it the moment the wait began
+// would live only in `backlog:drive`'s memory as `--active`, so a reader of the event stream could
+// tell the run was waiting but not until when. The budget names the
+// window, `backlog:offer` records it as an `idle` event, and `run:board` reads it back — all through the
+// text written and parsed here, so the three never spell it differently.
+
+type IdleBound = 'idle' | 'whole-run'
+
+interface IdleWindow {
+	since_ms: number
+	until_ms: number
+	// Which bound ends the wait: the idle budget running out, or the whole-run bound arriving first.
+	bound: IdleBound
+	// When the watching loop last asked the backlog — the poll the next one is counted from.
+	asked_ms: number
+}
+
+const TEXT_PATTERN =
+	/^idle since (?<since>\S+) until (?<until>\S+) \((?<bound>idle|whole-run)\) asked (?<asked>\S+)$/u
+const IDLE_BOUND: IdleBound = 'idle'
+const WHOLE_RUN_BOUND: IdleBound = 'whole-run'
+
+// The window an idle watch opened at `active_at_ms` runs for, as asked at `now_ms`, or `undefined` when
+// the watch is off. The wait ends at the earlier of the idle budget and the whole-run bound — the order
+// `decide` applies.
+function window_of(input: BudgetInput): IdleWindow | undefined {
+	if (input.idle_budget_ms === undefined) return undefined
+
+	const idle_until = input.active_at_ms + input.idle_budget_ms
+	const run_until = input.started_at_ms + backlog_budget.WHOLE_RUN_BUDGET_MS
+	const bound = run_until < idle_until ? WHOLE_RUN_BOUND : IDLE_BOUND
+
+	return {
+		since_ms: input.active_at_ms,
+		until_ms: Math.min(idle_until, run_until),
+		bound,
+		asked_ms: input.now_ms,
+	}
+}
+
+function iso_of(ms: number): string {
+	return new Date(ms).toISOString()
+}
+
+function text_of(window: IdleWindow): string {
+	const { since_ms, until_ms, bound, asked_ms } = window
+
+	return `idle since ${iso_of(since_ms)} until ${iso_of(until_ms)} (${bound}) asked ${iso_of(asked_ms)}`
+}
+
+function is_bound(value: string | undefined): value is IdleBound {
+	return value === IDLE_BOUND || value === WHOLE_RUN_BOUND
+}
+
+// A malformed stamp reads as no window rather than as `NaN`, so a mangled line is never drawn.
+function window_from(groups: Record<string, string>, bound: IdleBound): IdleWindow | undefined {
+	const since_ms = Date.parse(String(groups['since']))
+	const until_ms = Date.parse(String(groups['until']))
+	const asked_ms = Date.parse(String(groups['asked']))
+
+	return Number.isNaN(since_ms + until_ms + asked_ms)
+		? undefined
+		: { since_ms, until_ms, bound, asked_ms }
+}
+
+function parse(text: string): IdleWindow | undefined {
+	const groups = TEXT_PATTERN.exec(text)?.groups
+
+	if (groups === undefined || !is_bound(groups['bound'])) return undefined
+
+	return window_from(groups, groups['bound'])
+}
+
+// The next time the watching loop asks the backlog again: one `IDLE_POLL_MINUTES` after the ask the
+// stream recorded, never past the end of the wait — the interval `idle_watch_reason` tells the loop.
+function next_check_ms(window: IdleWindow): number {
+	const poll_ms = backlog_budget.IDLE_POLL_MINUTES * backlog_budget.MS_PER_MINUTE
+
+	return Math.min(window.asked_ms + poll_ms, window.until_ms)
+}
+
+const backlog_idle = { next_check_ms, parse, text_of, window_of }
+
+export { backlog_idle }
+export type { IdleBound, IdleWindow }

package/scripts/backlog/backlog-named.ts

@@ -1,18 +1,16 @@
-// The named-issue prefix of a `backlogrun` invocation (joshuafolkken/kit#1984). `backlogrun #N1 #N2 …`
+// The named-issue prefix of a `backlogrun` invocation. `backlogrun #N1 #N2 …`
 // runs the issues typed after the keyword in the order they were typed, one at a time, and only once
 // they are all done does the opted-in backlog drain. This module is the single source of that order
 // and of what a failure partway through it does, so the plan a person reads (`backlog:plan`) and the
 // loop that runs it (`backlogrun.md`) cannot disagree.
 //
-// **It replaces the old `queue` keyword.** `queue #N1 #N2 …` was a separate entry point for exactly
-// this sequential run; folding it in means one command carries both the named prefix and the backlog
-// that follows it, under one authorization and one carried budget.
+// **One command carries both the named prefix and the backlog that follows it**, under one
+// authorization and one carried budget, rather than a separate entry point for the sequential run.
 //
-// **A named item is a single issue or an epic** (joshuafolkken/kit#1985, folding in the old `epicrun`
-// keyword). A single-issue item is one `fullrun`; an epic item runs every child in dependency order,
-// across the free lanes, and is done only once every child has been processed — merged or parked. The
-// run does not advance to the next named item until the epic item is complete, which is `epicrun`'s
-// whole-epic execution at the granularity of one named item.
+// **A named item is a single issue or an epic.** A single-issue item is one `fullrun`; an epic item
+// runs every child in dependency order, across the free lanes, and is done only once every child has
+// been processed — merged or parked. The run does not advance to the next named item until the epic
+// item is complete, so a whole epic executes at the granularity of one named item.
 
 const NAMED_KIND = 'named'
 const BACKLOG_KIND = 'backlog'
@@ -51,12 +49,11 @@ type PlanStep = NamedStep | BacklogStep
 // A named issue that could not finish parks like any other child; what is specific to a sequential run
 // is that the issues declared *after* it are not started — the order was the point of naming them. What
 // follows is the pool by default, or nothing under `--only`, so the run then drains the opted-in
-// backlog or ends (joshuafolkken/kit#1984).
+// backlog or ends.
 //
 // **This skip only applies to a single-issue item.** An epic item does not park as a unit — its
 // children park individually and the epic item completes anyway (`epic_item_outcome`), so a parked
-// epic child, which is never in the named list, skips nothing and the run advances to the next item
-// (joshuafolkken/kit#1985).
+// epic child, which is never in the named list, skips nothing and the run advances to the next item.
 interface FailureOutcome {
 	parked: number
 	skipped: ReadonlyArray<number>
@@ -65,8 +62,7 @@ interface FailureOutcome {
 
 // The completion of one epic named item. It runs every child and finishes once each has been
 // processed; the children that parked are carried here so the completion report can list them, and the
-// item is complete regardless — a parked child never holds up the next named item
-// (joshuafolkken/kit#1985).
+// item is complete regardless — a parked child never holds up the next named item.
 interface EpicItemOutcome {
 	epic: number
 	parked: ReadonlyArray<number>
@@ -130,7 +126,7 @@ function after_failure(
 // An epic named item is complete once every child has been processed — merged or parked. The parked
 // children are carried out so the completion report can list them, and the item is complete either
 // way: a parked epic child does not hold up the next named item, which is `epicrun`'s park-and-continue
-// at the granularity of one named epic item (joshuafolkken/kit#1985).
+// at the granularity of one named epic item.
 function epic_item_outcome(
 	epic: number,
 	children: ReadonlyArray<EpicChildOutcome>,

package/scripts/backlog/backlog-next.ts

@@ -15,18 +15,17 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
+import { backlog_overlap } from './backlog-overlap'
 import { backlog_pool } from './backlog-pool'
 import { backlog_rank, type GateScope } from './backlog-rank'
-import { backlog_restructure } from './backlog-restructure'
 
-// `josh backlog:next` — what the whole opted-in backlog may run next (joshuafolkken/kit#1630).
+// `josh backlog:next` — what the whole opted-in backlog may run next.
 //
-// The answer used to be split in two, and neither half could give it. `epic:next` has the dependency
-// graph and the execution wave, but its input is **one epic's task list**. `auto-ok:next` sees the
-// whole backlog, but it orders by the display's newest-first ranking and reads no dependency at all.
-// So there was no route that asked the backlog itself what may start.
+// Neither half alone can give the answer. `epic:next` has the dependency graph and the execution
+// wave, but its input is **one epic's task list**. `auto-ok:next` sees the whole backlog, but it
+// orders by the display's newest-first ranking and reads no dependency at all.
 //
-// This command is that route, and it is glue rather than a third implementation: the epic half runs
+// This command is the route that asks the backlog itself what may start, and it is glue rather than a third implementation: the epic half runs
 // through `epic:next`'s own read → classify → report pipeline unchanged, the standalone half through
 // `auto-ok:next`'s own listing and runnability rules, and the verdict comes from
 // `epic_report.decide_verdict` so it cannot drift from what `epic:next` means by the same word.
@@ -48,7 +47,7 @@ const READ_FAILURES: Readonly<Record<Exclude<OptedInRead['kind'], 'read'>, strin
 	unreadable: auto_ok_cli.UNREADABLE_MESSAGE,
 }
 
-// What `retry` says that `error` cannot (joshuafolkken/kit#1663).
+// What `retry` says that `error` cannot.
 //
 // The anomaly `epic:next` raises for a child it could not read tells the reader to check
 // `gh auth status` and that the issue exists — correct for the failure it was written for, and
@@ -68,7 +67,7 @@ const RETRY_MESSAGE =
 // member none of them can produce — and `VERDICT_LINES` a line nothing ever prints. The token is a
 // backlog-level answer about the transport, not a reading of one epic's graph.
 //
-// `triage` is `epic:next`'s word as well as this command's (joshuafolkken/kit#2779), but it is decided
+// `triage` is `epic:next`'s word as well as this command's, but it is decided
 // after the graph is read rather than from it, so it stays `epic_triage`'s type too.
 type BacklogVerdict = EpicVerdict | 'retry' | TriageVerdict
 
@@ -100,7 +99,7 @@ interface PoolContext {
 //
 // **The tokens are scoped to this repository, which is `epic:next --repo`'s shape exactly.** An epic
 // may track a child elsewhere, and a bare number would send the loop reading this to *this*
-// repository's issue of that number — a different issue (joshuafolkken/kit#1016). Qualifying it
+// repository's issue of that number — a different issue. Qualifying it
 // instead was tried and is worse: `--exclude` parses bare integers, so a loop feeding a qualified
 // token back would be answered with a usage error rather than an exclusion. So a child elsewhere
 // stays out of the tokens, and `run` becomes `wait` when this repository has none — the same mapping
@@ -134,7 +133,7 @@ function warn_gaps(context: PoolContext, has_answer: boolean): void {
 function report(result: EpicNextResult, context: PoolContext): number {
 	warn_gaps(context, result.verdict === 'run')
 	// The explanation names epics and children as `#N` (`tracked by epic #N`); linkified so the text a
-	// run reads carries clickable references rather than bare ones (joshuafolkken/kit#2329). The stdout
+	// run reads carries clickable references rather than bare ones. The stdout
 	// tokens below are bare numbers by contract — a loop feeds them back to `--exclude` — so they are
 	// left untouched.
 	const explanation = epic_report.format_result(result, context.repo)
@@ -178,8 +177,7 @@ function combine(views: ReadonlyArray<EpicView>, context: PoolContext): EpicNext
 	})
 
 	// The same checkout map `epic:next` hands `build_result`. Without it every bundle heading reads
-	// `(no local checkout)`, including this repository's own — the misreport joshuafolkken/kit#864
-	// fixed on that path.
+	// `(no local checkout)`, including this repository's own.
 	return epic_report.build_result(
 		backlog_pool.merge_classifications(from_epics, from_standalone),
 		[
@@ -192,8 +190,7 @@ function combine(views: ReadonlyArray<EpicView>, context: PoolContext): EpicNext
 
 // The epic half and the standalone half settled against each other: an epic child a person has to
 // resolve can make a standalone row wait on that person, and that row can in turn hold an epic child.
-// Each pass only shrinks the set, so the walk ends at the first pass that removes nothing
-// (joshuafolkken/kit#1943).
+// Each pass only shrinks the set, so the walk ends at the first pass that removes nothing.
 function settled_views(
 	reads: ReadonlyArray<EpicRead>,
 	running: ReadonlySet<string>,
@@ -215,7 +212,7 @@ function settled_views(
 // walk rather than the only one.
 //
 // The running set covers the standalone rows as well as every read graph, so an epic child waiting on
-// an opted-in standalone issue waits rather than stops (joshuafolkken/kit#1943).
+// an opted-in standalone issue waits rather than stops.
 function views_from(reads: ReadonlyArray<EpicRead>, context: PoolContext): ReadonlyArray<EpicView> {
 	if (reads.length === 0) return []
 
@@ -230,8 +227,8 @@ function views_from(reads: ReadonlyArray<EpicRead>, context: PoolContext): Reado
 
 // The reads and the classification, with none of the printing `backlog:next` then does with them.
 //
-// `backlog:plan` renders this same pool as a plan a person reads before the run starts
-// (joshuafolkken/kit#1652), so the seam is cut here rather than a second read-and-classify path
+// `backlog:plan` renders this same pool as a plan a person reads before the run starts,
+// so the seam is cut here rather than a second read-and-classify path
 // being written beside it: the plan and the run cannot disagree about what may start, because there
 // is one answer and two renderings of it. `undefined` is the refusal — already reported.
 async function resolve(context: PoolContext): Promise<EpicNextResult | undefined> {
@@ -249,7 +246,7 @@ async function resolve(context: PoolContext): Promise<EpicNextResult | undefined
 	}
 
 	// The defect priority and the ranking keys are applied here rather than when printing, so
-	// `backlog:plan` shows the order the run takes (joshuafolkken/kit#2455, joshuafolkken/kit#2928). The
+	// `backlog:plan` shows the order the run takes. The
 	// ranking goes last: its sort is stable, so the defect order survives as its final key.
 	const ordered = await backlog_defect_priority.prioritize(
 		combine(views_from(reads, context), context),
@@ -261,11 +258,10 @@ async function resolve(context: PoolContext): Promise<EpicNextResult | undefined
 
 // Whether the `error` verdict is really a transport failure wearing the graph's clothes.
 //
-// **The answer comes from the reads that failed, not from a request made afterwards**
-// (joshuafolkken/kit#1690). joshuafolkken/kit#1663 asked a reachability probe here, once the answer
-// was otherwise final — and a connection that dropped for a few hundred milliseconds failed the read
-// at t=0 and answered that probe `reachable`, leaving the verdict `error` for a fault that had
-// already healed. Judging one request from a different one cannot be made reliable, so the failed
+// **The answer comes from the reads that failed, not from a request made afterwards**. A later
+// reachability probe can answer `reachable` after a connection that dropped for a few hundred
+// milliseconds already failed the read, leaving the verdict `error` for a fault that had already
+// healed. Judging one request from a different one cannot be made reliable, so the failed
 // request carries its own nature instead: `epic:next` marks the anomaly from the status GitHub wrote
 // on the failed response, and this reads the mark.
 function is_transport_failure(result: EpicNextResult): boolean {
@@ -300,19 +296,19 @@ function standalone_keys(context: PoolContext): ReadonlySet<string> {
 }
 
 // The running lanes still carry the pickup label, so the opted-in listing holds their bodies too —
-// which is what lets a candidate be held back from a restructure a running lane already makes
-// (joshuafolkken/kit#3221). `backlog:plan --waves` reads the same scope, so its first wave is this offer.
+// which is what lets a candidate be held back from a path a running lane already declares.
+// `backlog:plan --waves` reads the same scope, so its first wave is this offer.
 function gate_scope(context: PoolContext): GateScope {
 	return {
 		standalone: standalone_keys(context),
-		declared: backlog_restructure.declared_of(context.opted_in.issues),
+		declared: backlog_overlap.declared_of(context.opted_in.issues),
 	}
 }
 
 // The `run:solo` gate is applied here rather than in `resolve`, because `backlog:plan` shares
-// `resolve` and a plan made before the run lists everything (joshuafolkken/kit#2776). The holders are
+// `resolve` and a plan made before the run lists everything. The holders are
 // read only on a `run` answer — the one answer the gate can change. The cap follows the gate
-// (`backlog-rank.ts`, joshuafolkken/kit#2928).
+// (`backlog-rank.ts`).
 async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<EpicNextResult> {
 	if (result.verdict !== 'run') return result
 
@@ -331,7 +327,7 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 	return gated.result
 }
 
-// An untriaged candidate withholds every candidate (joshuafolkken/kit#2779). Checked before the
+// An untriaged candidate withholds every candidate. Checked before the
 // `run:solo` gate, which cannot be applied to an issue whose label is not recorded yet; the numbers go
 // to standard error, the one token to standard output.
 function report_triage(context: PoolContext, untriaged: ReadonlyArray<EpicChild>): number {

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

@@ -2,17 +2,18 @@
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { json_value } from '#scripts/lib/json-value'
 import { rule_value_cache } from '#scripts/rules/rule-value-cache'
 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'
 
-// `josh backlog:offer` — one composite command for a `backlogrun` loop-head event
-// (joshuafolkken/kit#2162). The loop used to spend a turn on `backlog:next` and a second turn feeding
+// `josh backlog:offer` — one composite command for a `backlogrun` loop-head event.
+// Without it the loop spends a turn on `backlog:next` and a second turn feeding
 // its answer, translated to a word by hand, into `backlog:budget`; the parent's context is largest
 // here, so collapsing the two saves the turn where a turn costs the most — the same reasoning
-// `run:merge` collapsed a merge event on.
+// `run:merge` collapses a merge event on.
 //
 // **The contract matches the path-decided commands': stdout carries the budget verdict on its first
 // line**, then — only on `run` — the issue numbers to start, one per line, so a loop reads the branch
@@ -28,7 +29,7 @@ const DEFAULT_COUNT = 0
 const RUN_VERDICT = 'run'
 const BUDGET_JSON_KEY = 'budget'
 // The one budget verdict and mapped answer that name a drain, plus the running count that means the run
-// has nothing of its own in flight (joshuafolkken/kit#2335). Read together in `mark_drain`.
+// has nothing of its own in flight. Read together in `mark_drain`.
 const WATCH_VERDICT = 'watch'
 const STOP_VERDICT = 'stop'
 const EXHAUSTED_ANSWER = 'exhausted'
@@ -124,27 +125,26 @@ const budget_read_schema = z.object({
 	[BUDGET_JSON_KEY]: z.string(),
 	reason: z.string(),
 	is_finish: z.boolean(),
+	idle: z.string().optional(),
 })
 
 interface BudgetRead {
 	verdict: string
 	reason: string
 	is_finish: boolean
+	// The idle watch's window, as `backlog_idle.text_of` wrote it, when the budget opened one.
+	idle?: string | undefined
 }
 
 function budget_of(out: string): BudgetRead | undefined {
-	try {
-		const parsed = budget_read_schema.safeParse(JSON.parse(out))
-
-		return parsed.success
-			? {
-					verdict: parsed.data[BUDGET_JSON_KEY],
-					reason: parsed.data.reason,
-					is_finish: parsed.data.is_finish,
-				}
-			: undefined
-	} catch {
-		return undefined
+	const read = json_value.parse_with(out, budget_read_schema)
+	if (read === undefined) return undefined
+
+	return {
+		verdict: read[BUDGET_JSON_KEY],
+		reason: read.reason,
+		is_finish: read.is_finish,
+		idle: read.idle,
 	}
 }
 
@@ -192,13 +192,12 @@ function refuse(): number {
 
 // The drain: the backlog is empty (`exhausted`) and nothing of the run's own is in flight, so the run is
 // about to open its idle watch or stop with `--idle 0`. Marking once per drain with `emit_once`
-// is what lets `run:step` fire the end-of-run retrospective *before* the watch rather than after it
-// (joshuafolkken/kit#2335), so the improvement issues the retrospective files are what the watch then
+// is what lets `run:step` fire the end-of-run retrospective *before* the watch rather than after it,
+// so the improvement issues the retrospective files are what the watch then
 // picks up. A watch that opened while children were still merging (`running > 0`) is not this drain: the
 // retrospective waits for the true idle, and the marker is emitted from the loop head for the same
 // reason `run:merge` emits its own events — the command that detects the event owns writing it.
-// Returns whether this call wrote the marker, so `backlog:drive` stops once per drain
-// (joshuafolkken/kit#2508).
+// Returns whether this call wrote the marker, so `backlog:drive` stops once per drain.
 async function mark_drain(verdict: string, answer: string, running: number): Promise<boolean> {
 	if (answer !== EXHAUSTED_ANSWER || running !== NO_RUNNING) return false
 	if (verdict !== WATCH_VERDICT && verdict !== STOP_VERDICT) return false
@@ -226,6 +225,12 @@ async function decide(values: ParsedValues, counts: OfferCounts): Promise<number
 
 	await mark_drain(decision.verdict, offer.answer, counts.running)
 
+	// The idle window with the ask that read it, once per watching poll, so `run:board` counts the next
+	// check from the poll that ran rather than guessing one.
+	if (decision.idle !== undefined) {
+		await run_event_stream_emit.emit_changed(run_event_stream.EVENT_KIND.IDLE, decision.idle)
+	}
+
 	return emit(decision, offer, values.json === true)
 }
 
@@ -236,9 +241,9 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	// The loop head is the one place `rule:value` is read from: once per iteration, the parent's
 	// context still small, so a rule that never fires shows up as a printed row rather than as
-	// something a person has to remember to measure (joshuafolkken/kit#2271). It prints the cached
-	// reading and refreshes it in a detached process, so the offer never waits on the measurement
-	// (joshuafolkken/kit#2881), and it never fails, so a broken reading never stops the backlog.
+	// something a person has to remember to measure. It prints the cached
+	// reading and refreshes it in a detached process, so the offer never waits on the measurement,
+	// and it never fails, so a broken reading never stops the backlog.
 	rule_value_cache.emit()
 
 	const counts = counts_of(values)

package/scripts/backlog/backlog-offer.ts

@@ -1,23 +1,23 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import type { BacklogAnswer } from './backlog-budget'
 import { backlog_next } from './backlog-next'
 
-// The mechanical half of `josh backlog:offer` (joshuafolkken/kit#2162): turn what `backlog:next`
+// The mechanical half of `josh backlog:offer`: turn what `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-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
-// consecutive one, which is `unreadable`. Both are decided from a count here rather than from a
-// judgement (joshuafolkken/kit#3175 dropped the prose copy from `backlogrun-steps.md`).
+// context branches an agent would otherwise apply 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 consecutive one, which is `unreadable`. Both are decided from a count here rather than from a
+// judgement.
 
 // Three consecutive `retry` answers end the run: below that a transport hiccup is re-asked, at it the
 // outage is not a hiccup. "`josh backlog:offer`" is the single source of the count.
 const RETRY_LIMIT = 3
 const FAILURE_EXIT_CODE = 1
 const NO_RETRIES = 0
-const NUMBER_PATTERN = /^[1-9]\d*$/u
 
 const TOKENS = backlog_next.VERDICT_TOKENS
 
@@ -70,7 +70,7 @@ function from_verdict(token: string, running: number, retries: number): OfferAns
 }
 
 function is_numbers(tokens: ReadonlyArray<string>): boolean {
-	return tokens.length > 0 && tokens.every((token) => NUMBER_PATTERN.test(token))
+	return tokens.length > 0 && tokens.every((token) => issue_number_shape.is_issue_number(token))
 }
 
 // **Read the exit code before the tokens.** Exit 1 is "the listing could not be read", which is never

package/scripts/backlog/backlog-overlap.ts

@@ -0,0 +1,178 @@
+import type { BusyRead } from '#scripts/epic/epic-busy'
+import type { EpicChild } from '#scripts/epic/epic-graph'
+import type { SoloSelection } from '#scripts/epic/epic-solo'
+import { session_cite } from '#scripts/issue/session-cite'
+
+// Which candidates may not run side by side because their bodies declare overlapping paths.
+// joshuafolkken/kit#3221 held back only a path both bodies named beside a move, split, rename or
+// delete verb, on the reading that a plain overlap always merged mechanically. It did not:
+// joshuafolkken/kit#3582 named `scripts/lines/effective-limit.ts`, joshuafolkken/kit#3586 named
+// `scripts/lines/**`, and the two lanes met a content conflict that stopped the second ship
+// (joshuafolkken/kit#3617). So any overlap now holds the later one back — the same file named by
+// both, or a path inside the other's directory glob. A directory one segment deep (`scripts/`) is
+// too broad to count, and an issue reference (`owner/repo#N`) is not a path. A dotted token with no
+// `/` is a file only when its extension is one this repository keeps at the root — otherwise
+// `session_cite.issue` or `process.env` would claim a path and serialize unrelated lanes.
+const CODE_SPAN = /`([^`\s]+)`/gu
+const LINE_SUFFIX = /:\d+(?:[-:]\d+)?$/u
+const FILE_EXTENSION = /\.[a-z]\w*$/iu
+const ROOT_FILE_EXTENSION = /\.(?:[cm]?[jt]sx?|svelte|jsonc?|md|ya?ml|css|html|sh|toml|txt)$/u
+const GLOB = '*'
+const ISSUE_MARK = '#'
+const SEPARATOR = '/'
+const MIN_DIRECTORY_DEPTH = 2
+
+// The paths each issue declares, by issue number. A directory ends in `/`; anything else is a file.
+type Declared = ReadonlyMap<number, ReadonlySet<string>>
+
+interface DeclaringIssue {
+	number: number
+	body?: string | undefined
+}
+
+// `scripts/lines/**` and `scripts/lines/*.ts` declare `scripts/lines/`; a path with no glob is itself.
+function without_glob(path: string): string {
+	const glob = path.indexOf(GLOB)
+
+	return glob === -1 ? path : path.slice(0, path.lastIndexOf(SEPARATOR, glob) + 1)
+}
+
+function is_narrow(directory: string): boolean {
+	return directory.split(SEPARATOR).filter(Boolean).length >= MIN_DIRECTORY_DEPTH
+}
+
+function is_file(path: string): boolean {
+	return (path.includes(SEPARATOR) ? FILE_EXTENSION : ROOT_FILE_EXTENSION).test(path)
+}
+
+function claim_of(path: string): string | undefined {
+	if (path.endsWith(SEPARATOR)) return is_narrow(path) ? path : undefined
+
+	return is_file(path) ? path : undefined
+}
+
+// The backticked files and directories `body` declares.
+function declared_paths(body: string): ReadonlySet<string> {
+	const tokens = [...body.matchAll(CODE_SPAN)].map((match) => match[1] ?? '')
+	const paths = tokens
+		.filter((token) => !token.includes(ISSUE_MARK))
+		.map((token) => claim_of(without_glob(token.replace(LINE_SUFFIX, ''))))
+
+	return new Set(paths.filter((path) => path !== undefined))
+}
+
+function declared_of(issues: ReadonlyArray<DeclaringIssue>): Declared {
+	return new Map(issues.map((issue) => [issue.number, declared_paths(issue.body ?? '')]))
+}
+
+function contains(outer: string, inner: string): boolean {
+	return outer.endsWith(SEPARATOR) ? inner.startsWith(outer) : outer === inner
+}
+
+function overlaps(left: string, right: string): boolean {
+	return contains(left, right) || contains(right, left)
+}
+
+interface SeparateContext {
+	read: BusyRead
+	repo: string
+}
+
+// The path each running lane declares, mapped to the issue that holds it.
+function running_claims(declared: Declared, read: BusyRead): Map<string, number> {
+	const holders = read.kind === 'busy' ? read.issues.map((issue) => issue.number) : []
+	const pairs = holders.flatMap((number) =>
+		[...(declared.get(number) ?? [])].map((path): [string, number] => [path, number]),
+	)
+
+	return new Map(pairs)
+}
+
+function paths_of(child: EpicChild, declared: Declared, repo: string): ReadonlySet<string> {
+	if (child.repo !== repo) return new Set()
+
+	return declared.get(child.number) ?? new Set()
+}
+
+interface Clash {
+	path: string
+	claimed: string
+	holder: number
+}
+
+function clash_of(
+	claims: ReadonlyMap<string, number>,
+	paths: ReadonlySet<string>,
+): Clash | undefined {
+	const clashes = [...paths].flatMap((path) =>
+		[...claims]
+			.filter(([claimed]) => overlaps(claimed, path))
+			.map(([claimed, holder]): Clash => ({ path, claimed, holder })),
+	)
+
+	return clashes[0]
+}
+
+function clash_note(child: EpicChild, clash: Clash): string {
+	const waiting = session_cite.issue(child.number, undefined, child.repo)
+	const holder = session_cite.issue(clash.holder, undefined, child.repo)
+
+	return `${waiting} waits: its \`${clash.path}\` overlaps \`${clash.claimed}\`, which ${holder} declares.`
+}
+
+interface Walk {
+	claims: Map<string, number>
+	offered: Array<EpicChild>
+	withheld: Array<EpicChild>
+	notes: Array<string>
+}
+
+function visit(walk: Walk, child: EpicChild, paths: ReadonlySet<string>): void {
+	const clash = clash_of(walk.claims, paths)
+
+	if (clash === undefined) {
+		walk.offered.push(child)
+		for (const path of paths) walk.claims.set(path, child.number)
+
+		return
+	}
+
+	walk.withheld.push(child)
+	walk.notes.push(clash_note(child, clash))
+}
+
+function merged_notice(
+	notice: string | undefined,
+	notes: ReadonlyArray<string>,
+): string | undefined {
+	const parts = notice === undefined ? notes : [notice, ...notes]
+
+	return parts.length === 0 ? undefined : parts.join('\n')
+}
+
+// `selection` with every offered candidate that declares a path overlapping one a running lane or
+// an earlier candidate already declares moved to `withheld`, in offer order.
+function separate(
+	selection: SoloSelection,
+	declared: Declared,
+	context: SeparateContext,
+): SoloSelection {
+	const walk: Walk = {
+		claims: running_claims(declared, context.read),
+		offered: [],
+		withheld: [],
+		notes: [],
+	}
+
+	for (const child of selection.offered) visit(walk, child, paths_of(child, declared, context.repo))
+
+	const notice = merged_notice(selection.notice, walk.notes)
+	const withheld = [...walk.withheld, ...selection.withheld]
+
+	return { offered: walk.offered, withheld, ...(notice !== undefined && { notice }) }
+}
+
+const backlog_overlap = { declared_of, declared_paths, separate }
+
+export { backlog_overlap }
+export type { Declared }