@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/run/board/run-board-thanks-csv.ts

@@ -0,0 +1,71 @@
+import { parse } from 'csv-parse/sync'
+import { run_board_render_title } from './run-board-render-title'
+
+// The reviewers who helped kit, read off the published roster's CSV. The roster is a spreadsheet anyone
+// with edit access changes, so nothing in it is trusted as drawn: a sheet whose header is not `name,url`
+// is not the roster, a row without a name or with a link that is not `https://` is dropped, and a name
+// loses every control character — an escape in a cell would otherwise be written to the terminal as one.
+
+const HEADER = ['name', 'url'] as const
+// Enough for any person's or project's name, short enough that one cell cannot fill the line; a
+// longer one is cut to an ellipsis, as a row's title is.
+const NAME_LIMIT = 40
+const CONTROL = /\p{Cc}/gu
+const SAFE_URL = /^https:\/\/[^\s\p{Cc}]+$/u
+
+interface Thanker {
+	name: string
+	// The page the name opens; `undefined` draws the name unlinked.
+	url: string | undefined
+}
+
+type Thanks = ReadonlyArray<Thanker>
+
+function name_of(cell: string): string {
+	return run_board_render_title.title_of(cell.replaceAll(CONTROL, '').trim(), NAME_LIMIT)
+}
+
+// An empty cell is a name without a link; any other value has to be a whole `https://` URL.
+function url_of(cell: string): string | undefined | false {
+	const url = cell.trim()
+
+	if (url === '') return undefined
+
+	return SAFE_URL.test(url) && URL.canParse(url) ? url : false
+}
+
+function thanker_of(row: ReadonlyArray<string>): Array<Thanker> {
+	const [name_cell = '', url_cell = ''] = row
+	const name = name_of(name_cell)
+	const url = url_of(url_cell)
+
+	if (name === '' || url === false) return []
+
+	return [{ name, url }]
+}
+
+function is_roster(header: ReadonlyArray<string> | undefined): boolean {
+	return header?.length === HEADER.length && HEADER.every((cell, index) => header[index] === cell)
+}
+
+function rows_of(csv: string): Array<Array<string>> | undefined {
+	try {
+		return parse(csv, { relax_column_count: true, skip_empty_lines: true, bom: true })
+	} catch {
+		return undefined
+	}
+}
+
+// `undefined` for a text that is not the roster, so a failed read is told apart from an empty roster.
+function thanks_of(csv: string): Thanks | undefined {
+	const [header, ...rows] = rows_of(csv) ?? []
+
+	if (!is_roster(header)) return undefined
+
+	return rows.flatMap((row) => thanker_of(row))
+}
+
+const run_board_thanks_csv = { NAME_LIMIT, thanks_of }
+
+export { run_board_thanks_csv }
+export type { Thanker, Thanks }

package/scripts/run/board/run-board-thanks-read.ts

@@ -0,0 +1,112 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { timed_fetch } from '#scripts/lib/timed-fetch'
+import { run_progress } from '#scripts/run/progress/run-progress'
+import { z } from 'zod'
+import { run_board_thanks_csv, type Thanks } from './run-board-thanks-csv'
+
+// The roster `run:board` thanks its reviewers from: a Google spreadsheet published as CSV, changed
+// apart from any build or release, so it is read at run time. Its answer is kept in the project's
+// record beside the board's other state and reused for five minutes — Google's own cache holds it as
+// long — so neither a redraw nor a fresh `--once` asks again inside that window. A read that fails
+// keeps the last answer, and with none draws no line; nothing about the failure reaches the screen.
+
+const ROSTER_URL =
+	'https://docs.google.com/spreadsheets/d/e/2PACX-1vR8Ia38Wiw6Kfyk9Or594J8ZRS8okynV30CpOtq5B6_GyJG7A1-t8Au64jTYvmzgIOlbafcKKgrNFVJ/pub?gid=0&single=true&output=csv'
+const RECORD_PREFIX = 'josh-run-board-thanks-'
+const TTL_MINUTES = 5
+const TTL_MS = TTL_MINUTES * run_progress.MS_PER_MINUTE
+
+const thanker_schema = z.object({ name: z.string(), url: z.string().optional() })
+const record_schema = z.object({ checked_ms: z.number(), thanks: z.array(thanker_schema) })
+
+interface ThanksRecord {
+	checked_ms: number
+	thanks: Thanks
+}
+
+// What the read works through, injected in tests.
+interface ThanksDependencies {
+	fetch_text: () => Promise<string>
+	record_path: string
+	now: () => number
+}
+
+function read_record(record_path: string): ThanksRecord | undefined {
+	const raw = stamp_file.read_stamp_text(record_path)
+	const parsed = raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+
+	if (parsed === undefined) return undefined
+
+	return {
+		checked_ms: parsed.checked_ms,
+		thanks: parsed.thanks.map(({ name, url }) => ({ name, url })),
+	}
+}
+
+// A record that cannot be written leaves the next read to ask again — never a reason to fail the board.
+function write_record(record_path: string, record: ThanksRecord): void {
+	try {
+		stamp_file.replace_stamp(record_path, record)
+	} catch {
+		// The board draws what it read either way.
+	}
+}
+
+async function fetch_roster(read: () => Promise<string>): Promise<Thanks | undefined> {
+	try {
+		return run_board_thanks_csv.thanks_of(await read())
+	} catch {
+		return undefined
+	}
+}
+
+// The recorded roster while it is younger than the record's life; `undefined` once it is stale. A
+// record dated after now — the clock stepped back — is stale too, or it would hold until the clock
+// caught up with it.
+function fresh_thanks(record: ThanksRecord | undefined, now_ms: number): Thanks | undefined {
+	if (record === undefined) return undefined
+
+	const age_ms = now_ms - record.checked_ms
+
+	return age_ms >= 0 && age_ms < TTL_MS ? record.thanks : undefined
+}
+
+// A response that is not a success is a failed read, so its body is never taken for the roster.
+async function fetch_text(): Promise<string> {
+	const response = await timed_fetch(ROSTER_URL)
+
+	if (!response.ok) throw new Error(`roster read answered ${String(response.status)}`)
+
+	return await response.text()
+}
+
+const LIVE_DEPS: ThanksDependencies = {
+	fetch_text,
+	record_path: stamp_file.stamp_path(RECORD_PREFIX, PROJECT_ROOT),
+	now: () => Date.now(),
+}
+
+async function read_with(deps: ThanksDependencies): Promise<Thanks> {
+	const now_ms = deps.now()
+	const record = read_record(deps.record_path)
+	const fresh = fresh_thanks(record, now_ms)
+
+	if (fresh !== undefined) return fresh
+
+	const thanks = (await fetch_roster(deps.fetch_text)) ?? record?.thanks ?? []
+
+	write_record(deps.record_path, { checked_ms: now_ms, thanks })
+
+	return thanks
+}
+
+async function read_thanks(deps: ThanksDependencies = LIVE_DEPS): Promise<Thanks> {
+	return await read_with(deps)
+}
+
+const run_board_thanks_read = { TTL_MS, read_thanks }
+
+export { run_board_thanks_read }
+export type { ThanksDependencies }

package/scripts/run/board/run-board-thanks.ts

@@ -0,0 +1,53 @@
+import { run_board_fetch, type Fetch } from './run-board-fetch'
+import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
+import type { Thanks } from './run-board-thanks-csv'
+import { run_board_thanks_read } from './run-board-thanks-read'
+
+// The reviewers' roster a `run:board` redraw draws above its legend. Like the GitHub reads
+// (`run-board-github.ts`), **a live board never waits on it**: the read is launched and folded in on
+// the redraw after it lands; one plain frame waits for it. It is launched again no sooner than the
+// roster's own record goes stale. A board with no `read_thanks` port — the chat frame — reads none and
+// draws none.
+
+const { TTL_MS } = run_board_thanks_read
+const { is_due } = run_board_state
+
+type ThanksState = Pick<BoardState, 'thanks' | 'thanks_fetch' | 'thanks_attempted_ms'>
+
+function launch_thanks(state: BoardState, ports: BoardPorts, now_ms: number): BoardState {
+	const { read_thanks } = ports
+
+	if (read_thanks === undefined || state.thanks_fetch !== undefined) return state
+	if (!is_due(state.thanks_attempted_ms, TTL_MS, now_ms)) return state
+
+	const thanks_fetch: Fetch<Thanks> = run_board_fetch.launch(read_thanks, state.thanks)
+
+	return { ...state, thanks_fetch, thanks_attempted_ms: now_ms }
+}
+
+function fold_thanks(state: BoardState): BoardState {
+	const answer = state.thanks_fetch?.answer()
+
+	if (answer === undefined) return state
+
+	return { ...state, thanks: answer.value, thanks_fetch: undefined }
+}
+
+// Folds what landed and launches what is due; at the `settled` pace, waits for it to land.
+async function gather_thanks(
+	state: BoardState,
+	ports: BoardPorts,
+	now_ms: number,
+	pace: Pace,
+): Promise<BoardState> {
+	const launched = launch_thanks(fold_thanks(state), ports, now_ms)
+
+	if (pace === 'settled' && launched.thanks_fetch !== undefined) await launched.thanks_fetch.landed
+
+	return fold_thanks(launched)
+}
+
+const run_board_thanks = { gather_thanks }
+
+export { run_board_thanks }
+export type { ThanksState }

package/scripts/run/board/run-board-tick.ts

@@ -8,10 +8,12 @@ import { run_board_link } from './run-board-link'
 import { run_board_machine } from './run-board-machine'
 import { run_board_notes, type Titles } from './run-board-notes'
 import type { LocalRead } from './run-board-read'
+import { run_board_reason } from './run-board-reason'
 import { run_board_render, type FrameBounds } from './run-board-render'
 import { run_board_spin, type Spun } from './run-board-spin'
 import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
 import { run_board_status, type RunActivity } from './run-board-status'
+import { run_board_thanks } from './run-board-thanks'
 import { run_board_usage } from './run-board-usage'
 
 // One `run:board` redraw. **Three speeds**: the frame is redrawn once a second, on the second, so
@@ -30,6 +32,7 @@ const LOCAL_READ_SECONDS = 5
 const LOCAL_READ_MS = LOCAL_READ_SECONDS * run_progress.MS_PER_SECOND
 const { FRESH_STATE, is_due } = run_board_state
 const { PLAN_RETRY_MS, gather_github, statuses_for } = run_board_github
+const { gather_thanks } = run_board_thanks
 
 async function reread(state: BoardState, ports: BoardPorts, now_ms: number): Promise<BoardState> {
 	if (!is_due(state.read_ms, LOCAL_READ_MS, now_ms)) return state
@@ -88,17 +91,17 @@ function titles_of(state: BoardState): Titles {
 	return with_closed(state.plan, state.closed).context.titles
 }
 
-// The statuses scoped to the run's plan, a running child the plan's listing no longer holds settled.
-// Before the plan is read, the run's own children alone.
-function layout_for(state: BoardState, local: LocalRead): BoardLayout {
-	const { plan, closed } = state
-
-	if (plan === undefined) {
-		return run_board_layout.local_layout_of(
-			run_board_status.statuses_of(local.events, local.lanes, new Set()),
-		)
-	}
+// A run `run:carry --end` closed and one nobody drives any more are both drawn as stopped.
+function activity_here(local: LocalRead): RunActivity {
+	return run_board_status.activity_of(
+		local.events,
+		local.ended_ms !== undefined || local.is_stranded,
+	)
+}
 
+// The plan laid under its statuses, each waiting row saying why it waits.
+function planned_layout(state: BoardState, plan: BoardPlan, local: LocalRead): BoardLayout {
+	const { closed } = state
 	const read = {
 		open_numbers: plan.context.open_numbers,
 		read_ms: state.fetched_ms,
@@ -106,8 +109,25 @@ function layout_for(state: BoardState, local: LocalRead): BoardLayout {
 		labels: plan.labels,
 	}
 	const statuses = run_board_status.settle_closed(statuses_for(plan, local), read)
+	const reason_of = run_board_reason.reader({
+		plan,
+		statuses,
+		events: local.events,
+		free_lanes: local.free_lanes,
+		is_stopped: activity_here(local).is_stopped,
+	})
 
-	return run_board_layout.layout_of(with_closed(plan, closed), statuses)
+	return run_board_layout.layout_of(with_closed(plan, closed), statuses, reason_of)
+}
+
+// The statuses scoped to the run's plan, a running child the plan's listing no longer holds settled.
+// Before the plan is read, the run's own children alone.
+function layout_for(state: BoardState, local: LocalRead): BoardLayout {
+	if (state.plan !== undefined) return planned_layout(state, state.plan, local)
+
+	return run_board_layout.local_layout_of(
+		run_board_status.statuses_of(local.events, local.lanes, new Set()),
+	)
 }
 
 // What one redraw draws with.
@@ -116,12 +136,20 @@ interface Redraw {
 	now_ms: number
 }
 
-// A run `run:carry --end` closed and one nobody drives any more are both drawn as stopped.
-function activity_here(local: LocalRead): RunActivity {
-	return run_board_status.activity_of(
-		local.events,
-		local.ended_ms !== undefined || local.is_stranded,
-	)
+// What the header reads off the local read.
+type LocalHeader = Pick<
+	BoardHeader,
+	'started_ms' | 'ended_ms' | 'activity' | 'operations' | 'usual'
+>
+
+function local_header(local: LocalRead): LocalHeader {
+	return {
+		started_ms: local.started_ms,
+		ended_ms: local.ended_ms,
+		activity: activity_here(local),
+		operations: local.operations,
+		usual: local.usual,
+	}
 }
 
 function header_of(
@@ -132,9 +160,7 @@ function header_of(
 ): BoardHeader {
 	return {
 		now_ms: redraw.now_ms,
-		started_ms: local.started_ms,
-		ended_ms: local.ended_ms,
-		activity: activity_here(local),
+		...local_header(local),
 		layout,
 		baseline_total: state.baseline_total,
 		plan_fetched_ms: state.fetched_ms,
@@ -161,6 +187,8 @@ function frame_of(state: BoardState, local: LocalRead, layout: BoardLayout, redr
 		header: header_of(state, local, layout, redraw),
 		notes: run_board_notes.notes_of(local.events, titles_of(state)),
 		resume: local.resume,
+		thanks: state.thanks,
+		link: redraw.ports.link,
 		...bounds,
 	})
 
@@ -203,8 +231,9 @@ async function tick(
 	}
 
 	const gathered = await gather_github(state_for(read, local), { ports, local, now_ms, pace })
+	const thanked = await gather_thanks(gathered, ports, now_ms, pace)
 
-	return draw_run(await resample(gathered, ports, now_ms), local, { ports, now_ms })
+	return draw_run(await resample(thanked, ports, now_ms), local, { ports, now_ms })
 }
 
 const run_board_tick = {

package/scripts/run/board/run-board-usual.ts

@@ -0,0 +1,44 @@
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { lane_stage_stats } from '#scripts/lane/lane-stage-stats'
+import { run_board_phase, type Phase } from './run-board-phase'
+
+// How long each phase usually takes: the lane ledger's median of the stage the phase is
+// (`lane-stage-stats.ts`), so a running child that has stood at its phase far longer stands out
+// (joshuafolkken/kit#3769). A phase is a `josh ship` stage under the names `run-board-phase.ts` gives
+// them, and `implement` is the ledger's derived one. A phase no stage records — `investigate`, `plan`,
+// `failed` — has no usual time, and is never drawn as long.
+
+type UsualTimes = ReadonlyMap<Phase, number>
+
+const IMPLEMENT_PHASE: Phase = 'implement'
+
+// Each phase's ledger stage, from the stage-to-phase names a row's phase is drawn with. The ledger's
+// `implement` runs from the dispatch, so it also holds the investigation and the plan the row draws
+// before its `implement` phase: the usual time is the longer, which can only draw a phase as long
+// later, never sooner.
+const PHASE_STAGES: ReadonlyArray<readonly [string, Phase | undefined]> = [
+	[lane_stage_stats.IMPLEMENT, IMPLEMENT_PHASE],
+	...Object.entries(run_board_phase.SHIP_PHASES),
+]
+
+function usual_of(entries: ReadonlyArray<LedgerEntry>): UsualTimes {
+	const medians = lane_stage_stats.medians(entries)
+
+	return new Map(
+		PHASE_STAGES.flatMap(([stage, phase]) => {
+			const median = medians.get(stage)
+
+			return phase === undefined || median === undefined ? [] : [[phase, median] as const]
+		}),
+	)
+}
+
+// The repository's whole ledger, read where the board reads its stream; an absent one has no usual time.
+function read(repository: string): UsualTimes {
+	return usual_of(lane_ledger.read_entries(lane_ledger.target_of(repository)))
+}
+
+const run_board_usual = { read, usual_of }
+
+export { run_board_usual }
+export type { UsualTimes }

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

@@ -1,5 +1,6 @@
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
 
@@ -178,6 +179,13 @@ function group_count(values: ParsedValues): number {
 	return groups.filter(Boolean).length
 }
 
+// The mark rides the environment the run launched its session with; the record keeps it beside the
+// owner, so `josh backlogrun --stop` knows that owner for the run's own. An attached owner is left as
+// it is, so its record is the one it always was.
+function marked(owner: CarryOwner): CarryOwner {
+	return run_headless.is_headless_parent(process.env) ? { ...owner, is_headless: true } : owner
+}
+
 // **`--owner` is what makes liveness answerable at all.** The process that runs this command is a
 // short-lived `tsx`, so its own pid says nothing about whether the run is still going; the caller
 // names the process that is — its own session — and a `backlogrun` passes `--owner "$PPID"`. Absent,
@@ -192,7 +200,7 @@ function to_owner(value: OptionValue): CarryOwner | undefined {
 
 	const pid = Number(text)
 
-	return pid < MIN_PID ? undefined : run_carry.owner_of(pid)
+	return pid < MIN_PID ? undefined : marked(run_carry.owner_of(pid))
 }
 
 // A non-empty `--summary`, or nothing. An empty string is nothing here, so it reads as absent and the

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

@@ -6,10 +6,8 @@ import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { run_event_setup } from '#scripts/run/event/run-event-setup'
 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_merge_collect } from '#scripts/run/merge/run-merge-collect'
 import { run_cli_fault } from '#scripts/run/run-cli-fault'
 import { run_headless } from '#scripts/run/run-headless'
-import { run_stop_notify } from '#scripts/run/run-stop-notify'
 import {
 	run_carry,
 	type CarryClaim,
@@ -19,8 +17,7 @@ import {
 } from './run-carry'
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
 import { run_carry_conversation } from './run-carry-conversation'
-import { run_carry_ended } from './run-carry-ended'
-import { run_carry_stash } from './run-carry-stash'
+import { run_carry_end } from './run-carry-end'
 
 // `josh run:carry` — the record that carries one invocation's budget across its own session cuts.
 // A `backlogrun` begins it, counts a merge and a filing into it, marks each
@@ -316,52 +313,12 @@ async function count(
 	return report_carry(COUNTED_VERDICT, carry, is_json)
 }
 
-// **A stop over a record that is still there pushes one ⏸️ confirmation before the record goes**.
-// `plan` is read from the record `--end` is about to remove, so the second `--end` reads `none` and
-// plans nothing — one stop never notifies twice. A clean `--end` passes no reason and stays silent,
-// because a completed run has its own notification. The closed-issue stash report
-// (`run-carry-stash.ts`) is once per invocation on the same read.
-async function report_end(read: CarryRead): Promise<void> {
-	if (read.kind === 'none') return
-
-	await run_carry_stash.report_orphans()
-}
-
-// Best-effort: the board's record of the ended run never stands between `--end` and the carry record it
-// clears, so a failed write goes to stderr rather than leaving the run carried.
-function keep_ended(directory: string, read: CarryRead, stopped: string | undefined): void {
-	try {
-		run_carry_ended.record_ended(run_carry_ended.ended_path(directory), read, new Date(), stopped)
-	} catch (error) {
-		console.error(`run:carry: the ended run was not recorded for run:board: ${String(error)}`)
-	}
-}
-
-// The record goes, and the run it held stays readable as the last ended run, so `run:board` keeps the
-// finished run on screen until the next one begins — a stopped one with the session to resume it from.
-function close_record(directory: string, stopped: string | undefined): CarryRead {
-	const target = run_carry.carry_path(directory)
-	const read = run_carry.read_carry(target)
-
-	keep_ended(directory, read, stopped)
-	run_carry.end_carry(target)
-
-	return read
-}
-
-// The merges the run ended with are recorded while its record can still count them.
 async function finish(
 	directory: string,
 	stopped: string | undefined,
 	is_json: boolean,
 ): Promise<number> {
-	await run_merge_collect.collect_merged(directory)
-	const read = close_record(directory, stopped)
-	const notice = run_stop_notify.plan(read, stopped)
-
-	if (notice !== undefined) await run_stop_notify.announce(notice)
-
-	await report_end(read)
+	const read = await run_carry_end.end_run(directory, { stopped, is_announced: true })
 
 	if (read.kind === 'none') return report(NONE_VERDICT, undefined, is_json, SUCCESS_EXIT_CODE)
 

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

@@ -0,0 +1,73 @@
+import { run_merge_collect } from '#scripts/run/merge/run-merge-collect'
+import { run_stop_notify } from '#scripts/run/run-stop-notify'
+import { run_carry, type CarryRead } from './run-carry'
+import { run_carry_ended } from './run-carry-ended'
+import { run_carry_stash } from './run-carry-stash'
+
+// Ending a run's record, apart from the command that prints the verdict: `run:carry --end` and
+// `josh backlogrun --stop` both end it here, so the one end is never written twice.
+
+interface EndRequest {
+	// Why the run stopped; `undefined` is a clean finish.
+	stopped: string | undefined
+	// Whether a stop pushes its ⏸️ confirmation. A person who typed the stop is already at the terminal.
+	is_announced: boolean
+}
+
+// **A stop over a record that is still there pushes one ⏸️ confirmation before the record goes**.
+// `plan` is read from the record the end is about to remove, so the second end reads `none` and
+// plans nothing — one stop never notifies twice. A clean end passes no reason and stays silent,
+// because a completed run has its own notification.
+async function announce_stop(read: CarryRead, request: EndRequest): Promise<void> {
+	if (!request.is_announced) return
+
+	const notice = run_stop_notify.plan(read, request.stopped)
+
+	if (notice !== undefined) await run_stop_notify.announce(notice)
+}
+
+// The closed-issue stash report (`run-carry-stash.ts`) is once per invocation on the same read.
+async function report_end(read: CarryRead): Promise<void> {
+	if (read.kind === 'none') return
+
+	await run_carry_stash.report_orphans()
+}
+
+// Best-effort: the board's record of the ended run never stands between the end and the carry record it
+// clears, so a failed write goes to stderr rather than leaving the run carried.
+function keep_ended(directory: string, read: CarryRead, stopped: string | undefined): void {
+	try {
+		run_carry_ended.record_ended(run_carry_ended.ended_path(directory), read, new Date(), stopped)
+	} catch (error) {
+		console.error(`run:carry: the ended run was not recorded for run:board: ${String(error)}`)
+	}
+}
+
+// The record goes, and the run it held stays readable as the last ended run, so `run:board` keeps the
+// finished run on screen until the next one begins — a stopped one with the session to resume it from.
+function close_record(directory: string, stopped: string | undefined): CarryRead {
+	const target = run_carry.carry_path(directory)
+	const read = run_carry.read_carry(target)
+
+	keep_ended(directory, read, stopped)
+	run_carry.end_carry(target)
+
+	return read
+}
+
+// The merges the run ended with are recorded while its record can still count them. The read handed
+// back is the record as it stood before it was removed.
+async function end_run(directory: string, request: EndRequest): Promise<CarryRead> {
+	await run_merge_collect.collect_merged(directory)
+	const read = close_record(directory, request.stopped)
+
+	await announce_stop(read, request)
+	await report_end(read)
+
+	return read
+}
+
+const run_carry_end = { end_run }
+
+export type { EndRequest }
+export { run_carry_end }

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

@@ -102,6 +102,9 @@ interface RunCarry {
 	// The owner conversation's transcript, which outlives a restart of its process
 	// (`run-carry-conversation.ts`). Optional for the same reason as the pid.
 	owner_transcript?: string | undefined
+	// The owner is a session the run launched headless (`run-headless.ts`), so nobody can end the run
+	// from it. Kept here, beside the owner it describes, so it outlives the supervisor's own record.
+	is_owner_headless?: boolean | undefined
 	// Set by `--cut`, and by nothing else. A crash never reaches `--cut`, which is what makes a
 	// declared cut the only standing record carried without a person deciding.
 	is_handed_off?: boolean | undefined
@@ -138,6 +141,7 @@ interface CarryOwner {
 	pid?: number | undefined
 	start?: string | undefined
 	transcript?: string | undefined
+	is_headless?: boolean | undefined
 }
 
 // **`resume` is the only one of the four that establishes anything.** The other three are refusals,
@@ -199,6 +203,7 @@ const run_carry_schema = z.object({
 	owner_pid: z.number().optional(),
 	owner_start: z.string().optional(),
 	owner_transcript: z.string().optional(),
+	is_owner_headless: z.boolean().optional(),
 	is_handed_off: z.boolean().optional(),
 	done: z.array(z.number()).optional(),
 	retrospective: z.boolean().optional(),
@@ -265,6 +270,7 @@ function fresh_carry(invocation: string, owner: CarryOwner, now: Date): RunCarry
 		owner_pid: owner.pid,
 		owner_start: owner.start,
 		owner_transcript: owner.transcript,
+		is_owner_headless: owner.is_headless,
 	}
 }
 
@@ -297,7 +303,7 @@ function adopt_carry(
 	owner: CarryOwner = NO_OWNER,
 ): RunCarry | undefined {
 	// The run's own fields carry across untouched — the counters, the outage fold timestamp, `done` so the successor does not re-run what the cut session finished,
-	// and `retrospective` so a run resumed after a cut does not repeat its retrospective. Only the three
+	// and `retrospective` so a run resumed after a cut does not repeat its retrospective. Only the
 	// ownership fields are overridden: the new owner replaces the old — a caller that declared none
 	// writes `undefined`, so the previous owner cannot survive — and the declared hand-off is spent.
 	const next: RunCarry = {
@@ -305,6 +311,7 @@ function adopt_carry(
 		owner_pid: owner.pid,
 		owner_start: owner.start,
 		owner_transcript: owner.transcript,
+		is_owner_headless: owner.is_headless,
 		is_handed_off: false,
 	}
 

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_watch } from '#scripts/issue/issue-watch'
 import { session_cite } from '#scripts/issue/session-cite'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
@@ -254,6 +255,10 @@ async function proceed(issue_number: string, hold: string, cost: string): Promis
 	await run_label.mark(issue_number)
 	const reads = await gather_reads(issue_number)
 
+	// The issue the report prints is the one the run has read, so it is the baseline a person's later
+	// 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 })
 }