@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/run/event/run-event-stream-emit.ts

@@ -3,7 +3,7 @@ import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_event_scope } from './run-event-scope'
 import { run_event_stream, type RunEvent } from './run-event-stream'
 
-// The write side of the run's event stream (joshuafolkken/kit#2205). It resolves the run's identity and
+// The write side of the run's event stream. It resolves the run's identity and
 // appends, and it is where the "reporting must not break the work it reports on" contract is kept: every
 // failure — a git call that hangs, a temp directory that cannot be written — is swallowed, so a lane
 // child's own work never fails because an append did.
@@ -29,8 +29,7 @@ async function stream_target(): Promise<string | undefined> {
 
 /**
  * Append one session-facing event, best-effort. A kind outside the enumeration is refused by `append`;
- * every error is swallowed, because the reporting path must never fail the work it reports on
- * (joshuafolkken/kit#2205).
+ * every error is swallowed, because the reporting path must never fail the work it reports on.
  */
 async function emit(kind: string, text: string): Promise<void> {
 	try {
@@ -46,13 +45,13 @@ async function emit(kind: string, text: string): Promise<void> {
 
 /**
  * Append one event unless the newest event on the stream already carries this kind — so a marker a loop
- * re-checks every poll is written once per episode rather than once per poll (joshuafolkken/kit#2335).
+ * re-checks every poll is written once per episode rather than once per poll.
  * The drain marker is the caller: `backlog:offer` runs every iteration of a watching loop, and one drain
  * event per drain is what `run:step` reads to fire the retrospective a single time. Best-effort like
  * `emit`: a failed resolve or read is swallowed rather than raised into the loop's work.
  *
  * **Returns whether it appended**, so a caller that pairs the marker with its own once-per-episode side
- * effect — the stall detector sends one notification per stall (joshuafolkken/kit#2359) — fires that
+ * effect — the stall detector sends one notification per stall — fires that
  * effect exactly when the marker was fresh. A skipped duplicate and a swallowed failure both read
  * `false`: neither is a fresh episode.
  */
@@ -71,6 +70,30 @@ async function emit_once(kind: string, text: string): Promise<boolean> {
 	}
 }
 
+/**
+ * Append one event unless the newest event of this kind already carries this text — for a marker whose
+ * value, not its presence, is the news. The idle window is re-derived on every
+ * offer of a watching loop; only a window that moved is worth a line. Returns whether it appended.
+ */
+async function emit_changed(kind: string, text: string): Promise<boolean> {
+	try {
+		const target = await stream_target()
+
+		if (target === undefined) return false
+
+		const newest = run_event_stream.read_events(target).findLast((event) => event.kind === kind)
+
+		if (newest?.text === text) return false
+
+		return run_event_stream.append(target, kind, text, now_iso()).appended
+	} catch (error) {
+		// Best-effort: a failed append is dropped rather than raised into the loop's work.
+		error_text.trace_swallowed('run_event_stream_emit.emit_changed', error)
+
+		return false
+	}
+}
+
 // The events of the invocation now running: the stream outlives every invocation, so a marker a previous
 // run left — a stall that ended with no dispatch after it — must not hold back this run's first one. An
 // undetermined scope (no carry record) keeps the whole stream, the side that under-notifies rather than
@@ -84,9 +107,9 @@ function invocation_events(repository: string, target: string): ReadonlyArray<Ru
 
 /**
  * Append one event unless this kind is already on the stream since the newest `reset_kind` — the
- * episode marker for a condition that holds across other events (joshuafolkken/kit#2464). `emit_once`'s
- * newest-event test re-fired the stall notification each time a parallel lane appended a merge or a
- * park; this ends the episode only at `reset_kind`. Returns whether it appended, as `emit_once` does.
+ * episode marker for a condition that holds across other events. `emit_once`'s newest-event test would
+ * re-fire each time a parallel lane appended a merge or a park; this ends the episode only at
+ * `reset_kind`. Returns whether it appended, as `emit_once` does.
  */
 async function emit_once_since(kind: string, text: string, reset_kind: string): Promise<boolean> {
 	try {
@@ -109,14 +132,14 @@ async function emit_once_since(kind: string, text: string, reset_kind: string):
 	}
 }
 
-// One progress heartbeat line onto the stream, so a relay reaches it across a cut (joshuafolkken/kit#2437).
+// One progress heartbeat line onto the stream, so a relay reaches it across a cut.
 async function emit_heartbeat(line: string): Promise<void> {
 	await emit(run_event_stream.EVENT_KIND.HEARTBEAT, line)
 }
 
 // The events of the invocation now running, for a reader restoring the run from its stream
-// (`backlog:drive`, joshuafolkken/kit#2508). Fail-quiet like the writers: no repository or an unreadable
-// stream is an empty invocation.
+// (`backlog:drive`). Fail-quiet like the writers: no repository or an unreadable stream is an empty
+// invocation.
 async function current_events(): Promise<ReadonlyArray<RunEvent>> {
 	try {
 		const repository = await run_carry.repository_directory()
@@ -133,12 +156,42 @@ async function current_events(): Promise<ReadonlyArray<RunEvent>> {
 	}
 }
 
+// The invocation's events for a writer deciding whether a marker is already there: unlike
+// `current_events`, an undetermined scope keeps the whole stream, so a run with no carry record skips a
+// marker it already wrote rather than writing it twice.
+async function invocation_or_all_events(): Promise<ReadonlyArray<RunEvent>> {
+	try {
+		const repository = await run_carry.repository_directory()
+
+		return repository === undefined
+			? []
+			: invocation_events(repository, run_event_stream.target_of(repository))
+	} catch {
+		return []
+	}
+}
+
+// Every event on the stream, across invocations, for a reader that scopes by the event's own text
+// rather than by the carry record (`issue:file`'s fold). Fail-quiet like `current_events`.
+async function all_events(): Promise<ReadonlyArray<RunEvent>> {
+	try {
+		const target = await stream_target()
+
+		return target === undefined ? [] : run_event_stream.read_events(target)
+	} catch {
+		return []
+	}
+}
+
 const run_event_stream_emit = {
+	all_events,
 	current_events,
 	emit,
+	emit_changed,
 	emit_heartbeat,
 	emit_once,
 	emit_once_since,
+	invocation_or_all_events,
 	stream_target,
 }
 

package/scripts/run/event/run-event-stream.ts

@@ -1,9 +1,11 @@
+import { repository_lock } from '#scripts/git/repository-lock'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { z } from 'zod'
 
 // The run's append-only, ordered event stream — the surface a reader who was away rebuilds the run's
-// recent shape from (joshuafolkken/kit#2205). The report clock (`run-progress-clock.ts`) keeps only the
+// recent shape from. The report clock (`run-progress-clock.ts`) keeps only the
 // *last* heartbeat, and its `.log` sibling keeps only heartbeat *lines* with no position; neither lets
 // a woken reader ask "everything since the position I last read". This does.
 //
@@ -19,7 +21,7 @@ import { z } from 'zod'
 // dropped older events. Renumbering on compaction would silently shift a reader past unseen events.
 //
 // **The write is best-effort by contract, and the safety lives on the emit side.** The reporting path
-// must never fail the work it reports on (joshuafolkken/kit#2205), so `run-event-stream-emit.ts` wraps
+// must never fail the work it reports on, so `run-event-stream-emit.ts` wraps
 // every append in a swallow; this module is free to throw on a genuinely broken write.
 
 const EVENT_PREFIX = 'josh-run-events-'
@@ -29,14 +31,20 @@ const EVENT_PREFIX = 'josh-run-events-'
 const EVENT_SUFFIX = '.jsonl'
 // A run's session-facing events over the 8-hour whole-run bound: a plan, a launch/PR/review-round/merge
 // per child across a few dozen children, plus parks, cuts and stops. Five hundred keeps the whole of a
-// large `backlogrun` and still bounds an unattended run — past it the oldest events roll off, which is
-// what the acceptance criteria pin.
+// large `backlogrun` and still bounds an unattended run — past it the oldest events roll off.
 const EVENT_CAP = 500
 const FIRST_POSITION = 0
 const POSITION_INCREMENT = 1
 const LINE_SEPARATOR = '\n'
-
-// **The one enumeration of what a session-facing event is** (joshuafolkken/kit#2205). Every writer names
+const WORD_SEPARATOR = ' '
+// `#<N> <stage> <phase>` carries the phase third.
+const STAGE_PHASE_INDEX = 2
+// The lock sits beside the stream it guards, so every writer of one stream contends for one record.
+const LOCK_SUFFIX = '.lock'
+// An append holds the lock for one read and one rename; a wait this long means a holder is stuck.
+const LOCK_WAIT_MS = 5000
+
+// **The one enumeration of what a session-facing event is.** Every writer names
 // its event by one of these members rather than passing a free string, so the set of things the stream
 // carries is defined here and nowhere else; `append` refuses a kind outside it, which is what keeps a
 // caller from quietly widening the stream.
@@ -48,57 +56,79 @@ const EVENT_KIND = {
 	SPLIT: 'split',
 	OUTAGE: 'outage',
 	CUT: 'cut',
-	// A fresh session adopted an implementation cut — `run:cut --resume` answered `resume-impl`
-	// (joshuafolkken/kit#3375). The resume clears the cut record, so without this the `cut` stayed the
-	// newest position and `run:step` kept answering the resume command it had just run.
+	// A fresh session adopted an implementation cut — `run:cut --resume` answered `resume-impl`. The
+	// resume clears the cut record, so without this the `cut` would stay the newest position and
+	// `run:step` would keep answering the resume command it had just run.
 	RESUME: 'resume',
-	// The backlog emptied while nothing of the run's own was in flight — the drain
-	// (joshuafolkken/kit#2335). It marks the position at which the end-of-run retrospective is owed,
-	// *before* the idle watch opens, so `run:step` fires the retrospective at the drain rather than after
-	// the watch runs its course. It is not itself a stop: the run watches on once the retrospective has
-	// run, and the real `STOP` follows when the watch expires.
+	// The backlog emptied while nothing of the run's own was in flight — the drain. It marks the position
+	// at which the end-of-run retrospective is owed, *before* the idle watch opens, so `run:step` fires
+	// the retrospective at the drain rather than after the watch runs its course. It is not itself a
+	// stop: the run watches on once the retrospective has run, and the real `STOP` follows when the watch
+	// expires.
 	DRAIN: 'drain',
 	STOP: 'stop',
 	PR_OPENED: 'pr-opened',
 	REVIEW_ROUND: 'review-round',
-	// The end-of-run retrospective's result, recorded when the run marks the retrospective done
-	// (joshuafolkken/kit#2342). A retrospective that files zero improvements and one that never ran look
+	// The end-of-run retrospective's result, recorded when the run marks the retrospective done. A
+	// retrospective that files zero improvements and one that never ran look
 	// the same from outside — no new Issue either way — so the result is put on the stream the report is
 	// generated from: the issues filed (or that none were), and the candidates dropped with why. It is
 	// emitted from the `run:carry --retrospective` close, so marking the retrospective done and recording
 	// what it found are one action rather than two the run could do only one of.
 	RETROSPECTIVE: 'retrospective',
 	// Ready backlog work is sitting undispatched while a lane is free and nothing has dispatched for a
-	// while (joshuafolkken/kit#2359). Emitted once per stall episode by the stop-time detector, it is
-	// both the dedup marker — `emit_once_since` refuses a second until a `CHILD_LAUNCH` intervenes
-	// (joshuafolkken/kit#2464) — and the line a
-	// terminal reader following the stream sees. `run:step` reads it as `backlog:next`, so a run that
+	// while. Emitted once per stall episode by the stop-time detector, it is both the dedup marker —
+	// `emit_once_since` refuses a second until a `CHILD_LAUNCH` intervenes — and the line a terminal
+	// reader following the stream sees. `run:step` reads it as `backlog:next`, so a run that
 	// stalled is pointed straight at dispatching the work rather than left waiting.
 	STALL: 'stall',
 	// The run's own driver is gone: the cut handed the budget off, the owner has died, and no supervisor
-	// is watching (joshuafolkken/kit#2375). Emitted once per strand episode by the stop-time detector,
+	// is watching. Emitted once per strand episode by the stop-time detector,
 	// exactly as `STALL` is — the newest-event dedup keeps a run polled every stop from notifying more
 	// than once, and a terminal reader following the stream sees the line. The strand is the step before
 	// the stall: a stalled run still has a driver that could dispatch, a stranded one has none.
 	STRANDED: 'stranded',
-	// One `josh ship` stage starting, succeeding or failing (joshuafolkken/kit#2426). It is a trace of the
+	// One `josh ship` stage starting, succeeding or failing. It is a trace of the
 	// composite's progress rather than a position the run is at — the positions a ship leaves behind are
 	// the closed issue its `followup` merges, or a detached supervisor's `SHIP_LAUNCH` / `SHIP_STOP` below
 	// — so it is one of the `TRACE_KINDS` the last-event read skips.
 	SHIP_STAGE: 'ship-stage',
-	// One progress watcher line — the `at … / next …` heartbeat `run:progress` prints
-	// (joshuafolkken/kit#2437). Printed only to the watcher's own output, a headless successor's heartbeat
-	// was buried in its log after a cut; on the stream it reaches the attached session's relay. It says
+	// One progress watcher line — the `at … / next …` heartbeat `run:progress` prints. Printed only to
+	// the watcher's own output, a headless successor's heartbeat would be buried in its log after a cut;
+	// on the stream it reaches the attached session's relay. It says
 	// the run is alive rather than where it is, so it is a trace kind like `SHIP_STAGE`.
 	HEARTBEAT: 'heartbeat',
-	// The post-implementation region handed to a detached `josh ship --detach` supervisor
-	// (joshuafolkken/kit#2428). Unlike a stage trace it is a position: the agent has ended and the
+	// The post-implementation region handed to a detached `josh ship --detach` supervisor. Unlike a stage
+	// trace it is a position: the agent has ended and the
 	// supervisor carries the run, so `run:step` answers `wait` until it stops or the issue closes.
 	SHIP_LAUNCH: 'ship-launch',
 	// The supervisor stopped at a failed stage — a red gate, a High/Medium review, a failed push, red CI
-	// (joshuafolkken/kit#2428). The position that hands control back: `run:step` prints the command that
+	// The position that hands control back: `run:step` prints the command that
 	// shows the stopped report, so the agent fixes it and relaunches rather than rebuilding the context.
 	SHIP_STOP: 'ship-stop',
+	// The idle watch's window — when the run began waiting on an empty backlog and when that wait ends
+	// `backlog:offer` writes it whenever the window changes, so `run:board` reads
+	// the deadline rather than guessing it. It is a trace: `emit_once`'s drain dedup and `run:step`'s
+	// position both read past it, so a watching loop never re-marks the drain it is waiting after.
+	IDLE: 'idle',
+	// An Issue the run filed on its way, written by `issue:file`, so a run started from the command line
+	// still surfaces what it found — `run:board`'s findings section reads it.
+	FILED: 'filed',
+	// A one-line observation short of an Issue, written with `run:event --append note` and shown in the
+	// same section.
+	NOTE: 'note',
+	// A lane child reached a phase no other event marks — its first implementation edit, written by the
+	// PreToolUse hook — so `run:board` draws how far the child has got. A trace,
+	// like `SHIP_STAGE`: it says where the child's work is, not where the run is.
+	LANE_PHASE: 'lane-phase',
+	// An issue `run:add` put into the live run. The parent's `--wait` watcher
+	// ends on it, so the issue takes the next free lane without waiting out the arrival probe's minute. A
+	// trace: it says what the run was handed, not where the run is.
+	ADD: 'add',
+	// `josh lane:limit` raised a live run's lane limit. The `--wait` watcher's
+	// arrival probe reads it as a wake: the lanes a raise frees are new room for a pool its baseline
+	// already holds. A trace: it says the run gained room, not where the run is.
+	LANE_LIMIT: 'lane-limit',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -108,7 +138,26 @@ const EVENT_KINDS: ReadonlyArray<string> = Object.values(EVENT_KIND)
 // The kinds that trace progress inside a step rather than mark where the run is. Every last-event reader
 // — `run:step`'s position, `emit_once`'s dedup — asks "where is the run", and a
 // ship's four stage lines after its `merge` would otherwise read as an unknown position.
-const TRACE_KINDS: ReadonlySet<string> = new Set([EVENT_KIND.SHIP_STAGE, EVENT_KIND.HEARTBEAT])
+const TRACE_KINDS: ReadonlySet<string> = new Set([
+	EVENT_KIND.SHIP_STAGE,
+	EVENT_KIND.HEARTBEAT,
+	EVENT_KIND.IDLE,
+	EVENT_KIND.FILED,
+	EVENT_KIND.NOTE,
+	EVENT_KIND.LANE_PHASE,
+	EVENT_KIND.ADD,
+	EVENT_KIND.LANE_LIMIT,
+])
+
+// The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
+// `note` line is a trace to the position readers but is the board's record of what the run found, so
+// it rolls off only with the positions. A ship-stage `start` and an `idle` line are disposable but go
+// last of them: `run:board` draws from those lines.
+const DISPOSABLE_KINDS: ReadonlySet<string> = new Set([
+	EVENT_KIND.SHIP_STAGE,
+	EVENT_KIND.HEARTBEAT,
+	EVENT_KIND.IDLE,
+])
 
 const event_schema = z.object({
 	pos: z.number(),
@@ -130,7 +179,7 @@ interface StreamRead {
 }
 
 // A kind the enumeration names, and nothing else. The predicate is what `append` asks before it writes,
-// so an event outside the enumeration is never appended (joshuafolkken/kit#2205).
+// so an event outside the enumeration is never appended.
 function is_event_kind(value: string): value is EventKind {
 	return EVENT_KINDS.includes(value)
 }
@@ -170,18 +219,71 @@ function last_position(events: ReadonlyArray<RunEvent>): number {
 	return events[events.length - POSITION_INCREMENT]?.pos ?? FIRST_POSITION
 }
 
+// The issue a ship-stage names — `#<N> <stage> <phase>` carries it first.
+function issue_of(event: RunEvent): string {
+	return event.text.split(WORD_SEPARATOR)[FIRST_POSITION] ?? ''
+}
+
+// Each issue's newest ship-stage, the one the board reads its furthest phase from.
+function newest_stages(events: ReadonlyArray<RunEvent>): ReadonlySet<RunEvent> {
+	const newest = new Map<string, RunEvent>()
+
+	for (const event of events) {
+		if (event.kind === EVENT_KIND.SHIP_STAGE) newest.set(issue_of(event), event)
+	}
+
+	return new Set(newest.values())
+}
+
+// A ship-stage that starts its stage — the line `run:board` draws a phase from. A `done`, a `failed` and
+// a passed-over stage draw none.
+function is_stage_start(event: RunEvent): boolean {
+	if (event.kind !== EVENT_KIND.SHIP_STAGE) return false
+
+	return event.text.split(WORD_SEPARATOR)[STAGE_PHASE_INDEX] === run_ship_stage.PHASE.START
+}
+
+// A disposable line `run:board` draws from: a ship-stage `start` is a phase on a lane's track, and an
+// `idle` line is the deadline of the run's wait.
+function is_drawn(event: RunEvent): boolean {
+	return event.kind === EVENT_KIND.IDLE || is_stage_start(event)
+}
+
+// The lines the bound may drop, in the order it drops them: the ones that draw nothing first, then the
+// ones `run:board` draws from, each group oldest first.
+function droppable(events: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> {
+	const kept = newest_stages(events)
+	const disposable = events.filter((event) => DISPOSABLE_KINDS.has(event.kind) && !kept.has(event))
+
+	return [
+		...disposable.filter((event) => !is_drawn(event)),
+		...disposable.filter((event) => is_drawn(event)),
+	]
+}
+
 // The bounded stream serialized back to JSONL. The newest `EVENT_CAP` are kept and the oldest roll off;
 // each survivor keeps its original `pos`, so the bound never renumbers a position a reader is holding.
-// The stream held to `EVENT_CAP`, dropping the oldest trace events before any position
-// (joshuafolkken/kit#3245). A long run's ship-stage and heartbeat lines once filled 396 of the 500 slots
-// and pushed its cuts off, so the retrospective counted `cut 0` for a run with thirteen; a trace says only
-// that the run was alive, so it is the first to go. Only a stream of positions alone rolls them off.
+// The stream held to `EVENT_CAP`, dropping the oldest trace events before any position: a trace says
+// only that the run was alive, so it is the first to go, and a long run's trace lines never push its
+// cuts off. Only a stream of positions alone rolls them off.
+//
+// **Each issue's newest ship-stage is not disposable**: it is the only record `run:board` draws a lane's
+// review-and-later phase from, and on a stream full of positions it would otherwise roll off in its own
+// append.
+//
+// **A ship-stage `start` outlasts the other disposable lines**: each one is a phase on the lane's track,
+// so it is kept past the `done` lines and the heartbeats. An `idle` line goes with them, oldest first,
+// so a run's newest wait is not the first line a stream of starts and positions gives up.
+//
+// **The kept line carries the history**: on a stream the positions fill, every append still rolls off
+// the issue's previous stage line, so the newest one lists every stage its
+// attempt has started (`run-ship-stage.ts` → `event_text`) and the track is redrawn from it alone.
 function bounded(events: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> {
 	const excess = events.length - EVENT_CAP
 
 	if (excess <= 0) return events
 
-	const dropped = new Set(events.filter((event) => TRACE_KINDS.has(event.kind)).slice(0, excess))
+	const dropped = new Set(droppable(events).slice(0, excess))
 
 	return events.filter((event) => !dropped.has(event)).slice(-EVENT_CAP)
 }
@@ -190,21 +292,43 @@ function serialize(events: ReadonlyArray<RunEvent>): string {
 	return `${events.map((event) => JSON.stringify(event)).join(LINE_SEPARATOR)}${LINE_SEPARATOR}`
 }
 
+// The read-modify-write, run only while the stream's lock is held. `replace_text_stamp` publishes the
+// rewrite with a rename, so a reader never sees the stream absent or half-written.
+function append_held(target: string, event: Omit<RunEvent, 'pos'>): number {
+	const existing = read_events(target)
+	const position = last_position(existing) + POSITION_INCREMENT
+	const events = bounded([...existing, { pos: position, ...event }])
+
+	stamp_file.replace_text_stamp(target, serialize(events))
+
+	return position
+}
+
 /**
  * Append one event, or refuse a kind the enumeration does not name.
  *
  * The position is the previous maximum plus one — monotonic across session cuts because the stream is
- * keyed to the run's identity rather than a session. `write_text_stamp` unlinks then creates
- * exclusively, so the rewrite is symlink-safe.
+ * keyed to the run's identity rather than a session. **The read and the rewrite are one step under a
+ * per-stream lock**: the parent, a cut successor and every lane child append to one stream, and an
+ * unlocked read-then-rewrite would lose one writer's event to another's. A lock still
+ * held after the wait is reported on stderr and thrown, which the best-effort emit side swallows.
  */
 function append(target: string, kind: string, text: string, at: string): AppendResult {
 	if (!is_event_kind(kind)) return { appended: false, position: FIRST_POSITION }
 
-	const existing = read_events(target)
-	const position = last_position(existing) + POSITION_INCREMENT
-	const events = bounded([...existing, { pos: position, at, kind, text }])
+	const lock = `${target}${LOCK_SUFFIX}`
+	const position = repository_lock.with_lock_sync(
+		() => append_held(target, { at, kind, text }),
+		lock,
+		LOCK_WAIT_MS,
+	)
+
+	if (position === undefined) {
+		const message = `run event stream: gave up waiting for the lock at ${lock}`
 
-	stamp_file.write_text_stamp(target, serialize(events))
+		process.stderr.write(`${message}\n`)
+		throw new Error(message)
+	}
 
 	return { appended: true, position }
 }
@@ -225,16 +349,16 @@ function read_from(target: string, position: number): StreamRead {
 	}
 }
 
-// The degenerate single-event read the "last line" consumers keep working as (joshuafolkken/kit#2205):
-// the newest positional event, or `undefined` for a stream with none. Trace events are skipped
-// (joshuafolkken/kit#2426), so the answer stays the run's position however many stage lines follow it.
+// The degenerate single-event read the "last line" consumers use: the newest positional event, or
+// `undefined` for a stream with none. Trace events are skipped, so the answer stays the run's position
+// however many stage lines follow it.
 function read_last(target: string): RunEvent | undefined {
 	return read_events(target).findLast((event) => !TRACE_KINDS.has(event.kind))
 }
 
 // Whether `kind` is already on the stream after the newest `reset_kind` — or anywhere, before the first
 // one. The episode test for a marker whose episode ends only when something specific happens rather than
-// when any other event lands (joshuafolkken/kit#2464): a stall ends at a dispatch, and the merges, parks
+// when any other event lands: a stall ends at a dispatch, and the merges, parks
 // and heartbeats every parallel lane appends in between must not read as a fresh stall.
 function has_since(events: ReadonlyArray<RunEvent>, kind: string, reset_kind: string): boolean {
 	const reset_at = events.findLastIndex((event) => event.kind === reset_kind)
@@ -242,7 +366,7 @@ function has_since(events: ReadonlyArray<RunEvent>, kind: string, reset_kind: st
 	return events.slice(reset_at + POSITION_INCREMENT).some((event) => event.kind === kind)
 }
 
-// One event as the line a reader relays (joshuafolkken/kit#2207). The follow reader and the degenerate
+// One event as the line a reader relays. The follow reader and the degenerate
 // `run:wake --list` both present events to a person, so the "what an event reads as" lives here, beside
 // the enumeration it names, rather than being spelled twice at the two call sites. `at`, `kind` and
 // `text` are joined with a separator no field carries, so the three stay legible in one line.
@@ -260,6 +384,7 @@ const run_event_stream = {
 	append,
 	format_event,
 	has_since,
+	is_stage_start,
 	read_events,
 	read_from,
 	read_last,

package/scripts/run/event/run-event-watch.ts

@@ -1,11 +1,9 @@
 import type { StreamRead } from './run-event-stream'
 
-// The loop behind `josh run:event --watch` (joshuafolkken/kit#2492) — the ambient surface a person keeps
-// open in a pane of their own. `--follow` is one bounded pass a session restarted after every exit,
-// relaying each line into its conversation; each relay re-read that conversation's whole history, so the
-// attached session outspent every lane of the run on relaying alone. The watch runs the same pass in a
-// loop inside one process and writes each event as the rendered line, so a person sees an event land at
-// once and the conversation is never woken for it.
+// The loop behind `josh run:event --watch` — the ambient surface a person keeps open in a pane of their
+// own. A session relaying `--follow` would re-read its whole history on every line, so the watch runs
+// the same pass in a loop inside one process and writes each event as the rendered line, so a person
+// sees an event land at once and the conversation is never woken for it.
 //
 // **The pass is `run_event_follow.follow`, reused through a port rather than re-spelled**, and the loop
 // carries the position the pass hands back. `should_continue` is the one stop condition: the CLI's is