@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/auto-ok/auto-ok-cli.ts

@@ -10,9 +10,9 @@ import { cutoff_cause, cutoff_of, type ScanCutoff } from '#scripts/git/listing-c
 import { read_json_listing } from '#scripts/git/parse-json-array'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
 import { AUTO_OK_LABEL } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
 
-// `josh auto-ok:next` — which issue outside the epic an unattended run picks up next
-// (joshuafolkken/kit#906).
+// `josh auto-ok:next` — which issue outside the epic an unattended run picks up next.
 //
 // A command rather than a documented `gh` invocation, for the reason the label constant exists: the
 // name `auto-ok` is single-sourced in `scripts/issue/issue-labels.ts`, and a procedure that told an
@@ -33,29 +33,23 @@ const USAGE = `Usage: josh auto-ok:next [${EXCLUDE_FLAG} <issue-number>[,<issue-
 const NONE_TOKEN = 'none'
 // Wide enough that the cap is never what decides the order. The listing is newest first because
 // `git-gh-issue-list.ts` spells `sort=created&direction=desc` into every request rather than leaning
-// on REST's default (joshuafolkken/kit#1025), so a truncated listing drops the *oldest* opted-in
+// on REST's default, so a truncated listing drops the *oldest* opted-in
 // issues — which is reported rather than silently ranked.
 const LISTING_LIMIT = 200
 
 // Two different gaps, told apart because they send a person to two different places. A listing that
 // never arrived is an access or connectivity problem; a listing that arrived in a shape the schema
 // rejects is the rows' fields having changed under the REST mapping in `git-gh-issue-rest.ts`, where
-// `gh auth status` is green and checking it wastes the one hint the message had to give
-// (joshuafolkken/kit#996).
-//
-// The second message named `gh --version` until joshuafolkken/kit#1069. The listing has been REST
-// since joshuafolkken/kit#1025 and `git-gh-issue-list.ts` builds the JSON this parser reads, so the
-// CLI's version cannot be what changed the row shape — the same misdirection the message below
-// already refuses to repeat for the blocker relations, left standing one constant above it.
+// `gh auth status` is green and checking it wastes the one hint the message had to give. Neither
+// names `gh --version`: the listing is REST and `git-gh-issue-list.ts` builds the JSON this parser
+// reads, so the CLI's version cannot be what changed the row shape.
 const UNREADABLE_MESSAGE = `Could not read the \`${AUTO_OK_LABEL}\` listing. That is not "nothing is opted in" — check \`gh auth status\` and ask again.`
 const UNEXPECTED_SHAPE_MESSAGE = `Read the \`${AUTO_OK_LABEL}\` listing but could not parse it. That is not "nothing is opted in" — the rows came back in a shape this command does not recognize, so check the fields it asks for and the REST field mapping in \`scripts/gh/git-gh-issue-rest.ts\` rather than your authentication.`
 // The blocker relations failing takes the whole listing with them, and `issue_list` swallows
 // the error — so the read looks exactly like an access failure and sends the reader to
-// `gh auth status`, which is green. That is the misdirection joshuafolkken/kit#996 added the message
-// above to remove, walked straight back in by the field the same change started asking for
-// (joshuafolkken/kit#1005).
+// `gh auth status`, which is green — the misdirection the message above exists to remove.
 //
-// The listing is REST now, so the cause is no longer `gh`'s version: the relations come from each
+// The cause is not `gh`'s version either: the relations come from each
 // issue's own `dependencies/blocked_by` endpoint, and it is those requests — not the CLI — that the
 // probe has just shown to be the difference. Naming `gh --version` here would send a reader on a
 // current `gh` to the one place the answer is not.
@@ -63,12 +57,12 @@ const UNEXPECTED_SHAPE_MESSAGE = `Read the \`${AUTO_OK_LABEL}\` listing but coul
 // It names both causes rather than asserting one. The probe separates "the relations" from "the
 // listing", and it cannot separate a host that does not serve dependencies from a rate limit reached
 // by the one-request-per-blocked-issue pass — so claiming the first would be the same misdirection
-// in a new place (joshuafolkken/kit#1025).
+// in a new place.
 const BLOCKERS_UNREADABLE_MESSAGE = `Could not read the \`${AUTO_OK_LABEL}\` listing, though the same listing reads once the blocker relations are dropped from it — so it is reading the relations that failed, not your authentication. That is one \`dependencies/blocked_by\` request per opted-in issue declaring a blocker: either this GitHub host does not serve issue dependencies, or those requests are being rate limited. Ask again, and check the host if it persists.`
 // Said once the answer is known, so it never claims there is an answer below when there is not.
 // Either cutoff only ever drops the *oldest* opted-in issues, the listing being newest first, so the
 // consequence is one sentence — but the two cite different numbers and a reader who wants the
-// listing widened reaches for a different knob for each (joshuafolkken/kit#1067).
+// listing widened reaches for a different knob for each.
 const TRUNCATED_BY_LIMIT = `hit the ${String(LISTING_LIMIT)}-issue cap`
 const TRUNCATED_WITH_ANSWER =
 	'; the answer below is opted in, but it may not be the highest-priority one.'
@@ -81,8 +75,8 @@ function truncated_cause(cutoff: ScanCutoff): string | undefined {
 
 const NONE_OPTED_IN_MESSAGE = `No open issue carries \`${AUTO_OK_LABEL}\`.`
 // The epic listing failing is not "no epic tracks anything". Read that way, every child of every
-// epic reads as a standalone candidate and the pickup hands one back out of its epic's order — the
-// single failure joshuafolkken/kit#1633 is about, arriving with exit 0 and nothing said.
+// epic reads as a standalone candidate and the pickup hands one back out of its epic's order,
+// arriving with exit 0 and nothing said.
 const EPICS_UNREADABLE_MESSAGE = `Could not read the epic listing, so which issues an epic already tracks is unknown. That is not "no epic tracks anything" — an opted-in child would be handed back outside its epic's order, so no answer is given. Check \`gh auth status\` and ask again.`
 const CLOSED_STATE = 'CLOSED'
 const NO_CUTOFF: ScanCutoff = 'none'
@@ -91,12 +85,12 @@ const NO_CUTOFF: ScanCutoff = 'none'
 // effect asynchronously, so for a few seconds after a merge the issue is still listed as open —
 // which is why `prioritize` takes this number at all, and why a pickup loop that never passes it
 // leaves an already-merged issue to be excluded only by the `in-progress` label it happens to still
-// carry (joshuafolkken/kit#906).
+// carry.
 interface NextOptions {
 	// Every number the caller asked to skip. A pickup loop passes the ones it has already run this
 	// session, not just the last: `closes #N` can fail to fire — a reference dropped from a PR body —
 	// and the `in-progress` label the procedure itself calls an unreliable guard is then the only
-	// thing standing between the loop and running an issue twice (joshuafolkken/kit#996).
+	// thing standing between the loop and running an issue twice.
 	exclude?: ReadonlyArray<number>
 	usage?: string
 }
@@ -134,7 +128,7 @@ function parse_pair(argv: ReadonlyArray<string>, index: number): ReadonlyArray<n
 // argument.
 //
 // `usage` is a parameter so a second command with the same `--exclude` grammar reuses this rather
-// than copying the loop — `josh backlog:next` does (joshuafolkken/kit#1630). Only the line printed on
+// than copying the loop — `josh backlog:next` does. Only the line printed on
 // a bad argument differs between them, and a caller that passes nothing gets this command's own.
 function parse_options(argv: ReadonlyArray<string>, usage: string = USAGE): NextOptions {
 	const exclude: Array<number> = []
@@ -150,23 +144,22 @@ function parse_options(argv: ReadonlyArray<string>, usage: string = USAGE): Next
 
 // Every open issue carrying the label, or which of two gaps stopped the read. Neither gap is an
 // empty listing: reading a failed read as "none" ends the run reporting a confident absence built on
-// a response nobody parsed (joshuafolkken/kit#950). They stay apart from each other because the zod
+// a response nobody parsed. They stay apart from each other because the zod
 // rejection `parse_json_array_or_undefined` deliberately rethrows means the listing's *fields*
-// changed, not that the caller's authentication lapsed (joshuafolkken/kit#996).
+// changed, not that the caller's authentication lapsed.
 type OptedInRead =
 	| { kind: 'read'; issues: Array<OpenIssueData>; cutoff: ScanCutoff }
 	| { kind: 'unreadable' }
 	| { kind: 'unexpected_shape' }
 	| { kind: 'blockers_unreadable' }
 
-// The two gaps `read_json_listing` names, carried through unchanged. Since joshuafolkken/kit#1025
-// `raw` is the JSON `git-gh-issue-list.ts` assembles from the REST rows rather than a CLI's stdout,
+// The two gaps `read_json_listing` names, carried through unchanged. `raw` is the JSON `git-gh-issue-list.ts` assembles from the REST rows rather than a CLI's stdout,
 // so a transport failure — a rate limit, a dropped connection — never reaches this parser at all:
 // `issue_list` catches it into `json === undefined` and `classify_failed_read` decides what it
 // was. What does reach here is the rethrown zod rejection, meaning the listing arrived and its
 // *fields* were not what was asked for. `unreadable` is passed on rather than folded away because
-// reading a gap as an empty listing is the confident absence kit#950 exists to prevent, and this is
-// not the place to make that assumption.
+// reading a gap as an empty listing is a confident absence built on a response nobody parsed, and
+// this is not the place to make that assumption.
 function parse_listing(raw: string, is_capped: boolean): OptedInRead {
 	const read = read_json_listing(raw, open_issue_schema)
 	if (read.kind !== 'read') return { kind: read.kind }
@@ -180,8 +173,7 @@ function parse_listing(raw: string, is_capped: boolean): OptedInRead {
 
 // Whether the *identical* listing reads once `blockedBy` is dropped from it. Named for what it
 // answers rather than for what it implies, because the two are opposite: a `true` here means the
-// field was the problem, and an earlier spelling returned the failure instead — correct only because
-// its one call site inverted it back (joshuafolkken/kit#1005).
+// field was the problem.
 //
 // **Only the field list changes.** Varying the limit as well would let a rate limit or a timeout that
 // a smaller request happens to survive read as the blocker relations failing, on a host that serves
@@ -200,8 +192,7 @@ async function reads_without_blocked_by(): Promise<boolean> {
 // success of that form is not enough on its own: a network blip or a passing rate limit on the first
 // read clears by the time the probe runs, and the run would then send someone whose host serves
 // dependencies perfectly well to look at it. `issue_list` swallows the underlying error, so
-// repeating the original read is what separates a transient failure from a standing one
-// (joshuafolkken/kit#1005).
+// repeating the original read is what separates a transient failure from a standing one.
 async function classify_failed_read(): Promise<OptedInRead> {
 	if (!(await reads_without_blocked_by())) return { kind: 'unreadable' }
 
@@ -226,14 +217,12 @@ async function fetch_opted_in(): Promise<OptedInRead> {
 // relation `epic:next` builds its graph from, and each blocker's state comes back alongside its
 // number, so no blocker needs a read of its own.
 //
-// The relations are not in the listing response at all since joshuafolkken/kit#1025 — REST serves
-// them from each issue's own dependencies endpoint — so this pickup pays one extra request per row
+// The relations are not in the listing response at all — REST serves them from each issue's own dependencies endpoint — so this pickup pays one extra request per row
 // whose own dependency summary does not report exactly zero blockers, and nothing for the rest.
 //
 // An unattended run must not start an issue whose prerequisite is still open: `auto-ok` is applied
-// by a person to an issue they judged needs no decision, which says nothing about ordering, and the
-// pickup previously consulted only the `epic` / `in-progress` / `needs-decision` labels
-// (joshuafolkken/kit#996). A blocker with no state reads as standing — the safe direction, since the
+// by a person to an issue they judged needs no decision, which says nothing about ordering.
+// A blocker with no state reads as standing — the safe direction, since the
 // cost is deferring an issue rather than implementing one out of order.
 // `nodes` is a page — fifty under GraphQL, one hundred under REST. When `totalCount` says there are
 // more, the ones outside the page are unknown, and unknown reads as standing — the same direction
@@ -248,7 +237,7 @@ function is_page_complete(blocked_by: OpenIssueData['blockedBy']): boolean {
 
 // `epic_issue.normalize_state` rather than a second spelling of it: the epic commands already read
 // GitHub's state casing through one function, and "is this blocker closed" is the question it
-// answers (joshuafolkken/kit#862). A blocker reported without a state reads as standing.
+// answers. A blocker reported without a state reads as standing.
 function is_closed(blocker: { state?: string | undefined }): boolean {
 	return epic_issue.normalize_state(blocker.state ?? '') === CLOSED_STATE
 }
@@ -261,21 +250,20 @@ function is_unblocked(issue: OpenIssueData): boolean {
 
 // Which issues an epic already tracks, or that the epic listing could not be read.
 //
-// **The question is membership, not a label** (joshuafolkken/kit#1633). An epic's child carries none
+// **The question is membership, not a label**. An epic's child carries none
 // of `epic` / `in-progress` / `needs-decision`, so the label comparison inside `prioritize` never
-// saw one — and `auto-ok` on a child put that child in the standalone candidate set, where the
+// sees one — and `auto-ok` on a child would put that child in the standalone candidate set, where the
 // epic's `blockedBy` ordering is never consulted. The epics themselves are still found by the `epic`
 // label, exactly as `epic:bundle` finds them, so this does not survive an epic that never received
-// it — what it removes is the *child's* labels deciding, which is the half that was failing.
+// it — what it removes is the *child's* labels deciding.
 //
-// **The whole index is carried rather than its key set** (joshuafolkken/kit#1668). Which epic tracks
+// **The whole index is carried rather than its key set**. Which epic tracks
 // a child decides both whether the standalone half withholds it — `epic_index.withheld_children` —
-// and, when it is withheld, the number `backlog:plan` names as the reason. Flattening to a `Set`
-// here threw that number away, so the plan reported a listing cap it had never reached.
+// and, when it is withheld, the number `backlog:plan` names as the reason.
 //
-// **And every tracking epic, not one winner** (joshuafolkken/kit#1694). Two epics can name the same
+// **And every tracking epic, not one winner**. Two epics can name the same
 // child, and a map of one epic per child keeps whichever came last — so an opted-in epic that came
-// earlier vanished, and the child was offered standalone *and* through that epic.
+// earlier would vanish, and the child be offered standalone *and* through that epic.
 type TrackingRead =
 	| { kind: 'read'; index: ReadonlyMap<number, ReadonlyArray<number>>; cutoff: ScanCutoff }
 	| { kind: 'epics_unreadable' }
@@ -313,8 +301,7 @@ async function fetch_tracking(count: number): Promise<TrackingRead> {
 // The pickup *order* is `git_next_issues.order` itself, not a copy of it: the ranking `prioritize`
 // shows, with the `epic` / `in-progress` / `needs-decision` exclusions, before its display cap.
 //
-// The two are no longer the same *set*, and deliberately so: since joshuafolkken/kit#996 the pickup
-// also drops a candidate whose prerequisite is still open, while `🗒 Next issues` shows every open
+// The two are not the same *set*, and deliberately so: the pickup also drops a candidate whose prerequisite is still open, while `🗒 Next issues` shows every open
 // issue and leaves the judgement to the person reading it. So the display can name an issue this
 // command refuses — a person can see a blocked issue is next and decide to start it anyway, and an
 // unattended run must not.
@@ -326,20 +313,19 @@ async function fetch_tracking(count: number): Promise<TrackingRead> {
 // `prioritize`'s capped one, which would answer `none` whenever its first rows happen to be blocked
 // while a runnable issue sits below them. They are applied **after** the ranking, not before it: the
 // dependents key counts the issues waiting on a row, and a waiting issue is by definition blocked —
-// filtered first, every row would count zero and the key would never decide anything
-// (joshuafolkken/kit#2928).
+// filtered first, every row would count zero and the key would never decide anything.
 //
 // The `🗒 Next issues` display is deliberately *not* filtered this way; `git-next-issues.ts` records
 // why, and the short version is that a person can see a blocked issue and choose to start it anyway
-// while an unattended run cannot (joshuafolkken/kit#1005).
+// while an unattended run cannot.
 //
 // A child of an epic that is itself opted in is dropped here for the same reason and by the same
 // rule: that epic's declared order sequences its children, and it is going to offer them, so a
-// standalone offer would skip the order and hand the same issue over twice (joshuafolkken/kit#1633).
-// **A child of an epic that is *not* opted in is no longer dropped** — no path would ever offer it,
-// which made a person's `auto-ok` on the child silently inert, and the order it does have is carried
-// by the native `blockedBy` relations `is_unblocked` already refuses to run past
-// (joshuafolkken/kit#1668). `tracked` is the narrowed set `epic_index.withheld_children` builds, not
+// standalone offer would skip the order and hand the same issue over twice.
+// **A child of an epic that is *not* opted in is kept** — no path would otherwise offer it, which
+// would make a person's `auto-ok` on the child silently inert, and the order it does have is carried
+// by the native `blockedBy` relations `is_unblocked` already refuses to run past.
+// `tracked` is the narrowed set `epic_index.withheld_children` builds, not
 // every tracked child; this function only applies it.
 function is_runnable(
 	issue: OpenIssueData,
@@ -370,7 +356,7 @@ function none_reason(count: number): string {
 
 // Said only when the cap actually bit, and worded from the answer rather than before it: the one run
 // where truncation matters is the one where everything listed was excluded, and announcing "the
-// answer below is opted in" there contradicted the `none` that followed (joshuafolkken/kit#996).
+// answer below is opted in" there contradicted the `none` that followed.
 function truncation_note(cutoff: ScanCutoff, has_answer: boolean): string | undefined {
 	const cause = truncated_cause(cutoff)
 	if (cause === undefined) return undefined
@@ -414,14 +400,14 @@ function report(context: PickupContext): number {
 		return SUCCESS_EXIT_CODE
 	}
 
-	console.error(`#${String(next.number)} ${next.title}`)
+	console.error(session_cite.issue(next.number, next.title))
 	console.info(String(next.number))
 
 	return SUCCESS_EXIT_CODE
 }
 
 // The second listing runs only once the first one has an answer to filter, and its failure is
-// reported rather than folded into "no epic tracks anything" (joshuafolkken/kit#1633).
+// reported rather than folded into "no epic tracks anything".
 async function answer(
 	read: { issues: Array<OpenIssueData>; cutoff: ScanCutoff },
 	exclude?: ReadonlyArray<number>,
@@ -444,7 +430,7 @@ async function answer(
 }
 
 // The gap that stopped the read decides the message, so a changed field list does not send anyone to
-// `gh auth status` (joshuafolkken/kit#996).
+// `gh auth status`.
 const READ_FAILURE_MESSAGES = {
 	unreadable: UNREADABLE_MESSAGE,
 	unexpected_shape: UNEXPECTED_SHAPE_MESSAGE,
@@ -474,7 +460,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 // `process.exitCode` rather than `process.exit()`: the answer is written with `console.info`, and on
 // macOS a write to a pipe is asynchronous — `process.exit()` can tear the process down before it has
 // drained, and this command's whole contract is `answer=$(pnpm josh auto-ok:next)`. The same shape
-// is already in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first (joshuafolkken/kit#996).
+// is already in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first.
 async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }

package/scripts/backlog/backlog-arrival-added.ts

@@ -0,0 +1,34 @@
+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'
+
+// Whether `pnpm josh run:add` handed the run an issue since the watcher started.
+// The arrival probe reads the backlog once a minute, and a `--only` run's pool is empty by definition, so
+// an added issue would otherwise wait for the minute — or never wake a `--only` parent at all. The event
+// stream is a local file, so this is read on every tick rather than on the probe's interval.
+
+type EventReader = () => Promise<ReadonlyArray<RunEvent>>
+
+async function read_stream(): Promise<ReadonlyArray<RunEvent>> {
+	const target = await run_event_stream_emit.stream_target()
+
+	return target === undefined ? [] : run_event_stream.read_events(target)
+}
+
+function has_added_since(events: ReadonlyArray<RunEvent>, since_ms: number): boolean {
+	return events.some(
+		(event) => event.kind === run_event_stream.EVENT_KIND.ADD && Date.parse(event.at) >= since_ms,
+	)
+}
+
+// A stream that cannot be read is no addition: the probe's own backlog read is still the fallback.
+async function is_added_since(since_ms: number, read: EventReader = read_stream): Promise<boolean> {
+	try {
+		return has_added_since(await read(), since_ms)
+	} catch {
+		return false
+	}
+}
+
+const backlog_arrival_added = { has_added_since, is_added_since }
+
+export { backlog_arrival_added }

package/scripts/backlog/backlog-arrival.ts

@@ -1,28 +1,30 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
 import type { JoshResult } from '#scripts/josh/josh-run'
+import { lane_limit_override } from '#scripts/lane/lane-limit-override'
 import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { run_headless } from '#scripts/run/run-headless'
+import { backlog_arrival_added } from './backlog-arrival-added'
 import { backlog_next } from './backlog-next'
 import { backlog_ready, type ReadyPorts, type ReadyReading } from './backlog-ready'
 import { backlog_stalled } from './backlog-stalled'
 
-// The arrival probe a `backlogrun` parent's `--wait` watcher runs while children are in flight
-// (joshuafolkken/kit#2503). An issue opted in with `auto-ok` mid-run was picked up only when the parent
-// next woke — a child's merge, or the progress interval — and in practice the ten-minute stall detector
-// became the pick-up: #2493 waited 10.5 minutes, and the person got a ⏳ notification for it.
+// The arrival probe a `backlogrun` parent's `--wait` watcher runs while children are in flight.
+// Without it, an issue opted in with `auto-ok` mid-run is picked up only when the parent
+// next wakes — a child's merge, or the progress interval — so in practice the ten-minute stall detector
+// becomes the pick-up, and the person gets a ⏳ notification for the wait.
 //
 // **The watcher's exit is the only thing that wakes a live parent**, so the probe rides it: once a
 // minute it reads the backlog the pick-up line reads (`backlog_ready.read_ready`, cheap first — a full
 // pool answers without the network read), and an issue runnable now that was not runnable when the
 // watcher started ends the wait. The exit prints the `ready #N` line as every exit does, and that line
-// is what sends the parent to `backlog:offer`. The stall detector goes back to being the safety net.
+// is what sends the parent to `backlog:offer`. The stall detector stays the safety net.
 //
 // **"New" is measured against the watcher's own start**, so one issue wakes the parent once: the next
 // `--wait` the parent starts takes the pool as it stands then — the woken issue included, dispatched or
 // not — as its baseline. A reading that fails is not an arrival; the probe says nothing and reads again
 // a minute later. A baseline that cannot be read is never read as empty — an empty one would wake the
 // parent for the whole pool — but it is not given up on either: the scheduled report no longer ends the
-// wait (joshuafolkken/kit#3102), so an inert probe would leave the parent without a wake until `--hours`. The
+// wait, so an inert probe would leave the parent without a wake until `--hours`. The
 // probe reads the baseline again each minute until one answers.
 //
 // **Every read is bounded.** The probe is awaited inside the watcher's tick loop, so a `gh` call that
@@ -54,7 +56,7 @@ function answered_issues(result: JoshResult | undefined): ReadonlyArray<string>
 	}
 
 	// `triage` names no number, yet the parent has work — so it is read as one token, which a reading
-	// sees as an arrival (joshuafolkken/kit#2779).
+	// sees as an arrival.
 	if (backlog_stalled.needs_triage(result.out)) return [epic_triage.TRIAGE_VERDICT]
 
 	return backlog_stalled.ready_tokens(result.out)
@@ -64,20 +66,32 @@ async function bounded_ready_issues(): Promise<ReadonlyArray<string>> {
 	return answered_issues(await backlog_ready.read_backlog_next(COMMAND_TIMEOUT_MS))
 }
 
-const ARRIVAL_PORTS: ReadyPorts = {
+// The backlog reads, plus whether `run:add` handed the run an issue since a given instant.
+interface ArrivalPorts extends ReadyPorts {
+	is_added_since: (since_ms: number) => Promise<boolean>
+}
+
+const ARRIVAL_PORTS: ArrivalPorts = {
 	free_lane_count: backlog_ready.free_lane_count,
 	ready_issues: bounded_ready_issues,
+	is_added_since: backlog_arrival_added.is_added_since,
 }
 
 interface ArrivalProbe {
 	has_arrived: (now_ms: number) => Promise<boolean>
 }
 
-// Runnable now, not runnable at the start, and a lane free to take it.
-function arrivals(baseline: ReadonlySet<string>, reading: ReadyReading): ReadonlyArray<string> {
+// Runnable now, not runnable at the start, and a lane free to take it. **A raised lane limit makes the
+// whole pool new**: the issues the baseline holds were waiting for a lane, and
+// the raise — unlike a merge — wakes nothing else, so the room it made would sit idle until a merge.
+function arrivals(
+	baseline: ReadonlySet<string>,
+	reading: ReadyReading,
+	is_raised: boolean,
+): ReadonlyArray<string> {
 	if (reading.free_lanes <= NO_FREE) return []
 
-	return reading.issues.filter((issue) => !baseline.has(issue))
+	return is_raised ? reading.issues : reading.issues.filter((issue) => !baseline.has(issue))
 }
 
 // The baseline is the whole runnable pool, free lane or not: an issue that was waiting for a lane is not
@@ -132,10 +146,11 @@ async function retry_baseline(
 // The next-probe instant is set before any read is awaited. A baseline that did not answer is read again
 // at the next probe instead of the reading, and the first one that answers is the baseline from then on
 // — never an arrival itself, since it is the pool as it stands.
-function probe_of(
+function pool_probe_of(
 	initial: ReadonlySet<string> | undefined,
 	first_ms: number,
 	ports: ReadyPorts,
+	is_raised: () => boolean,
 ): ArrivalProbe {
 	let next_ms = first_ms
 	// At most one entry, held in a list so the baseline that answers after an await is added rather than
@@ -153,25 +168,47 @@ function probe_of(
 
 		const reading = await read_reading(ports)
 
-		return reading !== undefined && arrivals(baseline, reading).length > NONE
+		return reading !== undefined && arrivals(baseline, reading, is_raised()).length > NONE
+	}
+
+	return { has_arrived }
+}
+
+// An issue `run:add` handed the run since the watcher started wakes the parent at the next tick, ahead
+// of the pool probe's minute.
+function probe_of(
+	initial: ReadonlySet<string> | undefined,
+	started_ms: number,
+	ports: ArrivalPorts,
+	is_raised: () => boolean,
+): ArrivalProbe {
+	const pool = pool_probe_of(initial, started_ms + PROBE_INTERVAL_MS, ports, is_raised)
+
+	async function has_arrived(now_ms: number): Promise<boolean> {
+		if (await ports.is_added_since(started_ms)) return true
+
+		return await pool.has_arrived(now_ms)
 	}
 
 	return { has_arrived }
 }
 
 // Inert outside a driving `backlogrun` parent — a `fullrun` watcher has no pool to pick from — and there
-// it reads nothing at all.
+// it reads nothing at all. The raise watch starts with the probe, so only a raise after it wakes.
 async function start(
 	now_ms: number,
-	ports: ReadyPorts = ARRIVAL_PORTS,
+	ports: ArrivalPorts = ARRIVAL_PORTS,
 	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+	watch_raise: () => Promise<() => boolean> = lane_limit_override.watch_raise,
 ): Promise<ArrivalProbe> {
 	if (!(await is_parent_safely(is_parent))) return INERT
 
-	return probe_of(await read_baseline(ports), now_ms + PROBE_INTERVAL_MS, ports)
+	const is_raised = await watch_raise()
+
+	return probe_of(await read_baseline(ports), now_ms, ports, is_raised)
 }
 
 const backlog_arrival = { PROBE_INTERVAL_MS, answered_issues, arrivals, start }
 
-export type { ArrivalProbe }
+export type { ArrivalPorts, ArrivalProbe }
 export { backlog_arrival }

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

@@ -2,7 +2,13 @@
 import { fileURLToPath } from 'node:url'
 import { path_decision } from '#scripts/josh/path-decision'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { backlog_budget, type BacklogAnswer, type BudgetInput } from './backlog-budget'
+import {
+	backlog_budget,
+	type BacklogAnswer,
+	type BudgetDecision,
+	type BudgetInput,
+} from './backlog-budget'
+import { backlog_idle } from './backlog-idle'
 
 // The thin half of `josh backlog:budget` (joshuafolkken/kit#1632): read the loop's state off the
 // command line, hand it to the pure decision, print the verdict on stdout and the reason on stderr
@@ -12,6 +18,7 @@ const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const JSON_KEY = 'budget'
+const EXHAUSTED_ANSWER: BacklogAnswer = 'exhausted'
 
 const USAGE = `Usage: josh backlog:budget --answer <${backlog_budget.ANSWERS.join('|')}> --started <ISO-8601> [--active <ISO-8601>, required unless the watch is off] [--merged <count>] [--running <count>] [--max <count>] [--idle <minutes>, 0 to turn the watch off] [--json]`
 
@@ -158,6 +165,29 @@ function build_input(values: ParsedValues, now_ms: number): BudgetInput | undefi
 	return input_of(values, { answer, now_ms, started_at_ms })
 }
 
+// The idle window, carried only on the watch an empty backlog opens — the one `idle_decision` reaches,
+// not the draining watch a reached bound returns while children still run — so `backlog:offer` can
+// record when that wait ends (joshuafolkken/kit#3430).
+function idle_of(input: BudgetInput, verdict: string): string | undefined {
+	const is_idle_watch =
+		verdict === backlog_budget.WATCH_VERDICT &&
+		input.answer === EXHAUSTED_ANSWER &&
+		backlog_budget.is_finish(input)
+	const window = is_idle_watch ? backlog_idle.window_of(input) : undefined
+
+	return window === undefined ? undefined : backlog_idle.text_of(window)
+}
+
+function print_json(input: BudgetInput, decision: BudgetDecision): void {
+	const { verdict, reason } = decision
+	const idle = idle_of(input, verdict)
+	const is_finish = backlog_budget.is_finish(input)
+
+	console.info(
+		JSON.stringify({ [JSON_KEY]: verdict, reason, is_finish, ...(idle !== undefined && { idle }) }),
+	)
+}
+
 function refuse(): number {
 	console.error(USAGE)
 
@@ -173,17 +203,15 @@ function run(argv: ReadonlyArray<string>, now_ms: number = Date.now()): number {
 
 	if (input === undefined) return refuse()
 
-	const { verdict, reason } = backlog_budget.decide(input)
+	const decision = backlog_budget.decide(input)
 
 	if (values.json === true) {
-		console.info(
-			JSON.stringify({ [JSON_KEY]: verdict, reason, is_finish: backlog_budget.is_finish(input) }),
-		)
+		print_json(input, decision)
 
 		return SUCCESS_EXIT_CODE
 	}
 
-	path_decision.print_decision(JSON_KEY, verdict, reason, false)
+	path_decision.print_decision(JSON_KEY, decision.verdict, decision.reason, false)
 
 	return SUCCESS_EXIT_CODE
 }

package/scripts/backlog/backlog-budget.ts

@@ -1,38 +1,32 @@
-// `josh backlog:budget` — whether a `backlogrun` may start more work, keep watching, or finish
-// (joshuafolkken/kit#1632).
+// `josh backlog:budget` — whether a `backlogrun` may start more work, keep watching, or finish.
 //
-// `backlog:next` says what may start; it says nothing about when the run itself should end. Before
-// this existed a `backlogrun` had exactly two endings and neither could be declared in advance: it
-// finished the moment the backlog read empty, so an issue a person opted in three minutes later
-// needed a whole new session, or it ran to the 8-hour whole-run bound, which is a limit on waiting
-// rather than a statement of scale.
+// `backlog:next` says what may start; it says nothing about when the run itself should end. Without
+// this a run would finish the moment the backlog read empty, so an issue a person opted in minutes
+// later would need a whole new session.
 //
-// **The idle watch is on by default and the maximum is not** (joshuafolkken/kit#1676). A
-// `backlogrun` with neither flag given watches an empty backlog for `DEFAULT_IDLE_MINUTES` before it
-// finishes, and takes as many issues as the backlog holds. `--idle 0` is how the watch is turned off.
+// **The idle watch is on by default and the maximum is not.** A `backlogrun` with neither flag given
+// watches an empty backlog for `DEFAULT_IDLE_MINUTES` before it finishes, and takes as many issues as
+// the backlog holds. `--idle 0` is how the watch is turned off.
 //
 // The decision is a command's rather than the loop's own arithmetic, for the reason `josh delegate`
 // and `josh review:level` are commands: a count and an elapsed time kept in an agent's head are a
-// one-shot judgement, and joshuafolkken/kit#1460 measured exactly that failure — a threshold asked
-// once and then never again while the run walked past it eight times.
+// one-shot judgement — a threshold asked once and then never again while the run walks past it.
 
 const MS_PER_MINUTE = 60_000
 const MINUTES_PER_HOUR = 60
-// `backlogrun-progress.md` → "Waiting, and never waiting forever" carried this as prose only. Held here it is
-// the same bound, decided the same way as the two new ones rather than by an agent reading a clock.
+// The whole-run bound, decided here like the idle watch and the maximum rather than by an agent reading
+// a clock.
 const WHOLE_RUN_BUDGET_HOURS = 8
 const WHOLE_RUN_BUDGET_MINUTES = WHOLE_RUN_BUDGET_HOURS * MINUTES_PER_HOUR
 const WHOLE_RUN_BUDGET_MS = WHOLE_RUN_BUDGET_MINUTES * MS_PER_MINUTE
 
-// **The default idle watch, and why it is this number** (joshuafolkken/kit#1676). The documents used
-// 30 as an example, and an example is not a reason; these three are.
+// **The default idle watch, and why it is this number.**
 //
 // - **Below it the watch is a coin flip.** What it waits for is a person noticing the run has gone
 //   quiet, filing an issue and applying `auto-ok`. Ten minutes does not reliably outlast that.
 // - **Above it the run pays for nothing.** At `IDLE_POLL_MINUTES` a 30-minute watch is six asks —
 //   about one child's worth of turns, spent while the run holds no working tree and no lane.
-// - **It is about the length of one child** — 12 to 28 minutes measured on joshuafolkken/kit#1477 —
-//   so a run that has emptied its backlog waits roughly as long as one more issue would have taken.
+// - **It is about the length of one child** — 12 to 28 minutes measured — so a run that has emptied its backlog waits roughly as long as one more issue would have taken.
 const DEFAULT_IDLE_MINUTES = 30
 const DEFAULT_IDLE_MS = DEFAULT_IDLE_MINUTES * MS_PER_MINUTE
 
@@ -51,10 +45,10 @@ const TRIAGE_VERDICT = 'triage'
 
 // `run` — start what `backlog:next` offered. `watch` — sleep the polling interval and ask again,
 // except while something of the run's own is in flight, where the wake is the progress watcher's exit
-// and the interval is only a floor (`backlogrun.md` → "The wake exists only while something is in
-// flight").
+// and the interval is only a floor (`docs/maintainers/backlogrun-driver.md` → "Waiting while
+// something is in flight").
 // `stop` — report and finish. `triage` — judge the untriaged issues `backlog:next` named, then ask
-// again (joshuafolkken/kit#2779); it is the parent's to act on, so `backlog:drive` hands it back.
+// again; it is the parent's to act on, so `backlog:drive` hands it back.
 type BudgetVerdict =
 	typeof RUN_VERDICT | typeof WATCH_VERDICT | typeof STOP_VERDICT | typeof TRIAGE_VERDICT
 
@@ -141,8 +135,7 @@ function idle_watch_reason(left_ms: number): string {
 	return `The backlog is empty and the idle watch has about ${to_minutes(left_ms)} minutes left. Release the working tree, ask again in ${next_ask_minutes(left_ms)} minutes, and restart the watch the moment a candidate appears.`
 }
 
-// **A watch that opens while children are still in lanes is not the idle watch's ordinary shape**, and
-// it became reachable the moment the watch was turned on by default (joshuafolkken/kit#1676): the
+// **A watch that opens while children are still in lanes is not the idle watch's ordinary shape**: the
 // backlog can answer `exhausted` while this run's own children are still merging. Two things the
 // sentence above would get wrong there — the working tree is still held, because the hold is released
 // at the *last* child's merge, and a five-minute poll would leave a merge unnoticed for five minutes.
@@ -237,7 +230,7 @@ function idle_decision(input: BudgetInput): BudgetDecision {
 // Whether a `stop` for this input is the run finishing — the idle watch ending on an empty backlog —
 // rather than stopping on something a person must act on: a parked backlog, an unreadable listing, the
 // maximum or the whole-run bound. The two end the carry record differently (`--end` against
-// `--end --stopped`), and `backlog:drive` reads which one from here (joshuafolkken/kit#2508).
+// `--end --stopped`), and `backlog:drive` reads which one from here.
 function is_finish(input: BudgetInput): boolean {
 	return stop_reason(input) === undefined && max_decision(input) === undefined
 }