@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/backlog/backlog-rank.ts

@@ -4,12 +4,14 @@ import { epic_rank } from '#scripts/epic/epic-rank'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
+import type { LaneRecords } from '#scripts/lane/lane-state'
 import { backlog_overlap, type Declared } from './backlog-overlap'
 
 // What the backlog offers, in the order it is decided: rank, then the
 // `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
 // plan's first wave is what the run starts into an idle repository rather than an order the run never
-// takes.
+// takes. Only the cap's width differs: `backlog:next` prints `DISPLAY_LIMIT` rows, a wave holds the
+// lane limit (`limit`).
 //
 // **The cap comes last.** Applied while the standalone half is classified, before the gate, it would
 // cut a `run:solo` issue ranked sixth or lower before the gate could see it — and offer the issues
@@ -28,37 +30,51 @@ function everything_in(result: EpicNextResult): ReadonlyArray<EpicChild> {
 // The ranking is `epic_rank.rank`, shared with a named epic's lanes.
 const { rank } = epic_rank
 
-// This repository's candidates re-ranked inside the result, so `backlog:plan` prints the order the
-// offer is decided in.
-function rank_result(result: EpicNextResult, repo: string): EpicNextResult {
+// This repository's candidates put in `order` inside the result; another repository's are left as
+// they came.
+function reorder_repo(
+	result: EpicNextResult,
+	repo: string,
+	order: (children: ReadonlyArray<EpicChild>) => ReadonlyArray<EpicChild>,
+): EpicNextResult {
 	if (result.verdict !== 'run') return result
 
-	const pool = everything_in(result)
-
 	return {
 		...result,
 		candidates: result.candidates.map((bundle) =>
-			bundle.repo === repo ? { ...bundle, children: rank(bundle.children, pool) } : bundle,
+			bundle.repo === repo ? { ...bundle, children: order(bundle.children) } : bundle,
 		),
 	}
 }
 
+// The rank `select` starts from; `offer_order` adds the yielded-first step for `backlog:plan`.
+function rank_result(result: EpicNextResult, repo: string): EpicNextResult {
+	const pool = everything_in(result)
+
+	return reorder_repo(result, repo, (children) => rank(children, pool))
+}
+
 // The standalone rows past the cap, in offer order.
 function overflow_of(
 	offered: ReadonlyArray<EpicChild>,
 	standalone: ReadonlySet<string>,
+	limit: number,
 ): ReadonlySet<string> {
 	const keys = offered.map((child) => epic_graph.key_of(child)).filter((key) => standalone.has(key))
 
-	return new Set(keys.slice(git_next_issues.DISPLAY_LIMIT))
+	return new Set(keys.slice(limit))
 }
 
 function is_in(child: EpicChild, keys: ReadonlySet<string>): boolean {
 	return keys.has(epic_graph.key_of(child))
 }
 
-function cap(selection: SoloSelection, standalone: ReadonlySet<string>): SoloSelection {
-	const overflow = overflow_of(selection.offered, standalone)
+function cap(
+	selection: SoloSelection,
+	standalone: ReadonlySet<string>,
+	limit: number,
+): SoloSelection {
+	const overflow = overflow_of(selection.offered, standalone, limit)
 
 	if (overflow.size === 0) return selection
 
@@ -82,22 +98,61 @@ interface OfferInput {
 	// The paths each issue declares; two candidates whose paths overlap are not offered together.
 	// Absent, nothing is separated.
 	declared?: Declared
+	// The issues' lane state records; a clash with a paused holder says so. Absent, none is named.
+	lanes?: LaneRecords
+	// The keys of the issues that gave their lane back (`lane-yield.ts`). Absent, none did.
+	yielded?: ReadonlySet<string>
+	// How many standalone rows the cap keeps. Absent, `DISPLAY_LIMIT` — what `backlog:next` prints.
+	limit?: number
+}
+
+// A yielded issue ahead of the rank: its lane was taken from it, so it takes the first free one
+// once its holder ends rather than queueing behind the pool (joshuafolkken/kit#5107). While the
+// holder runs, its kept plan still withholds it in the separation. It goes ahead of a `run:solo`
+// issue too: the solo gate sees it first.
+function yielded_first(
+	ranked: ReadonlyArray<EpicChild>,
+	yielded: ReadonlySet<string>,
+): Array<EpicChild> {
+	return [
+		...ranked.filter((child) => is_in(child, yielded)),
+		...ranked.filter((child) => !is_in(child, yielded)),
+	]
+}
+
+// A ranked result in the order `select` walks it — a yielded issue ahead of the rank — so
+// `backlog:plan`'s "Ready now" reads in the order each wave is offered in (joshuafolkken/kit#5299).
+function offer_order(
+	result: EpicNextResult,
+	repo: string,
+	yielded: ReadonlySet<string> = new Set(),
+): EpicNextResult {
+	return reorder_repo(result, repo, (children) => yielded_first(children, yielded))
 }
 
 // The overlap separation runs before the cap, for the reason the gate does: the cap only ever
 // removes what would otherwise be offered.
 function select(input: OfferInput): SoloSelection {
-	const ranked = rank(input.candidates, input.pool)
-	const { read, repo } = input
+	const ranked = yielded_first(rank(input.candidates, input.pool), input.yielded ?? new Set())
+	const { read, repo, lanes } = input
 	const gated = epic_solo.select(ranked, read, repo)
-	const separated = backlog_overlap.separate(gated, input.declared ?? new Map(), { read, repo })
+	const separated = backlog_overlap.separate(gated, input.declared ?? new Map(), {
+		read,
+		repo,
+		lanes,
+	})
 
-	return cap(separated, input.standalone)
+	return cap(separated, input.standalone, input.limit ?? git_next_issues.DISPLAY_LIMIT)
 }
 
 interface GateScope {
 	standalone: ReadonlySet<string>
 	declared: Declared
+	lanes?: LaneRecords
+	yielded?: ReadonlySet<string>
+	// How many standalone rows a planned wave holds — the lane limit; `backlog:next`'s offer ignores
+	// it. Absent, a wave is not capped (joshuafolkken/kit#5300).
+	wave_limit?: number | undefined
 }
 
 // `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.
@@ -109,7 +164,7 @@ function gate(result: EpicNextResult, read: BusyRead, repo: string, scope: GateS
 	)
 }
 
-const backlog_rank = { everything_in, gate, rank_result, select }
+const backlog_rank = { everything_in, gate, offer_order, rank_result, select }
 
 export { backlog_rank }
 export type { GateScope, OfferInput }

package/scripts/backlog/backlog-ready.ts

@@ -1,14 +1,22 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import type { JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { lane_process_table, type TableRead } from '#scripts/lane/lane-process-table'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_snapshot_trace } from '#scripts/lane/lane-snapshot-trace'
 import { lane_spent } from '#scripts/lane/lane-spent'
+import { lane_state } from '#scripts/lane/lane-state'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+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 { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
-import { backlog_occupied, type OccupiedRead } from './backlog-occupied'
+import { backlog_drive_restore } from './backlog-drive-restore'
+import { backlog_next_shared } from './backlog-next-shared'
+import { backlog_occupied } from './backlog-occupied'
+import { backlog_offer_exclude } from './backlog-offer-exclude'
 import { backlog_stalled } from './backlog-stalled'
 
 // The ready line reports runnable work to the driving backlogrun parent on a watcher wake.
@@ -21,10 +29,27 @@ interface ReadyReading {
 	free_lanes: number
 }
 
-// How many open lanes hold a place under the limit, and how many hold a port seat.
+// How many open lanes hold a place under the limit, how many hold a port seat, and the ones with no
+// lane state record.
 interface LaneUse {
 	occupied: number
 	seated: number
+	unknown: ReadonlyArray<string>
+}
+
+// The lanes that hold a place under the limit, read once for every count drawn from them.
+interface LaneRoom {
+	occupied: ReadonlyArray<LaneInfo>
+	// The open lanes no child is working in, read from the same snapshot.
+	idle: ReadonlyArray<string>
+	// The open lanes with no lane state record, counted as holding a place until one is written.
+	unknown: ReadonlyArray<string>
+	use: LaneUse
+}
+
+interface LaneCount {
+	limit: number
+	free: number
 }
 
 interface ReadyPorts {
@@ -32,45 +57,69 @@ interface ReadyPorts {
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
-// What decides which open lanes hold a place, read from this checkout's live run.
-async function occupied_read(): Promise<OccupiedRead> {
-	const carry = await run_headless.current_carry()
-
-	return {
-		invocation: carry?.invocation,
-		events: carry === undefined ? [] : await run_event_stream_emit.scoped_current_events(),
-		idle: lane_spent.idle_lanes,
-	}
+// The lanes that hold a place under the limit (`backlog-occupied.ts`), the idle ones and the unknown
+// ones. Paused is each lane's state record's answer; every lane's idle reading is drawn from one
+// asynchronous process snapshot, so the count never blocks its caller's event loop
+// (joshuafolkken/kit#4241, #4245); `run:board` passes the snapshot its redraw already read (#4246).
+async function occupancy_of(
+	open: ReadonlyArray<LaneInfo>,
+	table: TableRead,
+): Promise<Omit<LaneRoom, 'use'>> {
+	const rows = await table()
+	const issues = open.map((lane) => lane.issue)
+	const trace = { process_trace: await lane_snapshot_trace.traces_of(issues, rows) }
+	const records = await lane_state.read_states(issues)
+	const is_merge_waiting = await lane_snapshot_trace.merge_waits_of(issues, rows)
+	const occupied = backlog_occupied.occupied_lanes(
+		open,
+		(live) => lane_spent.idle_lanes(live, trace),
+		records,
+		is_merge_waiting,
+	)
+	const unknown = backlog_occupied.unknown_lanes(open, records)
+
+	return { occupied, idle: lane_spent.idle_lanes(open, trace), unknown }
 }
 
-// The lanes that hold a place under the limit (`backlog-occupied.ts`).
-async function occupied_lanes(lanes?: ReadonlyArray<LaneInfo>): Promise<Array<LaneInfo>> {
+// The open lanes as the free count reads them: those that hold a place under the limit, and every
+// open one, since an uncounted lane still holds its port seat.
+async function lane_room(
+	lanes?: ReadonlyArray<LaneInfo>,
+	table: TableRead = lane_process_table.read_table,
+): Promise<LaneRoom> {
 	const open = lanes ?? (await lane_registry.list_lanes())
+	const occupancy = await occupancy_of(open, table)
+	const seated = open.filter((lane) => !lane.is_stranded).length
 
-	return backlog_occupied.occupied_lanes(open, await occupied_read())
+	const use = { occupied: occupancy.occupied.length, seated, unknown: occupancy.unknown }
+
+	return { ...occupancy, use }
 }
 
-// The open lanes as the free count reads them: those that hold a place under the limit, and every
-// open one, since an uncounted lane still holds its port seat.
 async function lane_use(lanes?: ReadonlyArray<LaneInfo>): Promise<LaneUse> {
-	const open = lanes ?? (await lane_registry.list_lanes())
-	const occupied = await occupied_lanes(open)
+	const room = await lane_room(lanes)
 
-	return { occupied: occupied.length, seated: open.filter((lane) => !lane.is_stranded).length }
+	return room.use
 }
 
 function free_of(limit: number, use: LaneUse): number {
 	return lane_capacity.free_lanes(limit, use.occupied, use.seated)
 }
 
-// Free lanes beside `lanes`, `undefined` where the limit could not be read: the count `lane:limit`
-// prints, and the one `run:board` draws, so the two never answer apart.
-async function free_lanes_beside(lanes: ReadonlyArray<LaneInfo>): Promise<number | undefined> {
+// The limit and the free lanes in `room`, `undefined` where the limit could not be read: the count
+// `lane:limit` prints, and the one `run:board` draws, so the two never answer apart.
+async function count_in(room: LaneRoom): Promise<LaneCount | undefined> {
 	const limit = await lane_capacity.lane_limit()
 
 	if (limit.kind !== 'limit') return undefined
 
-	return free_of(limit.limit, await lane_use(lanes))
+	return { limit: limit.limit, free: free_of(limit.limit, room.use) }
+}
+
+async function free_lanes_beside(lanes: ReadonlyArray<LaneInfo>): Promise<number | undefined> {
+	const count = await count_in(await lane_room(lanes))
+
+	return count?.free
 }
 
 async function free_under(limit: number): Promise<number> {
@@ -94,12 +143,24 @@ async function free_lane_count(): Promise<number> {
 // **The drive's count throws on an unreadable limit**. The drive launches no
 // more than this count, so the safe-direction zero above would leave it launching nothing and reporting
 // nothing for good; a bad setting is the hard error `lane_capacity` says it is, ending the drive loudly.
-async function drive_free_lane_count(): Promise<number> {
+async function drive_limit(): Promise<number> {
 	const limit = await lane_capacity.lane_limit()
 
 	if (limit.kind !== 'limit') throw new Error(limit.problem)
 
-	return await free_under(limit.limit)
+	return limit.limit
+}
+
+async function drive_free_lane_count(): Promise<number> {
+	return await free_under(await drive_limit())
+}
+
+// The drive's room under the limit alone, for resuming a kept lane, which already holds its port seat.
+async function drive_limit_room(): Promise<number> {
+	const limit = await drive_limit()
+	const use = await lane_use()
+
+	return lane_capacity.limit_room(limit, use.occupied)
 }
 
 // **A `--only` run has no pool to drain**. `backlog:next` lists the opted-in
@@ -110,13 +171,32 @@ function drains_pool(carry: RunCarry | undefined): boolean {
 	return carry === undefined || !run_invocation.has_only(carry.invocation)
 }
 
+// The offer's own exclusion, read off this run's stream: a merged child `backlog:next` still reads OPEN,
+// or one in flight, is no ready work (joshuafolkken/kit#4349). Scoped to this invocation, as the drive's
+// list is: the stream is the repository's log, so an earlier run's merge or unsettled launch would
+// otherwise hide a reopened issue for good.
+async function stream_exclude(carry: RunCarry | undefined): Promise<ReadonlyArray<string>> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined || carry === undefined) return []
+
+	const scope = run_event_scope.scope_of({ kind: 'carried', carry })
+	const events = run_event_scope.scoped_events(run_event_stream.read_events(target), scope) ?? []
+
+	return backlog_drive_restore.offer_exclude(events)
+}
+
 // The `backlog:next` read, or `undefined` for a `--only` run, which answers none before paying for the
 // network read. A bounded read keeps stderr piped: the arrival probe reads once
 // a minute, and a forwarded refusal would fill the watcher's output.
 async function read_backlog_next(timeout_ms?: number): Promise<JoshResult | undefined> {
-	if (!drains_pool(await run_headless.current_carry())) return undefined
+	const carry = await run_headless.current_carry()
+
+	if (!drains_pool(carry)) return undefined
+
+	const argv = ['backlog:next', ...backlog_offer_exclude.exclude_argv(await stream_exclude(carry))]
 
-	return await josh_command.josh_run(['backlog:next'], timeout_ms === undefined, timeout_ms)
+	return await backlog_next_shared.read(argv, timeout_ms === undefined, timeout_ms)
 }
 
 // The runnable issues for this checkout, read the way a loop reads them: `backlog:next`'s numeric lines.
@@ -208,9 +288,11 @@ const backlog_ready = {
 	print_offer_hint,
 	free_lane_count,
 	free_lanes_beside,
+	count_in,
+	lane_room,
 	lane_use,
-	occupied_lanes,
 	drive_free_lane_count,
+	drive_limit_room,
 	drains_pool,
 	print_ready_line,
 	read_ready,
@@ -219,4 +301,4 @@ const backlog_ready = {
 }
 
 export { backlog_ready }
-export type { LaneUse, ReadyPorts, ReadyReading }
+export type { LaneCount, LaneRoom, LaneUse, ReadyPorts, ReadyReading }

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

@@ -1,12 +1,15 @@
-import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
 import { backlog_stalled, type StallReading, type StallVerdict } from './backlog-stalled'
 
 // The I/O half of the stall detector: it gathers the three counts the pure
-// judge in `backlog-stalled.ts` weighs, then — on a stall — leaves the marker and sends the one
-// notification. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary; the CLI
+// judge in `backlog-stalled.ts` weighs, then — on a stall — leaves the marker `run:step` reads as
+// `backlog:next`. It sends no Telegram (joshuafolkken/kit#4015): a stall resolves itself at the next
+// dispatch, so the person it reached had nothing to do; the idle notification `backlog:drive` sends
+// when nothing is left to dispatch is the one that wants a hand. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary; the CLI
 // exposes the same call for a person to run by hand.
 //
 // **Cheap first.** The costly read is `backlog:next`, a subprocess that hits the network. The two local
@@ -14,26 +17,39 @@ import { backlog_stalled, type StallReading, type StallVerdict } from './backlog
 // is one `git worktree list`. Neither the lane count nor the backlog read is made unless the cheaper
 // condition ahead of it already holds, so an ordinary stop — a run not idle, or with no free lane —
 // costs a single file read and nothing more.
+//
+// **A stall is aged from when work and a lane first met** (joshuafolkken/kit#4349). Each probe records,
+// on the lane ledger, whether offerable work and a free lane coexist — only when that changes — and the
+// wait runs from the observation that opened the current episode. The dispatch age stays the cheap
+// gate: the wait can never exceed it.
 
 const NO_FREE = 0
 const NO_READY = 0
 const NO_AGE = 0
 
-// The recovery line names the command that resolves the stall — the same one `run:step` points a stalled
-// run at — so the person the notification reaches has the fix in hand.
-const STALL_RECOVERY = 'Dispatch the ready work with `pnpm josh backlog:next`.'
-
-// The seams a test replaces: the stream target and its events, the clock, the two counts, and the two
-// side effects. The defaults are the real readers; a test hands fakes so the gather and report logic run
-// without a git tree, a network or a wall clock.
+// The seams a test replaces: the stream target and its events, the clock, the two counts, the ledger,
+// and the marker. The defaults are the real readers; a test hands fakes so the gather and report logic
+// run without a git tree, a network or a wall clock.
 interface DetectPorts {
 	resolve_target: () => Promise<string | undefined>
 	read_events: (target: string) => ReadonlyArray<RunEvent>
 	now_ms: () => number
 	free_lane_count: () => Promise<number>
 	ready_count: () => Promise<number>
+	read_ledger: () => Promise<ReadonlyArray<LedgerEntry>>
+	mark_offerable: (is_offerable: boolean) => Promise<void>
 	emit_stall: (text: string) => Promise<boolean>
-	notify_stalled: (body: string) => Promise<boolean>
+}
+
+interface Counts {
+	ready_count: number
+	free_lanes: number
+}
+
+// The dispatch reference the episode is bounded by, and the probe's own time.
+interface Clock {
+	reference_ms: number
+	now_ms: number
 }
 
 // The free-lane and runnable-issue reads are `backlog-ready.ts`'s — the watcher's ready line reads the
@@ -55,8 +71,15 @@ async function real_emit_stall(text: string): Promise<boolean> {
 	return await run_event_stream_emit.emit_once_since(STALL, text, CHILD_LAUNCH)
 }
 
-async function real_notify_stalled(body: string): Promise<boolean> {
-	return await telegram_notify.stalled({ body, recovery: STALL_RECOVERY })
+// A test run has no ledger (`lane_ledger.target`), so it reads as empty there.
+async function read_real_ledger(): Promise<ReadonlyArray<LedgerEntry>> {
+	const path = await lane_ledger.target()
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+async function real_mark_offerable(is_offerable: boolean): Promise<void> {
+	await lane_ledger_write.record_offerable(is_offerable)
 }
 
 function ports_over(ready: ReadyPorts): DetectPorts {
@@ -66,26 +89,64 @@ function ports_over(ready: ReadyPorts): DetectPorts {
 		now_ms: () => Date.now(),
 		free_lane_count: ready.free_lane_count,
 		ready_count: ready_count_of(ready),
+		read_ledger: read_real_ledger,
+		mark_offerable: real_mark_offerable,
 		emit_stall: real_emit_stall,
-		notify_stalled: real_notify_stalled,
 	}
 }
 
 const DEFAULT_PORTS: DetectPorts = ports_over(backlog_ready.DEFAULT_PORTS)
 
-function ok_reading(dispatch_age_ms: number): StallReading {
-	return { ready_count: NO_READY, free_lanes: NO_FREE, dispatch_age_ms }
+function ok_reading(): StallReading {
+	return { ready_count: NO_READY, free_lanes: NO_FREE, waiting_ms: NO_AGE }
 }
 
-// The idle-and-past-threshold branch, where the costly reads finally happen: count the free lanes, and
-// only if one is free read the backlog. A full pool short-circuits before the network call — a stall
-// needs a lane to go into.
-async function probe_reading(ports: DetectPorts, dispatch_age_ms: number): Promise<StallReading> {
+// Count the free lanes, and only if one is free read the backlog. A full pool short-circuits before the
+// network call — a stall needs a lane to go into.
+async function read_counts(ports: DetectPorts): Promise<Counts> {
 	const free_lanes = await ports.free_lane_count()
 
-	if (free_lanes <= NO_FREE) return { ready_count: NO_READY, free_lanes, dispatch_age_ms }
+	if (free_lanes <= NO_FREE) return { ready_count: NO_READY, free_lanes }
+
+	return { ready_count: await ports.ready_count(), free_lanes }
+}
+
+function has_both(counts: Counts): boolean {
+	return counts.ready_count > NO_READY && counts.free_lanes > NO_FREE
+}
+
+// How long both have held: from the observation that opened the episode, or zero where this probe opens
+// or closes one — and records that change.
+async function waiting_ms(
+	ports: DetectPorts,
+	entries: ReadonlyArray<LedgerEntry>,
+	clock: Clock,
+	is_offerable: boolean,
+): Promise<number> {
+	const opened_ms = backlog_stalled.open_offerable_ms(entries, clock.reference_ms)
+
+	if (is_offerable === (opened_ms !== undefined)) return clock.now_ms - (opened_ms ?? clock.now_ms)
 
-	return { ready_count: await ports.ready_count(), free_lanes, dispatch_age_ms }
+	await ports.mark_offerable(is_offerable)
+
+	return NO_AGE
+}
+
+// The idle-and-past-threshold branch, where the costly reads finally happen.
+async function probe_reading(ports: DetectPorts, clock: Clock): Promise<StallReading> {
+	const counts = await read_counts(ports)
+	const entries = await ports.read_ledger()
+	const waited = await waiting_ms(ports, entries, clock, has_both(counts))
+
+	return { ...counts, waiting_ms: waited, hold: backlog_stalled.open_hold(entries) }
+}
+
+// The dispatch reference and the probe's time, or `undefined` when the stream has nothing to age against.
+function clock_of(ports: DetectPorts, target: string): Clock | undefined {
+	const now_ms = ports.now_ms()
+	const age = backlog_stalled.dispatch_age_ms(ports.read_events(target), now_ms)
+
+	return age === undefined ? undefined : { reference_ms: now_ms - age, now_ms }
 }
 
 // The reading that decides the verdict, assembled cheap-condition-first. `undefined` is the unreadable
@@ -96,25 +157,38 @@ async function gather(ports: DetectPorts, threshold_ms: number): Promise<StallRe
 
 	if (target === undefined) return undefined
 
-	const age = backlog_stalled.dispatch_age_ms(ports.read_events(target), ports.now_ms())
+	const clock = clock_of(ports, target)
 
-	if (age === undefined) return ok_reading(NO_AGE)
-	if (age <= threshold_ms) return ok_reading(age)
+	if (clock === undefined || clock.now_ms - clock.reference_ms <= threshold_ms) return ok_reading()
 
-	return await probe_reading(ports, age)
+	return await probe_reading(ports, clock)
 }
 
-// The marker and the notification, both once per stall episode. `emit_stall` refuses a second until a
-// dispatch has intervened, and its `false` is what holds the notification back too — so a stall
-// polled every stop reaches the person once, not once a turn.
-async function report(ports: DetectPorts, reading: StallReading): Promise<void> {
-	const text = backlog_stalled.describe(reading)
+// The watcher's once-a-minute arrival probe records the same observation from the reading it already
+// made, so an episode opens within a probe interval of work meeting a lane — not at the first stop past
+// the dispatch-age gate, which would hide up to one threshold of the wait. Best-effort, like the check.
+async function observe_offerable(
+	is_offerable: boolean,
+	ports: DetectPorts = DEFAULT_PORTS,
+): Promise<void> {
+	try {
+		const target = await ports.resolve_target()
+		const clock = target === undefined ? undefined : clock_of(ports, target)
 
-	if (await ports.emit_stall(text)) await ports.notify_stalled(text)
+		if (clock !== undefined) await waiting_ms(ports, await ports.read_ledger(), clock, is_offerable)
+	} catch {
+		// A failed observation is dropped: the next probe records it, and the watcher's loop must not break.
+	}
+}
+
+// The marker, once per stall episode: `emit_stall` refuses a second until a dispatch has intervened, so a
+// stall polled every stop lands on the stream once, not once a turn.
+async function report(ports: DetectPorts, reading: StallReading): Promise<void> {
+	await ports.emit_stall(backlog_stalled.describe(reading))
 }
 
-// Read the three conditions, print nothing, and on a stall leave the marker and notify. The verdict is
-// returned for the CLI to print; the side effects are the report's.
+// Read the three conditions, print nothing, and on a stall leave the marker. The verdict is returned for
+// the CLI to print; the side effect is the report's.
 async function detect_and_report(
 	ports: DetectPorts = DEFAULT_PORTS,
 	threshold_ms: number = backlog_stalled.STALL_THRESHOLD_MS,
@@ -127,7 +201,7 @@ async function detect_and_report(
 	return verdict
 }
 
-// Best-effort for the Stop hook: the detector is a report, so a failure to gather or notify is dropped
+// Best-effort for the Stop hook: the detector is a report, so a failure to gather or mark is dropped
 // rather than raised into the stop decision it rides alongside.
 async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS): Promise<void> {
 	try {
@@ -137,7 +211,7 @@ async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS):
 	}
 }
 
-const backlog_stalled_detect = { detect_and_report, run_stall_check }
+const backlog_stalled_detect = { detect_and_report, observe_offerable, run_stall_check }
 
 export { backlog_stalled_detect }
 export type { DetectPorts }