@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/backlog/backlog-pool.ts

@@ -7,12 +7,7 @@ import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
 import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
-import {
-	ALREADY_DONE_LABEL,
-	EPIC_LABEL,
-	has_any_label,
-	NEEDS_DECISION_LABEL,
-} from '#scripts/issue/issue-labels'
+import { EPIC_LABEL, has_any_label, PARKED_LABELS } from '#scripts/issue/issue-labels'
 
 // The candidate pool `josh backlog:next` answers from.
 //
@@ -25,11 +20,12 @@ import {
 
 const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
 // The labels that put a withheld row in the "needs a person" bucket rather than the "waiting on
-// time" one. `already-done` belongs with `needs-decision` because no amount of waiting moves it: the
-// work is merged and the close is Tier C, so a person is the only thing that resolves it.
+// time" one are the park labels (`PARKED_LABELS`). `already-done` and `run:stalled` belong with
+// `needs-decision` because no amount of waiting moves them: the work is merged and the close is Tier C,
+// or a mechanical cause has to be fixed, so a person is the only thing that resolves it.
 // Read as `time`, it would be reported as something that resolves itself
-// and nobody would ever be told to close it.
-const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
+// and nobody would ever be told to act on it.
+const DECISION_LABELS: ReadonlySet<string> = PARKED_LABELS
 
 // What decides whether a standalone row is offered: the children an opted-in epic is going to offer
 // instead, the ones the caller has named as done, and the repository the rows belong to.
@@ -140,6 +136,9 @@ function settle_standalone(
 // `epic_issue.blocker_references_of` is the epic side's own resolution —
 // `repository_url` when the node names one, this repository only as the fallback an unqualified
 // relation has always meant — and it is reused rather than repeated.
+//
+// The body rides along as an epic child's does, so a declared start time (`issue-not-before.ts`)
+// reaches the classification and the board's waiting row for a standalone row too (#4014).
 function to_child(issue: OpenIssueData, repo: string): EpicChild {
 	return {
 		number: issue.number,
@@ -147,6 +146,7 @@ function to_child(issue: OpenIssueData, repo: string): EpicChild {
 		state: 'OPEN',
 		labels: (issue.labels ?? []).map((label) => label.name),
 		blocked_by: epic_issue.blocker_references_of(issue, repo),
+		body: issue.body,
 	}
 }
 

package/scripts/backlog/backlog-rank.ts

@@ -4,6 +4,7 @@ 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
@@ -82,15 +83,21 @@ 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 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 { 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)
 }
@@ -98,6 +105,7 @@ function select(input: OfferInput): SoloSelection {
 interface GateScope {
 	standalone: ReadonlySet<string>
 	declared: Declared
+	lanes?: LaneRecords
 }
 
 // `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.

package/scripts/backlog/backlog-ready.ts

@@ -1,11 +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_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.
@@ -18,28 +29,101 @@ interface ReadyReading {
 	free_lanes: number
 }
 
+// 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 {
 	free_lane_count: () => Promise<number>
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
-// The lanes in use: the open worktrees an interruption has not stranded. `josh lane:limit` prints it.
-async function live_lane_count(): Promise<number> {
-	return lane_registry.live_count(await lane_registry.list_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 }
 }
 
-// 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 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
+
+	const use = { occupied: occupancy.occupied.length, seated, unknown: occupancy.unknown }
+
+	return { ...occupancy, use }
+}
+
+async function lane_use(lanes?: ReadonlyArray<LaneInfo>): Promise<LaneUse> {
+	const room = await lane_room(lanes)
+
+	return room.use
+}
+
+function free_of(limit: number, use: LaneUse): number {
+	return lane_capacity.free_lanes(limit, use.occupied, use.seated)
+}
+
+// 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 lane_capacity.free_lanes(limit.limit, lane_registry.live_count(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> {
-	return lane_capacity.free_lanes(limit, await live_lane_count())
+	return free_of(limit, await lane_use())
 }
 
 // Free lanes right now: the limit less the live lanes. An unreadable limit reads as no free lane — the
@@ -48,9 +132,10 @@ async function free_under(limit: number): Promise<number> {
 //
 // **Occupancy is the local worktree count, not the dispatch budget's busy read.** `epic-lane-offer`
 // measures occupancy with `epic_busy.occupied_lanes`, a network read of in-progress issue labels; this
-// counts live worktrees instead, deliberately — it runs on the cheap-first path where the costly read
-// (`backlog:next`) is gated behind a free lane, so a network read here would defeat that design. The
-// two can diverge, but only toward over-counting live lanes → fewer free lanes, the safe direction.
+// counts the worktrees that hold a place instead (`backlog-occupied.ts`), deliberately — it runs on the
+// cheap-first path where the costly read (`backlog:next`) is gated behind a free lane, so a network
+// read here would defeat that design. The two can diverge, but only toward over-counting live lanes →
+// fewer free lanes, the safe direction.
 async function free_lane_count(): Promise<number> {
 	return (await free_lanes_beside(await lane_registry.list_lanes())) ?? NO_FREE
 }
@@ -58,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
@@ -74,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.
@@ -172,8 +288,11 @@ const backlog_ready = {
 	print_offer_hint,
 	free_lane_count,
 	free_lanes_beside,
-	live_lane_count,
+	count_in,
+	lane_room,
+	lane_use,
 	drive_free_lane_count,
+	drive_limit_room,
 	drains_pool,
 	print_ready_line,
 	read_ready,
@@ -182,4 +301,4 @@ const backlog_ready = {
 }
 
 export { backlog_ready }
-export type { ReadyPorts, ReadyReading }
+export type { LaneCount, LaneRoom, LaneUse, ReadyPorts, ReadyReading }

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

@@ -1,12 +1,14 @@
-import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
 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 +16,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 +70,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.record_offerable(is_offerable)
 }
 
 function ports_over(ready: ReadyPorts): DetectPorts {
@@ -66,26 +88,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 +156,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 +200,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 +210,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 }