@joshuafolkken/kit 1.872.0

package/scripts/run/run-progress-clock.ts

@@ -0,0 +1,320 @@
+import { git_utilities } from '#scripts/git/constants'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { execaSync } from 'execa'
+import { z } from 'zod'
+
+// The report clock `josh run:progress` keeps, in the one form both of its readers can use
+// (joshuafolkken/kit#1570).
+//
+// **It exists because a second reader arrived, and that one cannot await.** The watcher reads the
+// record between ticks, where an `async` call costs nothing; the trigger-delivered rule that refuses
+// an early heartbeat (`scripts/rules/early-heartbeat.ts`) reads it inside a `PreToolUse` hook, whose
+// decision is synchronous from payload to envelope. Copying the record's shape into the hook would be
+// the clone `CLAUDE.md` prohibits, in the one place where two copies disagreeing means the guard
+// silently guards nothing — so the record lives here and each reader brings its own way of naming the
+// work tree.
+//
+// **The key is the work tree's own git directory**, the way `run_hold` keys its record: two lanes of
+// one repository are two runs, and one lane's report must not silence the other's clock. The
+// synchronous twin asks `git rev-parse --absolute-git-dir`, which is the first of the two lines
+// `git_command.git_directories` reads and the one the asynchronous path already takes — so the two
+// spellings cannot name different files.
+
+const PROGRESS_PREFIX = 'josh-run-progress-'
+// The watcher's own liveness record, kept apart from the report clock above: that one says *when* the
+// run last reported and is written on every heartbeat, so it can never double as "should this watcher
+// still be running". This one is presence-only — the watcher writes it once when it begins, reads it
+// every tick, and ends the moment it is gone, which is how `josh followup` stops a watcher at the
+// merge instead of leaving it to wait out its whole bound (joshuafolkken/kit#1821). It reuses the same
+// key as the report clock — the work tree's own git directory — so both name one file per run.
+//
+// **The loop that reads its own record and exits when it is gone is `run-wake-loop.ts`'s `run_loop`
+// pattern (joshuafolkken/kit#1727), and the read/write is `stamp_file`.** Neither is re-implemented
+// here: this module only names the record, exactly as it names the report clock. Unlike `run-hold`'s
+// and `run-carry`'s records it needs no expiry, because it is read only by the one watcher that wrote
+// it — never by another run deciding whether a resource is free — so a fresh watcher always overwrites
+// a stale one and there is no cross-run read to fall open.
+const LIFE_PREFIX = 'josh-run-progress-life-'
+// **The ambient surface the heartbeat keeps across a session cut** (joshuafolkken/kit#2156). The report
+// clock holds only the *last* line, which `josh run:wake --list` relays on demand — a person has to
+// type for it, so after a cut the heartbeat sits at the *requested* tier. This log mirrors every
+// heartbeat line into a plain-text file beside the clock, so a person who keeps `tail -F` open on it
+// sees the run's progress without asking again: the *ambient* tier the terminal held before the cut,
+// kept across it. It is a sibling of the clock (`<clock>.log`) so both name one file per work tree, and
+// `.log` rather than `.json` because it holds the lines verbatim for a reader — the `stamp_path`
+// distinction the wake log already draws.
+const LOG_SUFFIX = '.log'
+// A few hours of heartbeats at the twenty-minute interval — enough to read the run's recent shape, and
+// bounded so an unattended run cannot grow the file without limit.
+const LOG_KEEP = 12
+const MS_PER_MINUTE = 60_000
+// Longer than any heartbeat interval and shorter than any gap between two runs. Heartbeats land at most
+// one interval apart while a run is live (twenty minutes by default, well under this), so a newest block
+// older than this belongs to a previous run: past it the log is reset rather than extended, and a fresh
+// run never opens on stale lines.
+const LOG_STALE_MINUTES = 90
+const LOG_STALE_MS = LOG_STALE_MINUTES * MS_PER_MINUTE
+const BLOCK_SEPARATOR = '\n\n'
+// The lookup only ever decides whether a rule speaks, so a git call that hangs must not hold the hook
+// that is holding the user's call. A timeout answers `undefined`, which reads as "no clock here" and
+// lets the call through — the direction every other failure in this path already takes.
+const GIT_TIMEOUT_MS = 5000
+// The first of the two lines `git_command.git_directories` reads, asked on its own because that is the
+// one the record is keyed on. Asking git rather than assuming a directory named `.git` is what makes a
+// linked work tree, a bare repository and a `--separate-git-dir` clone all answer correctly.
+const GIT_DIRECTORY_ARGUMENTS: ReadonlyArray<string> = ['rev-parse', '--absolute-git-dir']
+
+// `line` is the last heartbeat the watcher printed, kept verbatim beside the clock so a reader that
+// cannot see the watcher's transcript — a person checking a woken headless `backlogrun` through
+// `josh run:wake --list` — still reads the exact line it emitted (joshuafolkken/kit#1910). It is
+// optional because a bare `--mark` moves the clock without producing one, and because a record written
+// before this field existed carries only `reported_at`.
+const report_stamp_schema = z.object({ reported_at: z.string(), line: z.string().optional() })
+
+function parse_stamp(raw: string): number | undefined {
+	const parsed = report_stamp_schema.safeParse(JSON.parse(raw))
+
+	if (!parsed.success) return undefined
+
+	const reported_at = Date.parse(parsed.data.reported_at)
+
+	return Number.isNaN(reported_at) ? undefined : reported_at
+}
+
+/**
+ * The last heartbeat line the watcher persisted, or `undefined` for an absent, unparsable, or
+ * pre-`line` record. This is what `josh run:wake --list` relays to a person who is no longer the parent
+ * session — the headless parent woken after a cut prints its progress only to its own transcript, and
+ * this record is the one place that line survives (joshuafolkken/kit#1910).
+ */
+function read_last_line(target: string): string | undefined {
+	const raw = stamp_file.read_stamp_text(target)
+
+	if (raw === undefined) return undefined
+
+	try {
+		return report_stamp_schema.safeParse(JSON.parse(raw)).data?.line
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * When the run last reported anything — a real report through `--mark`, or a line the watcher printed.
+ *
+ * `undefined` for every unreadable shape. The watcher falls back to the moment it started watching;
+ * the guard reads it as "this run has no progress clock" and refuses nothing, which is what keeps an
+ * ordinary conversational session outside a rule written for unattended runs.
+ */
+function read_last_report(target: string): number | undefined {
+	const raw = stamp_file.read_stamp_text(target)
+
+	if (raw === undefined) return undefined
+
+	try {
+		return parse_stamp(raw)
+	} catch {
+		return undefined
+	}
+}
+
+// The ambient log's path, a sibling of the report clock so one directory names both and the CLI can
+// derive it from the clock target alone (joshuafolkken/kit#2156).
+function log_path_of(target: string): string {
+	return `${target}${LOG_SUFFIX}`
+}
+
+// **Staleness is read from the report clock's own last timestamp, not the log file's mtime**
+// (joshuafolkken/kit#2156). The clock's `reported_at` is the run's own clock — a copy or a backup can
+// move a file's mtime, and a fresh run whose first heartbeat found a previous run's log would then
+// append to it. It is read before `mark` overwrites the clock, so it sees the *previous* report.
+function is_log_stale(target: string, now_ms: number): boolean {
+	const previous_ms = read_last_report(target)
+
+	return previous_ms === undefined || now_ms - previous_ms > LOG_STALE_MS
+}
+
+// The blocks already in the log, or none when it is absent or a previous run's. `read_stamp_text` is
+// the symlink-safe read the clock itself uses, so a planted file reads as no record rather than being
+// trusted.
+function recent_blocks(log_target: string, is_fresh: boolean): ReadonlyArray<string> {
+	if (is_fresh) return []
+
+	const raw = stamp_file.read_stamp_text(log_target)
+
+	if (raw === undefined) return []
+
+	// `trimEnd` per block so the file's trailing newline, glued to the last block by the split, does not
+	// re-join into a `\n\n\n` gap that grows the reader's ambient surface a blank line at a time.
+	return raw
+		.split(BLOCK_SEPARATOR)
+		.map((block) => block.trimEnd())
+		.filter((block) => block.length > 0)
+}
+
+// One heartbeat mirrored into the ambient log, newest last, the oldest rolled off past `LOG_KEEP`. A
+// fresh run — or a stale log — starts the file over. `write_text_stamp` unlinks then creates
+// exclusively, so the write is symlink-safe and `tail -F` re-reads it cleanly after each replacement.
+function append_line(
+	log_target: string,
+	reported_at: string,
+	line: string,
+	is_fresh: boolean,
+): void {
+	const block = `${reported_at}\n${line}`
+	const blocks = [...recent_blocks(log_target, is_fresh), block].slice(-LOG_KEEP)
+
+	stamp_file.write_text_stamp(log_target, `${blocks.join(BLOCK_SEPARATOR)}\n`)
+}
+
+// A heartbeat carries its line; a bare `--mark` (a real report resetting the clock) carries none and
+// **preserves the line already there** rather than blanking it — so `josh run:wake --list` keeps
+// showing the most recent heartbeat between a run's real reports rather than going empty on every one
+// (joshuafolkken/kit#1910). A carried line is also mirrored into the ambient log — the surface a person
+// keeps open across a cut — before the clock is overwritten, so staleness sees the previous report
+// (joshuafolkken/kit#2156).
+function mark(target: string, now_ms: number, line?: string): void {
+	const reported_at = new Date(now_ms).toISOString()
+	const kept = line ?? read_last_line(target)
+
+	if (line !== undefined) {
+		append_line(log_path_of(target), reported_at, line, is_log_stale(target, now_ms))
+	}
+
+	stamp_file.write_stamp(target, kept === undefined ? { reported_at } : { reported_at, line: kept })
+}
+
+// `undefined` is passed straight through so `stamp_file`'s own default root stands, which is what the
+// caller got before this function existed. Hashing an empty string instead would key the record on a
+// path no other code path produces.
+function stamp_target_of(git_directory: string | undefined): string {
+	return stamp_file.stamp_path(PROGRESS_PREFIX, git_directory)
+}
+
+// The liveness record's path, keyed the same way as the report clock so the watcher and `josh followup`
+// name one file per work tree. A different prefix keeps it a separate file: removing it must not
+// disturb the report clock the early-heartbeat guard reads.
+function life_target_of(git_directory: string | undefined): string {
+	return stamp_file.stamp_path(LIFE_PREFIX, git_directory)
+}
+
+// **`pinged_at` is written by every tick and checked by `is_life_fresh`.** Without it the life record
+// is presence-only — existence is the only signal, and a record from a watcher that stopped an hour
+// ago is indistinguishable from one whose watcher is live. Adding `pinged_at` to the payload lets a
+// guard detect "children in-flight but watcher stale" without a second file (joshuafolkken/kit#2113).
+// Old records carrying only `{ alive: true }` parse successfully; `pinged_at` is optional on read,
+// which is what makes this backward-compatible.
+const life_schema = z.object({ alive: z.literal(true), pinged_at: z.string().optional() })
+
+// The watcher declares itself alive. `write_stamp` unlinks first, so a fresh `--wait` cleanly replaces
+// a record an earlier one left behind.
+function begin_life(target: string): void {
+	stamp_file.write_stamp(target, { alive: true, pinged_at: new Date().toISOString() })
+}
+
+// Refreshes the `pinged_at` timestamp without disturbing the liveness semantics. Called on every
+// watch tick so the record's age is a proxy for "watcher is running".
+function ping_life(target: string): void {
+	begin_life(target)
+}
+
+function parse_pinged_at(raw: string): number | undefined {
+	const parsed = life_schema.safeParse(JSON.parse(raw))
+
+	if (!parsed.success || parsed.data.pinged_at === undefined) return undefined
+
+	const pinged_ms = Date.parse(parsed.data.pinged_at)
+
+	return Number.isNaN(pinged_ms) ? undefined : pinged_ms
+}
+
+// Returns `false` for any absent, unreadable or un-timestamped record — both "no watcher" and "old
+// watcher that predates joshuafolkken/kit#2113" produce `false`, which is the safe direction for a
+// guard: it speaks up rather than staying silent.
+function is_life_fresh(target: string, threshold_ms: number): boolean {
+	const raw = stamp_file.read_stamp_text(target)
+
+	if (raw === undefined) return false
+
+	try {
+		const pinged_ms = parse_pinged_at(raw)
+
+		return pinged_ms !== undefined && Date.now() - pinged_ms < threshold_ms
+	} catch {
+		return false
+	}
+}
+
+// **Gone means ended.** `read_stamp_text` answers `undefined` for an absent or unowned record, and the
+// only writer is the watcher itself, so absence means `josh followup` removed it — or nobody began
+// one. Either way the watcher stops, which is the fail-quiet direction: a watcher that kept running on
+// a missing record would be the lingering process joshuafolkken/kit#1821 exists to end.
+function is_life_ended(target: string): boolean {
+	return stamp_file.read_stamp_text(target) === undefined
+}
+
+// What `josh followup` calls at the merge seam, and what the watcher calls when its own bound ends.
+// Removing an absent record is a no-op, so it is safe on either side.
+function end_life(target: string): void {
+	stamp_file.remove_stamp(target)
+}
+
+// execa runs the binary directly with an argument array and no `shell` option, so CLI args cannot
+// break out of a shell sandbox; the git command and args are internally controlled, never untrusted
+// input. tssecurity:S8705 is a false positive here.
+function git_directory_sync(): string | undefined {
+	const git_binary = git_utilities.get_git_command_for_spawn()
+	const result = execaSync(git_binary, GIT_DIRECTORY_ARGUMENTS, {
+		reject: false,
+		timeout: GIT_TIMEOUT_MS,
+	}) // NOSONAR
+
+	if (result.exitCode !== 0) return undefined
+
+	const output = result.stdout.trim()
+
+	return output === '' ? undefined : output
+}
+
+function stamp_target_sync(): string | undefined {
+	const directory = git_directory_sync()
+
+	return directory === undefined ? undefined : stamp_target_of(directory)
+}
+
+/**
+ * The clock, read from a place that cannot await — the whole reason this module is separate.
+ *
+ * It answers about the work tree the caller is standing in. A watcher started in another repository's
+ * checkout keeps its record there, so a hook running in the session's own tree finds none and the rule
+ * stays silent rather than guessing; that is the same limit `backlogrun.md` records for `--mark`.
+ */
+function read_last_report_sync(): number | undefined {
+	const target = stamp_target_sync()
+
+	return target === undefined ? undefined : read_last_report(target)
+}
+
+const run_progress_clock = {
+	LIFE_PREFIX,
+	LOG_KEEP,
+	LOG_STALE_MS,
+	PROGRESS_PREFIX,
+	append_line,
+	begin_life,
+	end_life,
+	is_life_ended,
+	is_life_fresh,
+	life_target_of,
+	log_path_of,
+	mark,
+	parse_stamp,
+	ping_life,
+	read_last_line,
+	read_last_report,
+	read_last_report_sync,
+	stamp_target_of,
+	stamp_target_sync,
+}
+
+export { run_progress_clock }

package/scripts/run/run-progress-config.ts

@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { z } from 'zod'
+import { run_progress } from './run-progress'
+
+// Where the silence interval comes from, and in what order (joshuafolkken/kit#1576).
+//
+// **The setting existed and could not leave the machine.** `JOSH_PROGRESS_INTERVAL_MINUTES` is read
+// from `.env`, which is deliberately never committed — so a person who set fifteen minutes here got
+// twenty on every other machine and in every cloud session, and the guard that enforces the floor got
+// twenty with them. Reporting still happened there, at a cadence nobody asked for.
+//
+// **So the repository carries one of its own.** `josh.progress_interval_minutes` in `package.json` is
+// committed, is per repository rather than per toolkit, and is read through the same reader both
+// halves of the mechanism already share — the watcher before it prints, and the `early-heartbeat` row
+// before it allows an arm. A guard that could disagree with the watcher it guards is worse than no
+// guard, so there is one order and both sides ask for it here.
+//
+// **The environment still outranks the file**, because a person's own machine is allowed to differ
+// from what the repository asks for, and `--interval` outranks both for the watcher alone — a hook has
+// no command line to read.
+//
+// **The nearest declaring `package.json` wins, searched upward.** The two callers do not stand in the
+// same directory — `pnpm` runs a script from the package root and Claude Code runs a hook from the
+// project root — and in a workspace those are different files, only one of which declares a cadence.
+// Reading the working directory alone would let the guard enforce the repository's interval while the
+// watcher it guards kept the default, which is the one state this module exists to prevent.
+
+const PACKAGE_FILE = 'package.json'
+const CONFIG_FIELD = 'josh'
+const INTERVAL_FIELD = 'progress_interval_minutes'
+
+// Deep enough to cross a workspace package and its root, and bounded so a path that never reaches a
+// root — a broken mount, a mocked `dirname` — cannot spin.
+const MAX_DEPTH = 10
+
+// Unknown keys are stripped rather than rejected: this reads a whole `package.json`, and every other
+// field in it is none of this module's business. A present-but-unusable interval fails the parse and
+// falls through, which is the same answer an unusable environment variable already gets.
+const package_schema = z.object({
+	josh: z.object({ progress_interval_minutes: z.number().positive() }).optional(),
+})
+
+function ancestors_of(start: string): ReadonlyArray<string> {
+	const directories: Array<string> = []
+	let current = path.resolve(start)
+
+	while (directories.length < MAX_DEPTH && !directories.includes(current)) {
+		directories.push(current)
+		current = path.dirname(current)
+	}
+
+	return directories
+}
+
+function read_declared_minutes(directory: string): number | undefined {
+	try {
+		const raw = readFileSync(path.join(directory, PACKAGE_FILE), 'utf8')
+		const parsed = package_schema.safeParse(JSON.parse(raw))
+
+		return parsed.success ? parsed.data.josh?.progress_interval_minutes : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function read_package_minutes(start: string): number | undefined {
+	for (const directory of ancestors_of(start)) {
+		const minutes = read_declared_minutes(directory)
+
+		if (minutes !== undefined) return minutes
+	}
+
+	return undefined
+}
+
+function to_ms(minutes: number | undefined): number | undefined {
+	return minutes === undefined ? undefined : minutes * run_progress.MS_PER_MINUTE
+}
+
+/**
+ * The interval in force: a hand-typed value, then the environment, then the repository, then twenty.
+ *
+ * Each step answers `undefined` for anything that is not a positive number, so an unusable value falls
+ * through to the next source rather than throwing — this runs unattended, and dying on a typo in an
+ * optional setting removes the reporting the setting was there to tune.
+ */
+function resolve_interval_ms(raw: string | undefined, directory: string = process.cwd()): number {
+	return (
+		to_ms(run_progress.minutes_from(raw)) ??
+		to_ms(run_progress.minutes_from(process.env[run_progress.INTERVAL_KEY])) ??
+		to_ms(read_package_minutes(directory)) ??
+		run_progress.DEFAULT_INTERVAL_MS
+	)
+}
+
+/**
+ * The **floor** the guard enforces — the same order with no command line in it.
+ *
+ * It is deliberately not the watcher's effective interval: the watcher takes `--interval` on top, and
+ * a hook has no flag to read. A `--interval` above the floor makes the watcher quieter than the guard
+ * requires, which is the harmless direction; below it, the watcher prints more often than the guard
+ * would let a run arm a timer for — so a run that wants a different cadence sets the environment
+ * variable or the committed field, which both sides read.
+ */
+function configured_interval_ms(directory: string = process.cwd()): number {
+	return resolve_interval_ms(undefined, directory)
+}
+
+const run_progress_config = {
+	CONFIG_FIELD,
+	INTERVAL_FIELD,
+	PACKAGE_FILE,
+	configured_interval_ms,
+	read_package_minutes,
+	resolve_interval_ms,
+}
+
+export { run_progress_config }

package/scripts/run/run-progress-read.ts

@@ -0,0 +1,199 @@
+import { loadavg } from 'node:os'
+import { epic_busy } from '#scripts/epic/epic-busy'
+import { git_command } from '#scripts/git/git-command'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_report } from '#scripts/lane/lane-report'
+import { run_carry, type CarryRead } from './run-carry'
+import { run_hold, type HoldRead } from './run-hold'
+import { run_liveness } from './run-liveness'
+import { run_preflight } from './run-preflight'
+import type { ChildObservation, LaneObservation, Observations } from './run-progress'
+import { run_progress_clock } from './run-progress-clock'
+
+// Everything `josh run:progress` reads: the last-report record that makes the clock a silence clock,
+// and the observations one tick puts on the line (joshuafolkken/kit#1520).
+//
+// **Every reader here is one that already exists.** The children in flight come from
+// `epic_busy.read_repository`, which is the same `in-progress` listing `epicrun` sizes its lanes
+// from — a second definition of "running" would let the progress line disagree with the loop that
+// printed the child. The pull request comes from `run_preflight`, the lanes from `lane_registry`, and
+// the transcript sample from `run_liveness.sample_output`, whose symlink-following `statSync` is the
+// whole of joshuafolkken/kit#1485; re-`stat`ing the path here would reintroduce that bug.
+//
+// **The record is kept per work tree**, keyed the way `run_hold` keys its own: two lanes of one
+// repository are two runs, and one lane's report must not silence the other's clock.
+
+// The record itself — its name, its shape, and how it is read and written — lives in
+// `run-progress-clock.ts`, because the trigger-delivered rule that refuses an early heartbeat reads
+// the same record from inside a `PreToolUse` hook and cannot await the git call this file makes
+// (joshuafolkken/kit#1570). What stays here is the asynchronous way of naming the work tree.
+const { PROGRESS_PREFIX, mark, parse_stamp, read_last_report } = run_progress_clock
+
+const FIRST_LOAD_AVERAGE = 0
+
+// A listing that arrived and had holders, a listing that arrived empty, and a listing that did not
+// arrive. All three end in no line being printed, and they are kept apart anyway: only the middle one
+// can mean "there is nothing to report", and saying so for the third would be a confident absence
+// built on a read nobody completed. **The middle one is `idle` only when no run has started** — a run
+// underway with no `in-progress` child yet is `observed` with an empty `children`, which is the
+// heartbeat this file emits before the first label appears (joshuafolkken/kit#1900).
+type ObservationRead =
+	{ kind: 'idle' } | { kind: 'observed'; observations: Observations } | { kind: 'unreadable' }
+
+const IDLE_READ: ObservationRead = { kind: 'idle' }
+const UNREADABLE_READ: ObservationRead = { kind: 'unreadable' }
+
+// The one place the record key is resolved: the first of the two paths git prints is this work tree's
+// own git directory; the second is the common directory every work tree shares, which is exactly what
+// must not be the key. Both the report clock and the liveness record key on it, so a single resolver
+// is what keeps the file the watcher writes and the file `josh followup` removes the same one.
+async function worktree_git_directory(): Promise<string | undefined> {
+	const [git_directory] = await git_command.git_directories()
+
+	return git_directory
+}
+
+async function stamp_target(): Promise<string> {
+	return run_progress_clock.stamp_target_of(await worktree_git_directory())
+}
+
+// The ambient log's path, a sibling of the report clock — the surface `josh run:progress --path` names
+// so a person can keep it open across a session cut (joshuafolkken/kit#2156).
+async function log_target(): Promise<string> {
+	return run_progress_clock.log_path_of(await stamp_target())
+}
+
+// The watcher's liveness record, resolved through the same resolver as `stamp_target`, so the file the
+// watcher begins is the file `josh followup` removes at the merge (joshuafolkken/kit#1821).
+async function live_target(): Promise<string> {
+	return run_progress_clock.life_target_of(await worktree_git_directory())
+}
+
+function to_labels(issue: OpenIssueData): Array<string> {
+	return (issue.labels ?? []).map((label) => label.name)
+}
+
+async function to_child(issue: OpenIssueData): Promise<ChildObservation> {
+	const number = String(issue.number)
+	const child = await run_preflight.read_child_state(number)
+
+	return { issue: number, labels: to_labels(issue), pr_state: child.pr_state }
+}
+
+async function read_children(repo: string): Promise<ReadonlyArray<ChildObservation> | undefined> {
+	const read = await epic_busy.read_repository(repo)
+
+	if (read.kind === 'idle') return []
+	if (read.kind !== 'busy') return undefined
+
+	return await Promise.all(read.issues.map(async (issue) => await to_child(issue)))
+}
+
+async function read_lanes(): Promise<ReadonlyArray<LaneObservation>> {
+	const lanes = await lane_registry.list_lanes()
+
+	return lanes.map((lane) => ({ issue: lane.issue, state: lane_report.lane_state(lane) }))
+}
+
+function is_mtime(value: number | undefined): value is number {
+	return value !== undefined
+}
+
+/**
+ * How long ago the newest delegated unit's transcript last grew — the one field that says a run may be
+ * stuck rather than merely slow.
+ *
+ * `undefined` when no path was given or none of them could be sampled, and the line prints `unread`
+ * for it. A run started before any unit exists has nothing to name here, and inventing an age for a
+ * file nobody read is the failure this command is built not to commit.
+ */
+function read_record_age(paths: ReadonlyArray<string>, now_ms: number): number | undefined {
+	const times = paths
+		.map((output_path) => run_liveness.sample_output(output_path)?.mtime_ms)
+		.filter(is_mtime)
+
+	if (times.length === 0) return undefined
+
+	return now_ms - Math.max(...times)
+}
+
+function is_hold_present(read: HoldRead): boolean {
+	return read.kind === 'held' || read.kind === 'stale'
+}
+
+function is_carry_present(read: CarryRead): boolean {
+	return read.kind === 'carried' || read.kind === 'expired'
+}
+
+function hold_present(worktree: string | undefined): boolean {
+	return worktree !== undefined && is_hold_present(run_hold.read_hold(run_hold.hold_path(worktree)))
+}
+
+function carry_present(repository: string | undefined): boolean {
+	if (repository === undefined) return false
+
+	return is_carry_present(run_carry.read_carry(run_carry.carry_path(repository)))
+}
+
+// The mechanical records that say a run is underway, read from the same git directories the report
+// clock is keyed on: the work tree's own for the hold, the common one for the carried budget.
+async function has_run_record(): Promise<boolean> {
+	const [worktree, repository] = await git_command.git_directories()
+
+	return hold_present(worktree) || carry_present(repository)
+}
+
+/**
+ * Whether a run has started in this checkout, read from a mechanical record rather than from the
+ * `in-progress` label — the label is exactly what is missing in the window this bridges
+ * (joshuafolkken/kit#1900).
+ *
+ * A registered lane covers an `epicrun` / `backlogrun` parent whose child has not labelled yet — and
+ * it is the one signal already read for the line, so it is asked first and short-circuits the git
+ * reads. A held work tree covers a `fullrun` / `halfrun` between `run:hold` and its first label, and a
+ * carried budget covers a `backlogrun` / `queue` before its first lane opens.
+ */
+async function has_run_started(lanes: ReadonlyArray<LaneObservation>): Promise<boolean> {
+	return lanes.length > 0 || (await has_run_record())
+}
+
+interface ObservationRequest {
+	now_ms: number
+	output_paths: ReadonlyArray<string>
+	repo: string
+}
+
+async function read_observations(request: ObservationRequest): Promise<ObservationRead> {
+	const [children, lanes] = await Promise.all([read_children(request.repo), read_lanes()])
+
+	if (children === undefined) return UNREADABLE_READ
+	if (children.length === 0 && !(await has_run_started(lanes))) return IDLE_READ
+
+	const observations: Observations = {
+		children,
+		lanes,
+		load_average: loadavg()[FIRST_LOAD_AVERAGE] ?? 0,
+		record_age_ms: read_record_age(request.output_paths, request.now_ms),
+	}
+
+	return { kind: 'observed', observations }
+}
+
+const run_progress_read = {
+	PROGRESS_PREFIX,
+	has_run_started,
+	live_target,
+	log_target,
+	mark,
+	parse_stamp,
+	read_children,
+	read_last_report,
+	read_lanes,
+	read_observations,
+	read_record_age,
+	stamp_target,
+}
+
+export type { ObservationRead }
+export { run_progress_read }