@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env tsx
+import { setTimeout as sleep } from 'node:timers/promises'
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { session_language } from '#scripts/josh/session-language'
+import { run_event_follow, type FollowPorts } from './run-event-follow'
+import { run_event_render } from './run-event-render'
+import { run_event_stream, type StreamRead } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+import { run_event_watch } from './run-event-watch'
+
+// `josh run:event` — the command a run's step calls to append to, or read back, the append-only event
+// stream (joshuafolkken/kit#2205). The in-process seams (`run:merge`) append directly; the steps with no
+// josh command at the point the event happens — a plan posted, a child launched, a PR opened, a stop —
+// call `--append` here, so parent and lane child alike write to the one stream. `--from` is the woken
+// reader's "everything since the position I last read"; `--last` is the degenerate single-event read.
+//
+// **`--follow` is one bounded read that waits** (joshuafolkken/kit#2207). It is `--from` that returns
+// the moment an event is past the given position, and otherwise at the interval. The lines go to
+// standard output and the position to read from next goes to standard error — the same before and after
+// a session cut, because the stream is the run's and the position is the caller's.
+//
+// **`--watch` is the ambient surface: the same pass in a loop that never exits** (joshuafolkken/kit#2492),
+// each event rendered in the session language (`run-event-render.ts`), for a person to keep open in a
+// pane of their own. No conversation relays the stream any more — a session woken per event re-read its
+// whole history each time, and outspent every lane of the run doing it.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const APPEND_FLAG = '--append'
+const FROM_FLAG = '--from'
+const FOLLOW_FLAG = '--follow'
+const LAST_FLAG = '--last'
+const WATCH_FLAG = '--watch'
+const FLAG_INDEX = 0
+const KIND_INDEX = 1
+const POSITION_INDEX = 1
+const TEXT_INDEX = 2
+const USAGE =
+	'Usage: josh run:event --append <kind> <text> | --from <position> | --follow <position> | --watch [<position>] | --last'
+
+function now_iso(): string {
+	return new Date().toISOString()
+}
+
+function report_usage(): number {
+	process.stderr.write(`${USAGE}\n`)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run_append(kind: string, text: string): Promise<number> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined) return report_usage()
+
+	const result = run_event_stream.append(target, kind, text, now_iso())
+
+	if (!result.appended) {
+		process.stderr.write(`not a session-facing event kind: ${kind}\n`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	process.stdout.write(`${String(result.position)}\n`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run_from(position_text: string | undefined): Promise<number> {
+	const target = await run_event_stream_emit.stream_target()
+	const position = Number(position_text)
+
+	if (target === undefined || position_text === undefined || !Number.isSafeInteger(position)) {
+		return report_usage()
+	}
+
+	process.stdout.write(`${JSON.stringify(run_event_stream.read_from(target, position))}\n`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function follow_ports(target: string): FollowPorts {
+	return {
+		read: (position) => run_event_stream.read_from(target, position),
+		now: () => Date.now(),
+		sleep: async (milliseconds) => {
+			await sleep(milliseconds)
+		},
+	}
+}
+
+// The events on standard output, and the next position on standard error for the caller to read back.
+// An empty read is a quiet tick — nothing printed, the position unchanged.
+function print_pass(read: StreamRead): void {
+	for (const event of read.events) {
+		process.stdout.write(`${run_event_stream.format_event(event)}\n`)
+	}
+
+	process.stderr.write(`next_position: ${String(read.next_position)}\n`)
+}
+
+async function follow_pass(target: string, position: number): Promise<StreamRead> {
+	return await run_event_follow.follow(follow_ports(target), position, {
+		interval_ms: run_event_follow.FOLLOW_INTERVAL_MS,
+		tick_ms: run_event_follow.FOLLOW_TICK_MS,
+	})
+}
+
+async function run_follow(position_text: string | undefined): Promise<number> {
+	const target = await run_event_stream_emit.stream_target()
+	const position = Number(position_text)
+
+	if (target === undefined || position_text === undefined || !Number.isSafeInteger(position)) {
+		return report_usage()
+	}
+
+	print_pass(await follow_pass(target, position))
+
+	return SUCCESS_EXIT_CODE
+}
+
+// With no position the pane starts at the stream's current end, so opening it shows what happens next
+// rather than replaying the up-to-`EVENT_CAP` events already there.
+function watch_start(target: string, position_text: string | undefined): number | undefined {
+	if (position_text === undefined) return run_event_stream.read_from(target, 0).next_position
+
+	const position = Number(position_text)
+
+	return Number.isSafeInteger(position) ? position : undefined
+}
+
+async function run_watch(position_text: string | undefined): Promise<number> {
+	const target = await run_event_stream_emit.stream_target()
+	const position = target === undefined ? undefined : watch_start(target, position_text)
+
+	if (target === undefined || position === undefined) return report_usage()
+
+	const { lang } = session_language.resolve_session_lang()
+
+	await run_event_watch.watch(
+		{
+			pass: async (from) => await follow_pass(target, from),
+			write: (line) => process.stdout.write(`${line}\n`),
+			render: (event) => run_event_render.render(event, lang),
+			should_continue: () => true,
+		},
+		position,
+	)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run_last(): Promise<number> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined) return report_usage()
+
+	const last = run_event_stream.read_last(target)
+
+	process.stdout.write(`${last === undefined ? '' : JSON.stringify(last)}\n`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function append_kind(argv: ReadonlyArray<string>): string {
+	return argv[KIND_INDEX] ?? ''
+}
+
+function append_text(argv: ReadonlyArray<string>): string {
+	return argv.slice(TEXT_INDEX).join(' ')
+}
+
+type Mode = (argv: ReadonlyArray<string>) => Promise<number>
+
+const MODES: ReadonlyMap<string, Mode> = new Map<string, Mode>([
+	[APPEND_FLAG, async (argv) => await run_append(append_kind(argv), append_text(argv))],
+	[FROM_FLAG, async (argv) => await run_from(argv[POSITION_INDEX])],
+	[FOLLOW_FLAG, async (argv) => await run_follow(argv[POSITION_INDEX])],
+	[WATCH_FLAG, async (argv) => await run_watch(argv[POSITION_INDEX])],
+	[LAST_FLAG, async () => await run_last()],
+])
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const mode = MODES.get(argv[FLAG_INDEX] ?? '')
+
+	return mode === undefined ? report_usage() : await mode(argv)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_event_cli = {
+	USAGE,
+	main,
+	run,
+	watch_start,
+}
+
+// `.env` is read here rather than through the dispatcher's `tsx_arguments`, which would take this
+// command off in-process dispatch: `--watch` renders in the `JOSH_SESSION_LANG` a person keeps there.
+// Inside the guard, so a developer's own `.env` cannot decide what the unit tests see.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	josh_environment_file.load_environment_file()
+	await main(process.argv.slice(ARGV_OFFSET))
+}
+
+export { run_event_cli }

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

@@ -0,0 +1,65 @@
+import type { StreamRead } from './run-event-stream'
+
+// The follow read behind `josh run:event --follow` and `--watch` (joshuafolkken/kit#2207). A reader
+// asks the run's event stream for "everything since the position I last read" — and must see **both** a
+// new event's arrival, promptly, and the interval passing when nothing new has happened, so a person
+// watching sees progress land at once and still sees the run is alive when it is quiet.
+//
+// **This is one bounded pass, not the loop.** It returns as soon as any event is past the caller's
+// position (the arrival), or when the interval elapses having found none (the quiet tick); the caller
+// shows what came back and asks again from the returned position. The loop is `run-event-watch.ts`,
+// run in a pane of its own rather than by a session restarting the pass (joshuafolkken/kit#2492).
+//
+// **It reads the run's stream, not a session's.** `read` is `run_event_stream.read_from` bound to the
+// run-keyed target, and the position is the caller's own, so the pass answers the same before and after
+// a `backlogrun` session cut: a cut changes who executes, never what the stream says or where a reader
+// stands in it. That invariant is the point of the whole issue, and it is why this takes ports rather
+// than resolving a target itself — the test drives it with a stream it controls and a clock it advances.
+//
+// **It is a poll, and deliberately not `run:progress`'s loop.** That one reads GitHub observations and
+// exits on a silence interval; this one reads the appended stream and exits on a position advancing.
+// The shapes rhyme, but the data source and the exit condition are different, so folding them together
+// would couple two unrelated readers rather than remove a duplicate.
+
+// The follow's quiet-tick cadence and how promptly it notices an arrival. The interval only bounds a
+// wait that found nothing — an arrival returns within a tick of landing — so it can be as long as the
+// heartbeat without making an arrival late, and the tick is a cheap `stat` of one file.
+const MS_PER_SECOND = 1000
+const SECONDS_PER_MINUTE = 60
+const FOLLOW_INTERVAL_MINUTES = 20
+const FOLLOW_INTERVAL_MS = FOLLOW_INTERVAL_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND
+const FOLLOW_TICK_MS = MS_PER_SECOND
+
+interface FollowPorts {
+	read: (position: number) => StreamRead
+	now: () => number
+	sleep: (milliseconds: number) => Promise<void>
+}
+
+interface FollowOptions {
+	interval_ms: number
+	tick_ms: number
+}
+
+// Everything past `position`, returned the moment it exists or when the interval runs out. `deadline`
+// is fixed once from the start, so the wait is the interval and not the interval per empty tick.
+async function follow(
+	ports: FollowPorts,
+	position: number,
+	options: FollowOptions,
+): Promise<StreamRead> {
+	const deadline = ports.now() + options.interval_ms
+	let read = ports.read(position)
+
+	while (read.events.length === 0 && ports.now() < deadline) {
+		await ports.sleep(options.tick_ms)
+		read = ports.read(position)
+	}
+
+	return read
+}
+
+const run_event_follow = { FOLLOW_INTERVAL_MS, FOLLOW_TICK_MS, follow }
+
+export type { FollowOptions, FollowPorts }
+export { run_event_follow }

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

@@ -0,0 +1,75 @@
+import type { EventKind, RunEvent } from './run-event-stream'
+
+// One run event as the line a person reads in the watch pane (joshuafolkken/kit#2492). The ambient tier
+// used to be a session relaying `run:event --follow`, and every relay re-read that session's whole
+// history; the pane is a script, so the wording a relaying session supplied is supplied here instead —
+// one label per event kind, in the session language, beside the local clock time.
+//
+// **The kinds are a fixed enumeration** (`run-event-stream.ts` → `EVENT_KIND`), so a template table is
+// the whole renderer; a kind the table does not name — a stream written by a newer kit — prints its raw
+// kind rather than being dropped, so the pane never hides an event.
+
+const JA = 'ja'
+const FIELD_SEPARATOR = ' · '
+const CLOCK_WIDTH = 2
+const CLOCK_PAD = '0'
+
+interface KindLabel {
+	ja: string
+	en: string
+}
+
+// Keyed by `EventKind`, so a kind added to the enumeration without a label fails the type check.
+const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
+	plan: { ja: '計画', en: 'planned' },
+	'child-launch': { ja: '着手', en: 'launched' },
+	merge: { ja: 'マージ', en: 'merged' },
+	park: { ja: '保留', en: 'parked' },
+	split: { ja: '分割', en: 'split' },
+	outage: { ja: '障害', en: 'outage' },
+	cut: { ja: 'セッション交代', en: 'session cut' },
+	drain: { ja: 'バックログが空', en: 'backlog drained' },
+	stop: { ja: '停止', en: 'stopped' },
+	'pr-opened': { ja: 'PR 作成', en: 'PR opened' },
+	'review-round': { ja: 'レビュー', en: 'review round' },
+	retrospective: { ja: '振り返り', en: 'retrospective' },
+	stall: { ja: '滞留', en: 'stalled' },
+	stranded: { ja: '実行者なし', en: 'stranded' },
+	'ship-stage': { ja: '出荷の段階', en: 'ship stage' },
+	heartbeat: { ja: '生存確認', en: 'heartbeat' },
+	'ship-launch': { ja: '出荷を開始', en: 'ship launched' },
+	'ship-stop': { ja: '出荷が停止', en: 'ship stopped' },
+}
+
+const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))
+
+function label_of(kind: string, lang: string): string {
+	const label = LABELS_BY_KIND.get(kind)
+
+	if (label === undefined) return kind
+
+	return lang === JA ? label.ja : label.en
+}
+
+function two_digits(value: number): string {
+	return String(value).padStart(CLOCK_WIDTH, CLOCK_PAD)
+}
+
+// The local wall-clock `HH:MM` of the event, the reading a person watching a pane compares with the clock
+// on their screen; an unparseable stamp is shown as written rather than as `NaN:NaN`.
+function clock_of(at: string): string {
+	const date = new Date(at)
+
+	if (Number.isNaN(date.getTime())) return at
+
+	return `${two_digits(date.getHours())}:${two_digits(date.getMinutes())}`
+}
+
+function render(event: RunEvent, lang: string): string {
+	return [clock_of(event.at), label_of(event.kind, lang), event.text].join(FIELD_SEPARATOR)
+}
+
+const run_event_render = { KIND_LABELS, clock_of, label_of, render }
+
+export type { KindLabel }
+export { run_event_render }

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

@@ -0,0 +1,127 @@
+import type { CarryRead } from './run-carry'
+import { run_event_stream, type RunEvent } from './run-event-stream'
+
+// The one place a stream consumer scopes the event stream to a single invocation (joshuafolkken/kit#2395).
+// The stream is the repository's event log, not this run's — it outlives every invocation by design — so a
+// consumer handed every event treats a previous invocation's merges, parks and cuts as its own. #2393 built
+// the fix (the carry record's `started_at` as the lower bound, filtered by each event's own time) but left
+// it private inside `run-report.ts`; every other consumer of the stream carried the same defect. This is that
+// mechanism, published once, so `run:report`, the retrospective digest and `run:step` share one time filter
+// rather than each writing it again — the second copy `CLAUDE.md` forbids as a clone.
+//
+// **It never rounds an undetermined scope back to the whole stream.** A scope that cannot be determined — no
+// carry record, an unreadable one, or a start time that is not a time — answers `undefined`, and each
+// consumer falls to the "could not determine" side rather than showing every invocation's events, which is
+// exactly the rounding #2308 and #2393 named.
+
+const SINCE_SCOPE = 'since'
+const UNKNOWN_SCOPE = 'unknown'
+
+// Which invocation a stream read covers. `since` carries the start time the carry record holds — and because
+// that field survives a `--cut` unchanged, the events either side of a cut fall inside one scope without a
+// consumer needing to know that cuts exist.
+type EventScope = { kind: typeof SINCE_SCOPE; started_at: string } | { kind: typeof UNKNOWN_SCOPE }
+
+const UNKNOWN_EVENT_SCOPE: EventScope = { kind: UNKNOWN_SCOPE }
+
+// A moment on the clock, or nothing when the text is not a time. Both the scope's start and an event's own
+// `at` go through it, so neither a corrupt record nor a truncated append is read as a moment.
+function moment_of(at: string): number | undefined {
+	const parsed = Date.parse(at)
+
+	return Number.isNaN(parsed) ? undefined : parsed
+}
+
+// Whether one event belongs to the invocation that began at `floor`. An event whose `at` cannot be read is
+// **out**: a consumer must show no line from before the start, and a line with no readable time cannot be
+// shown to satisfy that.
+function is_within(event: RunEvent, floor: number): boolean {
+	const at = moment_of(event.at)
+
+	return at !== undefined && at >= floor
+}
+
+// This invocation's events, or `undefined` when the scope could not be determined. The two answers stay
+// apart deliberately: an invocation that has done nothing yet is an empty list, an undetermined scope is
+// `undefined`, and collapsing them is exactly what would round the unknown back to "render everything".
+function scoped_events(
+	events: ReadonlyArray<RunEvent>,
+	scope: EventScope,
+): ReadonlyArray<RunEvent> | undefined {
+	if (scope.kind === UNKNOWN_SCOPE) return undefined
+
+	const floor = moment_of(scope.started_at)
+
+	if (floor === undefined) return undefined
+
+	return events.filter((event) => is_within(event, floor))
+}
+
+// The scope the run's own carry record implies. A record that reads at all names the invocation's start, and
+// **an expired one names it just as well**: expiry is the budget's verdict on a run, not a gap in the record,
+// so rounding it to unknown would withhold the scope from exactly the long runs that most need one. Only an
+// absent or unreadable record leaves the scope undetermined.
+function scope_of(read: CarryRead): EventScope {
+	if (read.kind === 'carried' || read.kind === 'expired') {
+		return { kind: SINCE_SCOPE, started_at: read.carry.started_at }
+	}
+
+	return UNKNOWN_EVENT_SCOPE
+}
+
+// The newest event within scope, or `undefined` when the scope could not be determined or nothing falls
+// inside it. The "last line" consumers read this rather than the raw newest event, so a stale event a
+// previous invocation left on the stream is never read as this run's position (joshuafolkken/kit#2395).
+function last_scoped_event(
+	events: ReadonlyArray<RunEvent>,
+	scope: EventScope,
+): RunEvent | undefined {
+	// Trace events (a `josh ship` stage line, joshuafolkken/kit#2426) are skipped, as `read_last` skips
+	// them, so `run:step` reads the run's position rather than an unknown `ship-stage`.
+	return scoped_events(events, scope)?.findLast(
+		(event) => !run_event_stream.TRACE_KINDS.has(event.kind),
+	)
+}
+
+// The positions a detached `josh ship` supervisor leaves (joshuafolkken/kit#2428). Each names its issue
+// (`#<N> …`), so they are self-scoping where the carry scope is not: the stream is shared by every lane,
+// and another lane's supervisor must never be read as this run's position.
+const SHIP_POSITION_KINDS: ReadonlySet<string> = new Set([
+	run_event_stream.EVENT_KIND.SHIP_LAUNCH,
+	run_event_stream.EVENT_KIND.SHIP_STOP,
+])
+
+function is_foreign_ship_event(event: RunEvent, issue: string): boolean {
+	return SHIP_POSITION_KINDS.has(event.kind) && !event.text.startsWith(`#${issue} `)
+}
+
+function is_own_ship_event(event: RunEvent, issue: string): boolean {
+	return SHIP_POSITION_KINDS.has(event.kind) && !is_foreign_ship_event(event, issue)
+}
+
+// The newest position for one issue's run: the scoped last event with other issues' ship positions left
+// out, and — where no scope applies, as in an interactive `fullrun` with no carry record — the issue's own
+// newest ship position, which its issue number already scopes. A determined scope with nothing in it yet
+// reads nothing: an earlier invocation's stop for the same issue is not this invocation's position.
+function last_issue_event(
+	events: ReadonlyArray<RunEvent>,
+	scope: EventScope,
+	issue: string,
+): RunEvent | undefined {
+	const own = events.filter((event) => !is_foreign_ship_event(event, issue))
+
+	if (scope.kind === SINCE_SCOPE) return last_scoped_event(own, scope)
+
+	return own.findLast((event) => is_own_ship_event(event, issue))
+}
+
+const run_event_scope = {
+	UNKNOWN_EVENT_SCOPE,
+	last_issue_event,
+	last_scoped_event,
+	scope_of,
+	scoped_events,
+}
+
+export type { EventScope }
+export { run_event_scope }

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

@@ -0,0 +1,140 @@
+import { run_carry } from './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
+// 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.
+//
+// **The key is `run-carry.ts`'s, not `run-progress-clock.ts`'s.** The report clock keys on the work
+// tree's own git directory because two lanes are two clocks; this stream is the opposite — the parent
+// session, a cut successor and every lane child are one run and append to one stream — so it keys on the
+// common git directory the carry record uses, which every lane of one repository shares.
+
+function now_iso(): string {
+	return new Date().toISOString()
+}
+
+/**
+ * The stream's path for the run this checkout belongs to, or `undefined` when there is no git
+ * repository to key on — outside one there is no run identity, and no stream.
+ */
+async function stream_target(): Promise<string | undefined> {
+	const repository = await run_carry.repository_directory()
+
+	return repository === undefined ? undefined : run_event_stream.target_of(repository)
+}
+
+/**
+ * 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).
+ */
+async function emit(kind: string, text: string): Promise<void> {
+	try {
+		const target = await stream_target()
+
+		if (target === undefined) return
+
+		run_event_stream.append(target, kind, text, now_iso())
+	} catch {
+		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
+	}
+}
+
+/**
+ * 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).
+ * 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 exactly when the marker was fresh. A skipped duplicate and a swallowed failure both read
+ * `false`: neither is a fresh episode.
+ */
+async function emit_once(kind: string, text: string): Promise<boolean> {
+	try {
+		const target = await stream_target()
+
+		if (target === undefined || run_event_stream.read_last(target)?.kind === kind) return false
+
+		return run_event_stream.append(target, kind, text, now_iso()).appended
+	} catch {
+		// Best-effort: a failed append is dropped rather than raised into the loop's work.
+		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
+// re-sends.
+function invocation_events(repository: string, target: string): ReadonlyArray<RunEvent> {
+	const events = run_event_stream.read_events(target)
+	const scope = run_event_scope.scope_of(run_carry.read_carry(run_carry.carry_path(repository)))
+
+	return run_event_scope.scoped_events(events, scope) ?? events
+}
+
+/**
+ * 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.
+ */
+async function emit_once_since(kind: string, text: string, reset_kind: string): Promise<boolean> {
+	try {
+		const repository = await run_carry.repository_directory()
+
+		if (repository === undefined) return false
+
+		const target = run_event_stream.target_of(repository)
+
+		if (run_event_stream.has_since(invocation_events(repository, target), kind, reset_kind)) {
+			return false
+		}
+
+		return run_event_stream.append(target, kind, text, now_iso()).appended
+	} catch {
+		// Best-effort: a failed append is dropped rather than raised into the caller's work.
+		return false
+	}
+}
+
+// One progress heartbeat line onto the stream, so a relay reaches it across a cut (joshuafolkken/kit#2437).
+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.
+async function current_events(): Promise<ReadonlyArray<RunEvent>> {
+	try {
+		const repository = await run_carry.repository_directory()
+
+		if (repository === undefined) return []
+
+		const read = run_carry.read_carry(run_carry.carry_path(repository))
+		const scope = run_event_scope.scope_of(read)
+		const events = run_event_stream.read_events(run_event_stream.target_of(repository))
+
+		return run_event_scope.scoped_events(events, scope) ?? []
+	} catch {
+		return []
+	}
+}
+
+const run_event_stream_emit = {
+	current_events,
+	emit,
+	emit_heartbeat,
+	emit_once,
+	emit_once_since,
+	stream_target,
+}
+
+export { run_event_stream_emit }