@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/run/carry/run-carry-conversation.ts

@@ -25,7 +25,7 @@ import type { CarryOwner, RunCarry } from './run-carry'
 // How long after its last write a conversation whose process has gone still counts as continuing. It
 // bridges a restart and a resume — measured at eighteen seconds — with room for a person reopening a
 // window, and it is the order of the wake grace window, so a genuine crash is recovered no later than
-// a lost wake would be retried.
+// a lost wake would be retried. A headless owner is not given it (`run-carry.ts` → `is_owner_live`).
 const CONVERSATION_QUIET_MS = 600_000
 
 type Environment = Readonly<Record<string, string | undefined>>

package/scripts/run/carry/run-carry.ts

@@ -323,11 +323,16 @@ function adopt_carry(
 // A live pid with no readable start token is conservatively held rather than replaced. The command
 // cannot prove its generation inside that sandbox, but a false `busy` stops for a person while a
 // false `standing` can put two parents on one budget. A record with no pid still resolves false.
-// A gone process whose conversation is still being continued is live (`run-carry-conversation.ts`).
-function is_owner_live(carry: RunCarry, now: Date = new Date()): boolean {
-	if (process_identity.is_same_process(carry.owner_pid, carry.owner_start) !== false) return true
+// A gone process whose conversation is still being continued is live (`run-carry-conversation.ts`);
+// a headless owner is never resumed into a new process, so its gone process is a gone owner.
+function is_owner_live(
+	carry: RunCarry,
+	now: Date = new Date(),
+	same_process: typeof process_identity.is_same_process = process_identity.is_same_process,
+): boolean {
+	if (same_process(carry.owner_pid, carry.owner_start) !== false) return true
 
-	return run_carry_conversation.is_conversation_live(carry, now)
+	return carry.is_owner_headless !== true && run_carry_conversation.is_conversation_live(carry, now)
 }
 
 function is_owned_by(carry: RunCarry, owner: CarryOwner): boolean {

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

@@ -61,6 +61,7 @@ const {
 	report_held_cut,
 	report_incomplete,
 	report_over,
+	report_relaunched_cut,
 	report_reviewer,
 	report_stale,
 	report_under_threshold,
@@ -124,7 +125,7 @@ function relaunch(target: string, lane: LaneInfo, phase: string): number {
 
 	if (notes.length > 0) console.error(notes.join('\n'))
 
-	return report(CUT_VERDICT, SUCCESS_EXIT_CODE)
+	return report_relaunched_cut()
 }
 
 const { is_lane_branch } = run_cut_ready
@@ -199,7 +200,7 @@ async function finish_cut(target: string, lane: LaneInfo, request: CutRequest):
 	if (refused !== undefined) return refused
 
 	return lane_relaunch.is_openai_lane(lane)
-		? report(CUT_VERDICT, SUCCESS_EXIT_CODE)
+		? report_relaunched_cut()
 		: relaunch(target, lane, request.phase)
 }
 

package/scripts/run/cut/run-cut-handoff.ts

@@ -126,10 +126,10 @@ function describe_handoff(handoff: Handoff): string {
 	].join('\n\n')
 }
 
-// Where a handoff file is written: `.claude/tmp/` is ignored, so `josh git`, which stages every
+// Where a handoff file is written: `.josh/tmp/` is ignored, so `josh git`, which stages every
 // untracked non-ignored file, cannot commit the note with the code. A refusal that asked for "a file"
 // and named no place got one written beside the code and committed (joshuafolkken/kit#3603).
-const HANDOFF_PATH = '.claude/tmp/handoff-<N>.json'
+const HANDOFF_PATH = '.josh/tmp/handoff-<N>.json'
 
 const run_cut_handoff = {
 	HANDOFF_FORMAT,

package/scripts/run/cut/run-cut-report.ts

@@ -148,6 +148,20 @@ function report_held_cut(issue: string): number {
 	return report(CUT_VERDICT, SUCCESS_EXIT_CODE)
 }
 
+// **A cut that relaunched its successor says so on this session's own transcript** (joshuafolkken/kit#3936).
+// The successor's `run:cut --resume` can clear the record before this session's turn ends, so the
+// `Stop` hook cannot tell a cut stop by the record alone; it reads this line off the turn instead, a
+// fact no other process can remove. The held cut never prints it — a person resumes that one. **A bare
+// token line**, so it is read off the `run:cut` call's own result (`cost-run-cut.ts`), and a turn that
+// merely quotes it is not read as a relaunch.
+const RELAUNCHED_CUT_MARKER = 'cut-relaunched'
+
+function report_relaunched_cut(): number {
+	console.error(RELAUNCHED_CUT_MARKER)
+
+	return report(CUT_VERDICT, SUCCESS_EXIT_CODE)
+}
+
 // **An implementation cut is never resumed by a session over the threshold**.
 // The cut outside a lane leaves the session that took it open, so a person retyping `fullrun #N` there
 // would be answered `resume-impl`, keep implementing over the threshold, and be cut again on the next
@@ -174,6 +188,7 @@ const run_cut_report = {
 	INCOMPLETE_VERDICT,
 	NOT_A_LANE_VERDICT,
 	OVER_VERDICT,
+	RELAUNCHED_CUT_MARKER,
 	RESUME_IMPL_VERDICT,
 	RESUME_VERDICT,
 	STALE_VERDICT,
@@ -191,6 +206,7 @@ const run_cut_report = {
 	report_held_cut,
 	report_incomplete,
 	report_over,
+	report_relaunched_cut,
 	report_reviewer,
 	report_stale,
 	report_under_threshold,

package/scripts/run/detached-launch.ts

@@ -4,6 +4,7 @@ import { agent_launch_environment } from '#scripts/agent/agent-launch-environmen
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { launch_priority } from '#scripts/run/launch-priority'
 
 // Starting a process that outlives this one, and keeping what it writes.
 //
@@ -34,13 +35,18 @@ const UNSAFE_NOTE =
 //
 // A NUL byte is what `execve` treats as the end of a string, so a value carrying one executes as a
 // prefix of itself; the other control characters have no business in a command line and their presence
-// means the value did not come from where it was supposed to.
+// means the value did not come from where it was supposed to. **An agent's prompt is the one element a
+// line break belongs in** — a ship-stop prompt carries the failed output's lines — so a vector marked
+// `ends_with_prompt` lets it into its last element alone (joshuafolkken/kit#3964).
 //
 // The shared value validation lives with the role policy so environment overrides and argv elements
 // cannot disagree about which control characters or lengths are safe.
 interface LaunchArgv {
 	command: string
 	args: ReadonlyArray<string>
+	// Set by an agent argv builder, whose prompt is the last element: that one element may carry line
+	// breaks (`is_safe_prompt`), and every other element is checked as before.
+	ends_with_prompt?: boolean
 }
 
 type LaunchResult = { kind: 'launched'; pid: number } | { kind: 'failed'; note: string }
@@ -65,12 +71,23 @@ interface LaunchRequest {
 	profile?: AgentProfile | undefined
 }
 
-const { is_safe_value } = agent_role_profile
+const { is_safe_prompt, is_safe_value } = agent_role_profile
+const LAST = -1
+
+// An agent vector's prompt, the last element, may break lines; every other element is a value.
+function is_safe_element(argv: LaunchArgv, value: string, index: number): boolean {
+	const is_prompt = argv.ends_with_prompt === true && index === argv.args.length + LAST
+
+	return is_prompt ? is_safe_prompt(value) : is_safe_value(value)
+}
 
 // The single gate every argument vector passes before it reaches the operating system, whoever
 // composed it.
 function is_safe_argv(argv: LaunchArgv): boolean {
-	return is_safe_value(argv.command) && argv.args.every((value) => is_safe_value(value))
+	return (
+		is_safe_value(argv.command) &&
+		argv.args.every((value, index) => is_safe_element(argv, value, index))
+	)
 }
 
 function note_of(error: unknown): string {
@@ -251,6 +268,7 @@ async function attached_spawn(
 		child.once('exit', (exit_code) => {
 			resolve({ kind: 'completed', pid: child.pid ?? 0, exit_code })
 		})
+		launch_priority.lower(child.pid)
 		notify_spawn(child.pid, on_spawn, on_error)
 	})
 }
@@ -287,6 +305,7 @@ function spawned(
 		on_error(note_of(error))
 	})
 	child.unref()
+	launch_priority.lower(child.pid)
 
 	return child.pid === undefined ? { kind: 'failed', note: NO_PID_NOTE } : launched(child.pid)
 }
@@ -341,5 +360,5 @@ const detached_launch = {
 	note_of,
 }
 
-export type { LaunchArgv, LaunchRequest, LaunchResult }
+export type { AttachedLaunchResult, LaunchArgv, LaunchRequest, LaunchResult }
 export { detached_launch }

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

@@ -22,6 +22,7 @@ import {
 } from '#scripts/run/run-stage'
 import { run_stage_read, type StageRead } from '#scripts/run/run-stage-read'
 import { run_step } from '#scripts/run/run-step'
+import { run_step_section } from '#scripts/run/run-step-section'
 import { run_entry, type EntryParts } from './run-entry'
 import { run_entry_stop } from './run-entry-stop'
 
@@ -259,7 +260,13 @@ async function proceed(issue_number: string, hold: string, cost: string): Promis
 	// update is measured against (`issue-watch.ts`).
 	await issue_watch.record_baseline_here(issue_number)
 
-	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+	const code = emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+
+	// The entry's own read — the split assessment every run answers before its work — printed here so
+	// the reader does not spend a turn fetching it.
+	if (code !== SUCCESS_EXIT_CODE) return code
+
+	return run_step_section.print_section(run_step_section.ENTRY)
 }
 
 async function claim_run(

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

@@ -39,10 +39,6 @@ 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`)
 
@@ -54,7 +50,7 @@ async function run_append(kind: string, text: string): Promise<number> {
 
 	if (target === undefined) return report_usage()
 
-	const result = run_event_stream.append(target, kind, text, now_iso())
+	const result = await run_event_stream_emit.append_at(target, kind, text, new Date())
 
 	if (!result.appended) {
 		process.stderr.write(`not a session-facing event kind: ${kind}\n`)

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

@@ -6,9 +6,9 @@ import {
 	has_label_name,
 } from '#scripts/issue/issue-labels'
 
-// The text of a `filed` event: the Issue a run filed, its kind, its title, and the child whose work
-// turned it up. `issue:file` writes it and `run:board` reads it back, both through this module, so the
-// two never spell it differently.
+// The text of a `filed` event: the Issue a run filed, its kind, its title, whether a run's own session
+// filed it, and the child whose work turned it up. `issue:file` writes it and `run:board` reads it
+// back, both through this module, so the two never spell it differently.
 
 // The classification labels a filing's kind is read from, in precedence order: a breaking change is
 // named as one whatever else it is.
@@ -25,13 +25,18 @@ interface Filed {
 	title: string
 	// The lane child that was working when the Issue was filed, when the filing came from one.
 	found_during: string | undefined
+	// A run's own session filed it — the parent holding the run's hold or a lane child — rather than one
+	// outside the run sharing the repository's stream (joshuafolkken/kit#4099). An event written before
+	// the mark was recorded reads as filed outside.
+	is_run?: boolean | undefined
 }
 
 // The kind slot is always written, `[<label>]` or `[]`, against the reference with no space: an event
 // written before the kind always has the space there, so no title, whatever it opens with, reads as a
-// kind.
+// kind. The run's mark follows the kind slot, again with no space.
+const RUN_MARK = '[run]'
 const TEXT_PATTERN = new RegExp(
-	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\])? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
+	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\](?<run>\[run\])?)? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
 	'u',
 )
 
@@ -41,7 +46,7 @@ function kind_of(labels: ReadonlyArray<string>): FiledKind | undefined {
 }
 
 function text_of(filed: Filed): string {
-	const kind = `[${filed.kind ?? ''}]`
+	const kind = `[${filed.kind ?? ''}]${filed.is_run === true ? RUN_MARK : ''}`
 	const suffix =
 		filed.found_during === undefined
 			? ''
@@ -60,6 +65,7 @@ function parse(text: string): Filed | undefined {
 		kind: KINDS.find((kind) => kind === groups['kind']),
 		title: String(groups['title']),
 		found_during: groups['during'],
+		is_run: groups['run'] !== undefined,
 	}
 }
 

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

@@ -1,3 +1,4 @@
+import { MS_PER_MINUTE, MS_PER_SECOND } from '#scripts/lib/timeouts'
 import type { StreamRead } from './run-event-stream'
 
 // The follow read behind `josh run:event --follow` and `--watch`. A reader
@@ -24,10 +25,8 @@ import type { StreamRead } from './run-event-stream'
 // 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_INTERVAL_MS = FOLLOW_INTERVAL_MINUTES * MS_PER_MINUTE
 const FOLLOW_TICK_MS = MS_PER_SECOND
 
 interface FollowPorts {

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

@@ -1,3 +1,4 @@
+import { figure_format } from '#scripts/lib/figure-format'
 import type { EventKind, RunEvent } from './run-event-stream'
 
 // One run event as the line a person reads in the watch pane. The pane is a script, not a session, so
@@ -10,8 +11,6 @@ import type { EventKind, RunEvent } from './run-event-stream'
 
 const JA = 'ja'
 const FIELD_SEPARATOR = ' · '
-const CLOCK_WIDTH = 2
-const CLOCK_PAD = '0'
 
 interface KindLabel {
 	ja: string
@@ -29,6 +28,7 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	cut: { ja: 'セッション交代', en: 'session cut' },
 	resume: { ja: '実装を再開', en: 'implementation resumed' },
 	restart: { ja: '止めて出し直し', en: 'restarted' },
+	withdraw: { ja: '取り下げ', en: 'withdrawn' },
 	drain: { ja: 'バックログが空', en: 'backlog drained' },
 	stop: { ja: '停止', en: 'stopped' },
 	'pr-opened': { ja: 'PR 作成', en: 'PR opened' },
@@ -47,6 +47,9 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	'lane-limit': { ja: 'レーン上限', en: 'lane limit' },
 	setup: { ja: '準備', en: 'setup' },
 	'pr-checks': { ja: 'PR のチェック', en: 'PR checks' },
+	'idle-notice': { ja: '待機の通知', en: 'idle notice' },
+	'lane-state': { ja: 'レーンの状態', en: 'lane state' },
+	'paused-notice': { ja: '一時停止の通知', en: 'paused notice' },
 }
 
 const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))
@@ -59,18 +62,12 @@ function label_of(kind: string, lang: string): string {
 	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
+	const ms = new Date(at).getTime()
 
-	return `${two_digits(date.getHours())}:${two_digits(date.getMinutes())}`
+	return Number.isNaN(ms) ? at : figure_format.minute_of(ms)
 }
 
 function render(event: RunEvent, lang: string): string {

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

@@ -94,6 +94,7 @@ const KIND = run_event_stream.EVENT_KIND
 const BATCH_RECORD_KINDS: ReadonlySet<string> = new Set([
 	KIND.CHILD_LAUNCH,
 	KIND.RESTART,
+	KIND.WITHDRAW,
 	KIND.PARK,
 	KIND.SPLIT,
 	KIND.RETROSPECTIVE,
@@ -113,7 +114,7 @@ function is_own_ship_event(event: RunEvent, issue: string): boolean {
 }
 
 // The issue an event's text names, the way every reader here — and `run:board` — keys an event to a child.
-function issue_named(event: RunEvent): string | undefined {
+function issue_named(event: Pick<RunEvent, 'text'>): string | undefined {
 	return ISSUE_REFERENCE.exec(event.text)?.[1]
 }
 
@@ -167,12 +168,14 @@ function last_issue_event(
 }
 
 // A child's launch and the endings `run:merge` settles it with — the ones `run:board` stops drawing it
-// running on. A park or a split already ran `run:merge`, so a child closed after one owes nothing.
+// running on. A park or a split already ran `run:merge`, so a child closed after one owes nothing; a
+// withdrawal settles the child itself, its issue left open for the next run.
 const LAUNCH_OR_SETTLE_KINDS: ReadonlySet<string> = new Set([
 	KIND.CHILD_LAUNCH,
 	KIND.MERGE,
 	KIND.PARK,
 	KIND.SPLIT,
+	KIND.WITHDRAW,
 ])
 
 // Whether this invocation's newest launch of the issue has not yet been settled.
@@ -186,9 +189,24 @@ function is_merge_owed(events: ReadonlyArray<RunEvent>, scope: EventScope, issue
 	return newest?.kind === KIND.CHILD_LAUNCH
 }
 
+function is_launch_or_withdrawal(event: RunEvent, issue: string): boolean {
+	const is_kind = event.kind === KIND.CHILD_LAUNCH || event.kind === KIND.WITHDRAW
+
+	return is_kind && names_issue(event, issue)
+}
+
+// Whether a person withdrew the issue's newest launch (`lane:withdraw`): its newest launch or withdrawal
+// is a withdrawal. A launch after it is a fresh attempt, which the old withdrawal does not settle.
+function is_withdrawn(events: ReadonlyArray<RunEvent>, issue: string): boolean {
+	const newest = events.findLast((event) => is_launch_or_withdrawal(event, issue))
+
+	return newest?.kind === KIND.WITHDRAW
+}
+
 const run_event_scope = {
 	UNKNOWN_EVENT_SCOPE,
 	is_merge_owed,
+	is_withdrawn,
 	issue_named,
 	last_issue_event,
 	last_scoped_event,

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

@@ -1,7 +1,9 @@
+import { lane_state, type LaneStateRecord } from '#scripts/lane/lane-state'
 import { error_text } from '#scripts/lib/error-message'
+import { run_board_lane_time } from '#scripts/run/board/run-board-lane-time'
 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'
+import { run_event_stream, type AppendResult, type RunEvent } from './run-event-stream'
 
 // 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
@@ -27,17 +29,66 @@ async function stream_target(): Promise<string | undefined> {
 	return repository === undefined ? undefined : run_event_stream.target_of(repository)
 }
 
+// The child's lane record; an unreadable one reads as none, so the ending is still written.
+async function lane_record(issue: string): Promise<LaneStateRecord | undefined> {
+	try {
+		return await lane_state.read_state(issue)
+	} catch (error) {
+		error_text.trace_swallowed('run_event_stream_emit.lane_record', error)
+
+		return undefined
+	}
+}
+
+async function ending_fields(
+	target: string,
+	event: Omit<RunEvent, 'pos'>,
+): Promise<Pick<RunEvent, 'elapsed_ms'>> {
+	const issue = run_event_scope.issue_named(event)
+
+	if (issue === undefined || !run_board_lane_time.OFF_LANE_KINDS.has(event.kind)) return {}
+
+	const elapsed_ms = run_board_lane_time.ending_elapsed({
+		events: run_event_stream.read_events(target),
+		issue: Number(issue),
+		record: await lane_record(issue),
+		ended_ms: Date.parse(event.at),
+	})
+
+	return elapsed_ms === undefined ? {} : { elapsed_ms }
+}
+
+/**
+ * Append one event at `at`, an ending with its child's lane time (joshuafolkken/kit#4481). Every writer
+ * of an ending — `emit` and `run:event --append` — appends through here, so the time is computed once,
+ * as the ending is written, with the board's own count.
+ */
+async function append_at(
+	target: string,
+	kind: string,
+	text: string,
+	at: Date,
+): Promise<AppendResult> {
+	const event = { kind, text, at: at.toISOString() }
+
+	return run_event_stream.append_event(target, {
+		...event,
+		...(await ending_fields(target, event)),
+	})
+}
+
 /**
  * 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.
+ * `at` is the caller's instant where another record must carry the same one.
  */
-async function emit(kind: string, text: string): Promise<void> {
+async function emit(kind: string, text: string, at: Date = new Date()): Promise<void> {
 	try {
 		const target = await stream_target()
 
 		if (target === undefined) return
 
-		run_event_stream.append(target, kind, text, now_iso())
+		await append_at(target, kind, text, at)
 	} catch {
 		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
 	}
@@ -85,37 +136,51 @@ 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. `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.
+ * `reset_kind`. The text is composed only once the episode is new, so a caller polled every pass whose
+ * text costs a network read pays it once. Returns the appended text, or `undefined` when nothing was.
  */
-async function emit_once_since(kind: string, text: string, reset_kind: string): Promise<boolean> {
+async function emit_once_since_with(
+	kind: string,
+	reset_kind: string,
+	compose: () => Promise<string>,
+): Promise<string | undefined> {
 	try {
 		const repository = await run_carry.repository_directory()
 
-		if (repository === undefined) return false
+		if (repository === undefined) return undefined
 
 		const target = run_event_stream.target_of(repository)
 
 		if (run_event_stream.has_since(invocation_events(repository, target), kind, reset_kind)) {
-			return false
+			return undefined
 		}
 
-		return run_event_stream.append(target, kind, text, now_iso()).appended
+		const text = await compose()
+
+		return run_event_stream.append(target, kind, text, now_iso()).appended ? text : undefined
 	} catch (error) {
 		// Best-effort: a failed append is dropped rather than raised into the caller's work.
 		error_text.trace_swallowed('run_event_stream_emit.emit_once_since', error)
 
-		return false
+		return undefined
 	}
 }
 
+// `emit_once_since_with` for a text already in hand. Returns whether it appended, as `emit_once` does.
+async function emit_once_since(kind: string, text: string, reset_kind: string): Promise<boolean> {
+	const appended = await emit_once_since_with(kind, reset_kind, async () => text)
+
+	return appended !== undefined
+}
+
 // 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`). Fail-quiet like the writers: no repository or an unreadable stream is an empty
-// invocation.
+// (`backlog:drive`). Fail-quiet like the writers: no repository, an unreadable stream or an
+// undetermined scope is an empty invocation.
 async function current_events(): Promise<ReadonlyArray<RunEvent>> {
 	try {
 		const repository = await run_carry.repository_directory()
@@ -161,11 +226,13 @@ async function all_events(): Promise<ReadonlyArray<RunEvent>> {
 
 const run_event_stream_emit = {
 	all_events,
+	append_at,
 	current_events,
 	emit,
 	emit_heartbeat,
 	emit_once,
 	emit_once_since,
+	emit_once_since_with,
 	invocation_or_all_events,
 	stream_target,
 }

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

@@ -29,10 +29,11 @@ const EVENT_PREFIX = 'josh-run-events-'
 // every reader — a person, an editor — that it is a line stream rather than a single document, the same
 // distinction the ambient `.log` draws.
 const EVENT_SUFFIX = '.jsonl'
-// A run's session-facing events over one unattended night: 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.
-const EVENT_CAP = 500
+// A week of a busy run's events, so `josh lane:stats --period 7` reads the parks that end a stop's wait
+// and `run:board` keeps every ship stage (joshuafolkken/kit#3997). A four-lane `backlogrun` wrote about
+// 75 events an hour (1,877 in 25 hours), so fifteen thousand holds about eight days at that rate and
+// still bounds the file to a few megabytes — past it the oldest events roll off.
+const EVENT_CAP = 15_000
 const FIRST_POSITION = 0
 const POSITION_INCREMENT = 1
 const LINE_SEPARATOR = '\n'
@@ -64,6 +65,10 @@ const EVENT_KIND = {
 	// (`lane:restart`). It follows the fresh dispatch's `CHILD_LAUNCH`, so it is a launch to the parent and
 	// the board, and — like that launch — a batch record a lane child never reads as its own position.
 	RESTART: 'restart',
+	// A person withdrew a lane child — stopped it and left its issue open for the next run (`lane:withdraw`).
+	// It is written before the stop, so `run:merge` settles the child as withdrawn whatever GitHub says
+	// by the time the parent collects it, and counts it as neither a merge, a failure nor an outage.
+	WITHDRAW: 'withdraw',
 	// 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
@@ -139,6 +144,19 @@ const EVENT_KIND = {
 	// in followup without asking GitHub (joshuafolkken/kit#3770). A trace: it says how the checks stand,
 	// not where the run is.
 	PR_CHECKS: 'pr-checks',
+	// `backlog:drive` reached a watch with no child running and nothing to dispatch — the point a person's
+	// hand is wanted. Emitted once per idle episode (`emit_once_since_with`, reset by `CHILD_LAUNCH`), it
+	// is the dedup marker for the one idle Telegram. A trace: a drain's retrospective is read off the
+	// position beneath it, so the marker must not stand over it.
+	IDLE_NOTICE: 'idle-notice',
+	// A person paused or resumed a lane child (`lane:pause` / `lane:resume`), so who halted a lane and
+	// when is on the stream rather than only in a shell history (joshuafolkken/kit#4268). A trace: it
+	// says what a lane's processes were told, not where the run is.
+	LANE_STATE: 'lane-state',
+	// `backlog:drive` found nothing of the run in flight and only paused lanes left, paused past the
+	// silent window (joshuafolkken/kit#4270). Emitted once per pause episode (`emit_once_since_with`,
+	// reset by `LANE_STATE`), it is the dedup marker for the one paused-lane Telegram. A trace.
+	PAUSED_NOTICE: 'paused-notice',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -158,6 +176,9 @@ const TRACE_KINDS: ReadonlySet<string> = new Set([
 	EVENT_KIND.LANE_LIMIT,
 	EVENT_KIND.SETUP,
 	EVENT_KIND.PR_CHECKS,
+	EVENT_KIND.IDLE_NOTICE,
+	EVENT_KIND.LANE_STATE,
+	EVENT_KIND.PAUSED_NOTICE,
 ])
 
 // The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
@@ -177,6 +198,9 @@ const event_schema = z.object({
 	at: z.string(),
 	kind: z.string(),
 	text: z.string(),
+	// The child's time on a lane, recorded once by the writer of an ending (joshuafolkken/kit#4481), so a
+	// reader never has to find its launch again. An event written before it has none.
+	elapsed_ms: z.number().optional(),
 })
 
 type RunEvent = z.infer<typeof event_schema>
@@ -342,12 +366,12 @@ function append_held(target: string, event: Omit<RunEvent, 'pos'>): number {
  * 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 }
+function append_event(target: string, event: Omit<RunEvent, 'pos'>): AppendResult {
+	if (!is_event_kind(event.kind)) return { appended: false, position: FIRST_POSITION }
 
 	const lock = `${target}${LOCK_SUFFIX}`
 	const position = repository_lock.with_lock_sync(
-		() => append_held(target, { at, kind, text }),
+		() => append_held(target, event),
 		lock,
 		LOCK_WAIT_MS,
 	)
@@ -362,6 +386,11 @@ function append(target: string, kind: string, text: string, at: string): AppendR
 	return { appended: true, position }
 }
 
+// `append_event` for an event that records nothing beyond its kind, text and instant.
+function append(target: string, kind: string, text: string, at: string): AppendResult {
+	return append_event(target, { at, kind, text })
+}
+
 /**
  * Every event after `position`, in order, and the position a reader passes back next time.
  *
@@ -411,6 +440,7 @@ const run_event_stream = {
 	EVENT_KINDS,
 	TRACE_KINDS,
 	append,
+	append_event,
 	format_event,
 	has_since,
 	is_stage_start,