@joshuafolkken/kit 1.1379.0 → 1.1387.0

package/scripts/backlog/backlog-budget.ts

@@ -1,12 +1,17 @@
 // `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. Without
-// this a run would finish the moment the backlog read empty, so an issue a person opted in minutes
+// this a run would finish the moment nothing could proceed, 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.** 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.
+// watches for `IDLE_WAIT_HOURS` once nothing can proceed before it finishes, and takes as many issues
+// as the backlog holds. `--idle 0` is how the watch is turned off.
+//
+// **Every reason nothing can proceed is watched, not only an empty backlog.** Everything opted in
+// waiting on a person, and a listing that could not be read, both change without this run doing
+// anything — a person opts the prerequisite in, GitHub answers again — so ending on either would miss
+// the issue opted in minutes later, which is the one thing the watch exists to catch.
 //
 // 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
@@ -14,29 +19,23 @@
 
 const MS_PER_MINUTE = 60_000
 const MINUTES_PER_HOUR = 60
-// 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.**
-//
-// - **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 — so a run that has emptied its backlog waits roughly as long as one more issue would have taken.
-const DEFAULT_IDLE_MINUTES = 30
+// **How long a run with nothing to do waits, and the only time bound a run has.** It is counted from
+// when the run last had work, never from its start: a run still working, or still inside this wait,
+// is not ended by its age. Eight hours is one unattended night — a person who opts an issue in before
+// they sleep, or after they wake, finds the run still there to pick it up.
+const IDLE_WAIT_HOURS = 8
+const DEFAULT_IDLE_MINUTES = IDLE_WAIT_HOURS * MINUTES_PER_HOUR
 const DEFAULT_IDLE_MS = DEFAULT_IDLE_MINUTES * MS_PER_MINUTE
 
-// **What a watching run sleeps between asks, and it is not the loop's 60-second polling interval.**
-// That one is sized to a child's `fullrun`, which finishes in minutes; a watch is waiting on a person
-// to file an issue and opt it in, which happens on human timescales. Polling a watch every minute
-// would spend thirty of the parent session's own requests — each one billing the whole session
-// history — to learn nothing thirty times. `backlogrun-progress.md` → "Waiting, and never waiting forever" holds
+// **The one interval between two asks for work, whether lanes are running or nothing is.** The driver
+// and the wake supervisor both read it from here. The loop is a process, so an ask spends no AI turn,
+// and a watch is polled as often as a running batch; a child collected in between is asked about at
+// once, without waiting it out. `backlogrun-progress.md` → "Waiting, and never waiting forever" holds
 // the row; the figure is here because `idle_watch_reason` below has to say it.
-const IDLE_POLL_MINUTES = 5
+const OFFER_INTERVAL_SECONDS = 60
+const MS_PER_SECOND = 1000
+const OFFER_INTERVAL_MS = OFFER_INTERVAL_SECONDS * MS_PER_SECOND
 
 const RUN_VERDICT = 'run'
 const WATCH_VERDICT = 'watch'
@@ -69,7 +68,7 @@ interface BudgetInput {
 	// otherwise be measured against a maximum that cannot see it.
 	running: number
 	started_at_ms: number
-	// When this run last had work — the most recent ask that was not `exhausted`, or the run's start.
+	// When this run last had work — its most recent launch or collected child, or the run's start.
 	// Refreshing it is what restarts the idle watch when a candidate appears during one.
 	active_at_ms: number
 	now_ms: number
@@ -87,22 +86,28 @@ interface BudgetDecision {
 	reason: string
 }
 
-const WHOLE_RUN_REASON = `The whole-run bound of ${String(WHOLE_RUN_BUDGET_HOURS)} hours has passed. An unattended run that has not finished overnight needs a person, not more waiting.`
-
-const PARKED_REASON =
-	'Nothing opted in can proceed without a person. Report the parked issues and finish.'
-
-const UNREADABLE_REASON =
-	'The backlog listing could not be read, so nothing was offered. Report what the command printed and finish — it is not an empty backlog.'
-
 const BLOCKED_REASON =
 	'Everything opted in is blocked or already running, so waiting can still change the answer. Poll again at the polling interval.'
 
 const TRIAGE_REASON =
 	'An opted-in candidate carries neither `run:solo` nor `run:lane`, so nothing starts until it is judged. Read each issue named above, record its order and one of the two labels with a comment, then ask again.'
 
-const NO_IDLE_WATCH_REASON =
-	'The backlog is empty and the idle watch was turned off with `--idle 0`, so the run finishes here.'
+// What the run is waiting on, by the answer that opened the watch — the opening of every sentence a
+// watch or its ending prints, so a person reads which of the three it was.
+const EMPTY_BACKLOG = 'The backlog is empty'
+const WAITING_ON: Readonly<Partial<Record<BacklogAnswer, string>>> = {
+	exhausted: EMPTY_BACKLOG,
+	parked: 'Nothing opted in can proceed without a person',
+	unreadable: 'The backlog listing could not be read',
+}
+
+function waiting_on(answer: BacklogAnswer): string {
+	return WAITING_ON[answer] ?? EMPTY_BACKLOG
+}
+
+function no_idle_watch_reason(answer: BacklogAnswer): string {
+	return `${waiting_on(answer)} and the idle watch was turned off with \`--idle 0\`, so the run finishes here.`
+}
 
 function to_minutes(duration_ms: number): string {
 	return String(Math.ceil(duration_ms / MS_PER_MINUTE))
@@ -119,39 +124,29 @@ function draining_reason(running: number, reason: string): string {
 	return `Start nothing more and poll until the running children merge (running: ${String(running)}). Then report and finish — ${reason}`
 }
 
-function idle_expired_reason(idle_budget_ms: number): string {
-	return `The backlog stayed empty for the whole ${to_minutes(idle_budget_ms)}-minute idle watch. Report what was done, including how many were picked up during the watch, and finish.`
-}
-
-// Never longer than the watch has left: "about 2 minutes left, ask again in 5 minutes" would overrun
-// the budget a person declared, and a sentence that contradicts itself is read as neither half.
-function next_ask_minutes(left_ms: number): string {
-	const left_minutes = Number(to_minutes(left_ms))
-
-	return String(Math.min(IDLE_POLL_MINUTES, left_minutes))
+function idle_expired_reason(answer: BacklogAnswer, idle_budget_ms: number): string {
+	return `${waiting_on(answer)}, and stayed so for the whole ${to_minutes(idle_budget_ms)}-minute idle watch. Report what was done, including how many were picked up during the watch, and finish.`
 }
 
-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.`
+function idle_watch_reason(answer: BacklogAnswer, left_ms: number): string {
+	return `${waiting_on(answer)} and the idle watch has about ${to_minutes(left_ms)} minutes left. Release the working tree, ask again in ${String(OFFER_INTERVAL_SECONDS)} seconds, 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**: 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.
+// backlog can offer nothing while this run's own children are still merging. The sentence above
+// would get one thing wrong there — the working tree is still held, because the hold is released at
+// the *last* child's merge.
 //
-// **The watch runs down while they drain, and the sentence does not promise otherwise.** Pausing it
-// would mean moving `active_at` on an ask that answered `exhausted`, which is the one thing that
-// moment is defined not to do — so a drain longer than the budget ends the run at the drain. That is
-// the honest ending: the backlog was empty at every ask, which is exactly what the watch measures.
-function running_watch_reason(running: number, left_ms: number): string {
-	return `The backlog is empty and the idle watch has about ${to_minutes(left_ms)} minutes left, with ${String(running)} still running. Keep the working tree until they merge and poll at the polling interval, not the idle poll — the watch is running down meanwhile.`
+// **The watch runs down while they drain, and restarts at each one collected.** A collected child is
+// work, so it moves `active_at`; an ask that offered nothing never does.
+function running_watch_reason(answer: BacklogAnswer, running: number, left_ms: number): string {
+	return `${waiting_on(answer)} and the idle watch has about ${to_minutes(left_ms)} minutes left, with ${String(running)} still running. Keep the working tree until they merge and poll at the polling interval — the watch is running down meanwhile.`
 }
 
 function watching_reason(input: BudgetInput, left_ms: number): string {
-	if (input.running === 0) return idle_watch_reason(left_ms)
+	if (input.running === 0) return idle_watch_reason(input.answer, left_ms)
 
-	return running_watch_reason(input.running, left_ms)
+	return running_watch_reason(input.answer, input.running, left_ms)
 }
 
 // What the maximum has already taken: merged issues and the children still running. Counting only
@@ -169,32 +164,10 @@ function run_reason(input: BudgetInput): string {
 	return `Start at most ${String(max_issues - taken_by(input))} more: this run's maximum is ${String(max_issues)}, with ${String(input.merged)} merged and ${String(input.running)} running.`
 }
 
-// The two answers that end a run whatever the budgets say. Neither is a budget decision — the graph
-// said so — but both reach this command, because the loop asks one question rather than branching on
-// `backlog:next`'s word itself and then asking a second.
-const ANSWER_STOP_REASONS: Readonly<Partial<Record<BacklogAnswer, string>>> = {
-	parked: PARKED_REASON,
-	unreadable: UNREADABLE_REASON,
-}
-
-function whole_run_reason(input: BudgetInput): string | undefined {
-	if (input.now_ms - input.started_at_ms < WHOLE_RUN_BUDGET_MS) return undefined
-
-	return WHOLE_RUN_REASON
-}
-
-// The answer-level stops come first, ahead of every budget. Both of them say something the person
-// has to act on — issues are parked, or the listing could not be read — and the reason printed here
-// is quoted verbatim into the completion report, so a budget reason in front of one would report a
-// tidy ending for a run whose backlog actually broke.
-function stop_reason(input: BudgetInput): string | undefined {
-	return ANSWER_STOP_REASONS[input.answer] ?? whole_run_reason(input)
-}
-
 // Every ending goes through here, so no ending abandons a lane. Children already started have to
-// merge and be reported whatever ended the run — the maximum, a parked backlog, a listing that could
-// not be read, or the whole-run bound — so a `stop` while any of them is still running would leave
-// open lanes behind and merged work unmentioned.
+// merge and be reported whatever ended the run — the maximum, or a watch that ran out or was turned
+// off — so a `stop` while any of them is still running would leave open lanes behind and merged work
+// unmentioned.
 function stopping(input: BudgetInput, reason: string): BudgetDecision {
 	if (input.running === 0) return { verdict: STOP_VERDICT, reason }
 
@@ -212,30 +185,31 @@ function max_decision(input: BudgetInput): BudgetDecision | undefined {
 	return stopping(input, max_reached_reason(input.merged, max_issues))
 }
 
-// An empty backlog is watched rather than acted on, which is now the default — and the watch lives
-// *inside* the whole-run bound, which `stop_reason` has already applied above. Only `--idle 0` takes
-// the other branch, where an empty backlog is the run's ending.
+// Nothing can proceed, so the run watches rather than ends — whichever of the three answers said so.
+// The watch is the run's only time bound: it is counted from `active_at_ms`, so a run is never ended
+// by how long ago it started. Only `--idle 0` takes the other branch, where the first such answer is
+// the run's ending.
 function idle_decision(input: BudgetInput): BudgetDecision {
 	const { idle_budget_ms } = input
 
-	if (idle_budget_ms === undefined) return stopping(input, NO_IDLE_WATCH_REASON)
+	if (idle_budget_ms === undefined) return stopping(input, no_idle_watch_reason(input.answer))
 
 	const left_ms = idle_budget_ms - (input.now_ms - input.active_at_ms)
 
-	if (left_ms <= 0) return stopping(input, idle_expired_reason(idle_budget_ms))
+	if (left_ms > 0) return { verdict: WATCH_VERDICT, reason: watching_reason(input, left_ms) }
 
-	return { verdict: WATCH_VERDICT, reason: watching_reason(input, left_ms) }
+	return stopping(input, idle_expired_reason(input.answer, idle_budget_ms))
 }
 
-// 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.
+// Whether a `stop` for this input is the run finishing — the watch ending on an empty backlog —
+// rather than stopping on something a person must act on: the maximum, issues still waiting on a
+// person, or a listing that never became readable. The two end the carry record differently (`--end`
+// against `--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
+	return input.answer === 'exhausted' && max_decision(input) === undefined
 }
 
-// The answers whose decision no count changes, once the bounds above have been applied.
+// The answers whose decision no count changes, once the maximum above has been applied.
 const FIXED_DECISIONS: Readonly<Partial<Record<BacklogAnswer, BudgetDecision>>> = {
 	blocked: { verdict: WATCH_VERDICT, reason: BLOCKED_REASON },
 	untriaged: { verdict: TRIAGE_VERDICT, reason: TRIAGE_REASON },
@@ -248,15 +222,7 @@ function answer_decision(input: BudgetInput): BudgetDecision {
 }
 
 function decide(input: BudgetInput): BudgetDecision {
-	const reason = stop_reason(input)
-
-	if (reason !== undefined) return stopping(input, reason)
-
-	const capped = max_decision(input)
-
-	if (capped !== undefined) return capped
-
-	return answer_decision(input)
+	return max_decision(input) ?? answer_decision(input)
 }
 
 const backlog_budget = {
@@ -264,25 +230,22 @@ const backlog_budget = {
 	BLOCKED_REASON,
 	DEFAULT_IDLE_MINUTES,
 	DEFAULT_IDLE_MS,
-	IDLE_POLL_MINUTES,
+	IDLE_WAIT_HOURS,
 	MS_PER_MINUTE,
-	NO_IDLE_WATCH_REASON,
-	PARKED_REASON,
+	OFFER_INTERVAL_MS,
 	RUN_VERDICT,
 	STOP_VERDICT,
 	TRIAGE_REASON,
 	TRIAGE_VERDICT,
-	UNREADABLE_REASON,
+	WAITING_ON,
 	WATCH_VERDICT,
-	WHOLE_RUN_BUDGET_HOURS,
-	WHOLE_RUN_BUDGET_MS,
-	WHOLE_RUN_REASON,
 	decide,
 	draining_reason,
 	idle_expired_reason,
 	idle_watch_reason,
 	is_finish,
 	max_reached_reason,
+	no_idle_watch_reason,
 	run_reason,
 	running_watch_reason,
 	taken_by,

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

@@ -13,10 +13,12 @@ import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_merge_cli, type MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { z } from 'zod'
+import { backlog_budget } from './backlog-budget'
 import {
 	backlog_drive,
 	type DriveEnd,
 	type DriveState,
+	type LoopConfig,
 	type LoopPorts,
 	type OfferRead,
 } from './backlog-drive'
@@ -46,7 +48,6 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const should_forward_stderr = true
 const POLL_MS = 5000
-const OFFER_MS = 60_000
 const FIRST_LINE = 0
 
 // The `--json` object `backlog:offer` prints, keyed under its `JSON_KEY`.
@@ -71,17 +72,14 @@ async function read_record(): Promise<RunCarry | undefined> {
 
 	const read = run_carry.read_carry(run_carry.carry_path(target))
 
-	return read.kind === 'carried' || read.kind === 'expired' ? read.carry : undefined
+	return read.kind === 'carried' ? read.carry : undefined
 }
 
 async function read_offer(
 	state: DriveState,
 	context: DriveContext,
 ): Promise<OfferRead | undefined> {
-	await backlog_drive_owner.assert_current(context.owner)
-	const carry = await read_record()
-
-	if (carry === undefined) return undefined
+	const carry = await backlog_drive_owner.assert_current(context.owner)
 	const named = await backlog_drive_named_offer.read(carry, state, context)
 	if (named !== undefined) return named
 
@@ -204,6 +202,11 @@ async function seeded_lanes(context: DriveContext): Promise<ReadonlyArray<string
 	return backlog_drive_restore.restore(lanes, events, carry.merged_issues ?? [])
 }
 
+// The interval between two asks is `backlog:budget`'s own, so the driver keeps the one its reason prints.
+function loop_config(window_ms: number | undefined): LoopConfig {
+	return { poll_ms: POLL_MS, offer_ms: backlog_budget.OFFER_INTERVAL_MS, window_ms }
+}
+
 async function drive(context: DriveContext): Promise<number> {
 	const seeded = await seeded_lanes(context)
 
@@ -212,7 +215,7 @@ async function drive(context: DriveContext): Promise<number> {
 	const initial =
 		context.stopped === undefined ? fresh : backlog_drive.merge_stopped(context.stopped, fresh)
 	const last = { state: { ...initial, exclude: [...context.exclude] } }
-	const config = { poll_ms: POLL_MS, offer_ms: OFFER_MS, window_ms: context.window_ms }
+	const config = loop_config(context.window_ms)
 	const end = await backlog_drive.run_loop(last.state, config, ports_of(context, seeded, last))
 
 	console.info(end_line(end))
@@ -258,10 +261,12 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const backlog_drive_cli = {
 	end_line,
 	finish: backlog_drive_finish.finish,
+	loop_config,
 	merge,
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse: backlog_drive_args.parse,
+	read_offer,
 	resume_line: backlog_drive_args.resume_line,
 	run,
 	to_offer,

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

@@ -1,5 +1,6 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { backlog_drive_owner } from './backlog-drive-owner'
 
 // The driver's lane launch. The parent that ran `josh latest` in the primary
@@ -28,6 +29,7 @@ async function latest_stash(): Promise<string | undefined> {
 
 async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
 	await backlog_drive_owner.assert_current(owner)
+	await run_event_setup.emit(run_event_setup.opening_lane(issue))
 
 	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
 

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

@@ -1,4 +1,18 @@
-import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { existsSync } from 'node:fs'
+import { poll } from '#scripts/lib/poll'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
+import { backlog_budget } from './backlog-budget'
+
+// **A record that does not read is asked again before the driver gives up on it.** The driver is the
+// only thing looking for work during the idle watch, so ending on one failed read throws away whatever
+// is left of the watch. The read is repeated at the offer's own interval, and
+// the count bounds it: a record that stays unreadable still ends the driver, with the reason said.
+const READ_ATTEMPTS = 6
+const ENDED_MESSAGE = 'The carry record is no longer active.'
+
+// The run this driver last read, so a record that is gone can be told from one `run:carry --end` ended.
+const seen: { started_at?: string } = {}
 
 function owns_record(carry: RunCarry, owner: string): boolean {
 	const current = run_carry.owner_of(Number(owner))
@@ -7,16 +21,69 @@ function owns_record(carry: RunCarry, owner: string): boolean {
 	return has_owner && run_carry.is_owner_live(carry) && !carry.is_handed_off
 }
 
-async function assert_current(owner: string): Promise<void> {
+// `--end` records the run it removes, so an ended run answers at once rather than after the re-reads.
+function is_ended(directory: string): boolean {
+	return run_carry_ended.has_ended(run_carry_ended.ended_path(directory), seen.started_at)
+}
+
+// Whether the file is there is said beside the read, because `none` is the answer both to a record
+// that is gone and to one that is present and could not be opened.
+function unread_note(read: CarryRead, directory: string): string {
+	const presence = existsSync(run_carry.carry_path(directory)) ? 'present' : 'absent'
+
+	return `The carry record read \`${read.kind}\` with its file ${presence}`
+}
+
+function is_settled(read: CarryRead, directory: string): boolean {
+	if (read.kind === 'carried' || is_ended(directory)) return true
+
+	console.error(`${unread_note(read, directory)}; reading it again.`)
+
+	return false
+}
+
+async function read_record(directory: string): Promise<CarryRead> {
+	const target = run_carry.carry_path(directory)
+	let read: CarryRead = { kind: 'none' }
+
+	await poll.poll_until(
+		async () => {
+			read = run_carry.read_carry(target)
+
+			return is_settled(read, directory)
+		},
+		{
+			attempts: READ_ATTEMPTS,
+			interval_ms: backlog_budget.OFFER_INTERVAL_MS,
+			sleeper: async (duration_ms) => {
+				await poll.sleep(duration_ms)
+			},
+		},
+	)
+
+	return read
+}
+
+function unread_message(read: CarryRead, directory: string): string {
+	if (is_ended(directory)) return ENDED_MESSAGE
+
+	return `${unread_note(read, directory)}, ${String(READ_ATTEMPTS)} times in a row.`
+}
+
+async function assert_current(owner: string): Promise<RunCarry> {
 	const directory = await run_carry.repository_directory()
 	if (directory === undefined) throw new Error('The carry record cannot be located.')
 
-	const read = run_carry.read_carry(run_carry.carry_path(directory))
-	if (read.kind !== 'carried') throw new Error('The carry record is no longer active.')
+	const read = await read_record(directory)
+	if (read.kind !== 'carried') throw new Error(unread_message(read, directory))
 
 	if (!owns_record(read.carry, owner)) {
 		throw new Error('The driver no longer owns the carry record.')
 	}
+
+	seen.started_at = read.carry.started_at
+
+	return read.carry
 }
 
-export const backlog_drive_owner = { assert_current }
+export const backlog_drive_owner = { READ_ATTEMPTS, assert_current }

package/scripts/backlog/backlog-drive.ts

@@ -140,9 +140,12 @@ function ended(reason: string, state: DriveState, token?: string, issue?: string
 	}
 }
 
+// Only an empty backlog drains: `backlog:offer` marks the drain on `exhausted` alone, so a watch over a
+// parked or unreadable backlog has no retrospective for `run:step` to fire and stays the driver's.
 function is_drain(read: OfferRead, state: DriveState): boolean {
 	return (
 		read.verdict === WATCH_VERDICT &&
+		read.answer === 'exhausted' &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
 	)
@@ -352,8 +355,8 @@ async function run_pass(
 
 interface LoopConfig {
 	poll_ms: number
-	// The floor between two `backlog:offer` asks while nothing was collected — the same one-minute
-	// cadence the wake supervisor polls the backlog on, so an idle stretch is not a network hammer.
+	// The floor between two `backlog:offer` asks while nothing was collected, running or idle alike —
+	// `backlog_budget.OFFER_INTERVAL_MS`, the interval the wake supervisor polls on too.
 	offer_ms: number
 	// How long one invocation may wait before returning `window`, or `undefined` for no bound. A headless
 	// parent's foreground call is capped by its shell's timeout, so it passes one under that cap.

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

@@ -125,27 +125,19 @@ 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 {
 	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,
-	}
+	return { verdict: read[BUDGET_JSON_KEY], reason: read.reason, is_finish: read.is_finish }
 }
 
 function to_tokens(out: string): ReadonlyArray<string> {
@@ -225,12 +217,6 @@ 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)
 }
 

package/scripts/backlog/backlogrun-launch.ts

@@ -11,6 +11,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { run_headless } from '#scripts/run/run-headless'
 import { z } from 'zod'
 
@@ -34,10 +35,20 @@ const launch_schema = z.object({
 	pid: z.number(),
 	start: z.string().optional(),
 	session: z.string().optional(),
+	// What the parent was started to run and when, so `run:board` has a run to draw and a clock to count
+	// before the parent claims the carry record. Absent on a record an earlier version wrote.
+	invocation: z.string().optional(),
+	started_at: z.string().optional(),
 })
 
 type LaunchRecord = z.infer<typeof launch_schema>
 
+// A launched run the parent has not claimed yet, as far as its record says.
+interface PendingLaunch {
+	invocation: string
+	started_at: string
+}
+
 interface LaunchTarget {
 	// The checkout the parent runs in, and its common git directory the records are keyed on.
 	worktree: string
@@ -117,10 +128,48 @@ function note_to_stderr(note: string): void {
 	console.error(`backlogrun: ${note}`)
 }
 
-function record_launch(git_directory: string, pid: number, session: string | undefined): void {
-	const started = process_identity.read_start(pid)
+// **The record and the run's first stage carry one moment**, so the `starting session` event is never
+// dated before the start the board measures from.
+function record_launch(
+	git_directory: string,
+	launch: Pick<LaunchRecord, 'pid' | 'session' | 'invocation'>,
+): void {
+	const now = new Date()
+	const identity = process_identity.read_start(launch.pid)
+	const record: LaunchRecord = { ...launch, start: identity, started_at: now.toISOString() }
+
+	stamp_file.replace_stamp(launch_path(git_directory), record)
+	run_event_setup.emit_in(git_directory, run_event_setup.STAGE.STARTING, now)
+}
+
+// The live launch record here, `undefined` once the parent it names is gone.
+function live_launch(git_directory: string): LaunchRecord | undefined {
+	const record = read_launch(launch_path(git_directory))
+
+	return is_launch_live(record) ? record : undefined
+}
+
+// The launch `run:board` draws while no carry record stands: one whose record says what it runs and
+// since when.
+function pending_launch(git_directory: string): PendingLaunch | undefined {
+	const { invocation, started_at } = live_launch(git_directory) ?? {}
+
+	if (invocation === undefined || started_at === undefined) return undefined
+
+	return { invocation, started_at }
+}
+
+// When the launch that started `owner_pid` began, for `run:carry --begin` to start the run's clock
+// from: **only the parent this launch started inherits it**, so a run typed inside a session — which has
+// no launch record, or another parent's — still starts at its own `--begin`.
+function started_for(git_directory: string, owner_pid: number | undefined): Date | undefined {
+	const record = live_launch(git_directory)
+
+	if (record?.started_at === undefined || record.pid !== owner_pid) return undefined
+
+	const started_ms = Date.parse(record.started_at)
 
-	stamp_file.replace_stamp(launch_path(git_directory), { pid, start: started, session })
+	return Number.isNaN(started_ms) ? undefined : new Date(started_ms)
 }
 
 // The headless mark holds the parent's turn open while its lanes run, as `run:wake`'s does. The launch
@@ -160,7 +209,7 @@ function start(invocation: string, provider: AgentProvider, target: LaunchTarget
 
 	if (result.kind === 'failed') return result
 
-	record_launch(target.git_directory, result.pid, session)
+	record_launch(target.git_directory, { pid: result.pid, session, invocation })
 
 	const launched = { pid: result.pid, session, log_path: log_path(target.git_directory) }
 
@@ -171,8 +220,10 @@ const backlogrun_launch = {
 	argv_of,
 	chosen_environment,
 	is_running,
+	pending_launch,
 	start,
+	started_for,
 }
 
-export type { Launched, LaunchTarget, StartResult }
+export type { Launched, LaunchTarget, PendingLaunch, StartResult }
 export { backlogrun_launch }