@joshuafolkken/kit 1.872.0

package/scripts/time-runtime/time-density-hook.ts

@@ -0,0 +1,166 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+import { time_density } from './time-density'
+import { time_hook_transcript } from './time-hook-transcript'
+
+// The disk half of the live density line (joshuafolkken/kit#1329): find the transcript, read enough
+// of it, and remember when the line was last emitted.
+//
+// **It rides the hook that already runs, and adds no second one.** `.claude/settings.json` wires
+// `pnpm josh format:edited` to `PostToolUse` for `Edit`, `Write` and `Bash`; a matcher covering every
+// tool would put a process start in front of all ~250 calls of a run to say something on a handful of
+// them.
+//
+// **`Bash` is in that list because the edit half was measured missing its audience**
+// (joshuafolkken/kit#1337). Riding the edit hook was chosen on run #1299, where `Edit` was the
+// most-called tool at 65 calls — and that run no longer represents how these sessions work. Of the
+// ten most recent in this checkout, **seven called `Edit` and `Write` zero times**: they edit through
+// `sed` instead, and they are the same sessions measured at 1.00–1.31 against the 1.50 floor, so the
+// line was reaching none of the runs it exists for. `Bash` is 88–100% of their calls, which is why
+// naming it alone reaches all of them and the read-only tools stay off the hook.
+//
+// **Nothing here may fail.** A `PostToolUse` hook runs after the edit has landed and cannot undo it,
+// so a transcript that is missing, unreadable or not JSON at all ends as "no line", exactly as
+// `format-edited-file.ts` treats a formatter it could not start. A transcript caught mid-append ends
+// there too: `time_density.last_turn_calls` withholds the count when the tail's final line does not
+// parse, because that line belongs to the turn the count is about.
+
+// How much of the transcript's end is read. The file grows to several megabytes over a long run —
+// 4.7 MB and 2,712 lines for the largest in this checkout — and reading all of it on every edit would
+// put the run's own history in front of every write. A quarter of a megabyte is far more than the ten
+// round trips the reading needs and is read in a couple of milliseconds.
+const TAIL_BYTES = 262_144
+const FILE_START = 0
+// **One record per session, keyed on the transcript the payload named**, rather than per checkout the
+// way `josh gate`'s stamp is. What is being throttled is a *run*, and a run is one session: keyed on
+// the checkout, a session started — or cleared — within the interval of the previous one's line would
+// inherit that silence through its opening stretch, which is the part of a run where the correction
+// is worth the most. Keying on the transcript path also gives a delegated child its own budget, which
+// is right for the same reason: it is a run of its own. The cost is one small record per session left
+// in the temp directory rather than one per checkout reused — reaped with everything else there, and
+// cheaper than the silence the shared key bought.
+const NOTICE_PREFIX = 'josh-density-notice-'
+// No record means nothing has been said yet, and the caller compares `now - this`. Zero makes that
+// difference enormous, which is the answer wanted: the first eligible edit of a run emits.
+const NEVER_MS = 0
+
+// The two fields this reads. Claude Code hands a `PostToolUse` hook `transcript_path` beside the
+// `tool_input` the formatter half uses, so a file is named rather than searched for — no
+// home-directory walk.
+//
+// **`agent_id` is what makes a delegated unit answerable with its own transcript**
+// (joshuafolkken/kit#1424). The path in the payload is the *parent* session's, whichever agent issued
+// the call, so without this field the line a fork read described the parent's calls per round trip —
+// a number about a run the reader is not in. `time-hook-transcript.ts` carries the derivation.
+const payload_schema = z.object({
+	transcript_path: z.string().min(1).optional(),
+	// **`nullish`, not `optional`.** A payload spelling the absent agent as `null` has to read as "no
+	// fork"; rejected, it would fail `safeParse` for the whole payload and silence the line for every
+	// edit of the main line — the opposite of this module's stated failure direction.
+	agent_id: z.string().nullish(),
+})
+const notice_schema = z.object({ notified_at_ms: z.number() })
+
+function parse_transcript_path(raw_payload: string): string | undefined {
+	const parsed = payload_schema.safeParse(JSON.parse(raw_payload))
+
+	if (!parsed.success || parsed.data.transcript_path === undefined) return undefined
+
+	return time_hook_transcript.transcript_of(parsed.data.transcript_path, parsed.data.agent_id)
+}
+
+// The last `max_bytes` of a file, as text. The leading line is usually cut mid-way, which every
+// reader below already handles: an unparseable line is dropped rather than dated.
+//
+// **Only the bytes `readSync` reports are decoded.** `Buffer.alloc` zero-fills, and a short read — a
+// real possibility on the network- and FUSE-backed home directories these transcripts can live on —
+// would otherwise leave NUL padding on the end of the text, making the *last* line unparseable. That
+// is the one line the turn's call count is read from.
+function read_tail(file_path: string, max_bytes: number = TAIL_BYTES): string {
+	const descriptor = openSync(file_path, 'r')
+
+	try {
+		const { size } = fstatSync(descriptor)
+		const length = Math.min(size, max_bytes)
+		const buffer = Buffer.alloc(length)
+		const read = readSync(descriptor, buffer, FILE_START, length, size - length)
+
+		return buffer.subarray(FILE_START, read).toString('utf8')
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+function notice_path(transcript_path: string): string {
+	return stamp_file.stamp_path(NOTICE_PREFIX, transcript_path)
+}
+
+// A record that is absent, unreadable, planted by another account or not the shape written here all
+// answer `NEVER_MS`. The failure direction is one extra line, never a silenced one.
+function last_notice_ms(source: string): number {
+	const raw = stamp_file.read_stamp_text(source)
+
+	if (raw === undefined) return NEVER_MS
+
+	try {
+		return notice_schema.parse(JSON.parse(raw)).notified_at_ms
+	} catch {
+		return NEVER_MS
+	}
+}
+
+// **Arming the throttle is best-effort, and never costs the line.** The caller prints and exits, so
+// this write is the only place the throttle can be armed — but `write_stamp` creates exclusively, so
+// a second hook running in the same session, a sticky temp directory, or a path another account owns
+// each throw. Swallowed here rather than by the outer guard, which would discard the notice that had
+// already been computed and silence exactly what `last_notice_ms` promises never to silence.
+//
+// **What this trades for is stated at its worst, not at its mildest.** A transient collision costs
+// one extra line; a write that fails for the whole session — an unwritable temp directory, a path
+// another account owns — arms nothing ever, so the interval is not stretched but gone, and the line
+// lands on every single-call edit turn of the run. That is still the better direction: an agent that
+// reads the same line repeatedly has been told something true, while one silenced by a temp-file
+// permission has been told nothing at all and cannot tell.
+function arm_throttle(target: string, now_ms: number): void {
+	try {
+		stamp_file.write_stamp(target, { notified_at_ms: now_ms })
+	} catch {
+		// Deliberately empty — see above.
+	}
+}
+
+function notice_for(raw_payload: string, now_ms: number): string | undefined {
+	const transcript_path = parse_transcript_path(raw_payload)
+
+	if (transcript_path === undefined) return undefined
+
+	const reading = time_density.read_window(read_tail(transcript_path))
+	const target = notice_path(transcript_path)
+
+	if (!time_density.is_due(reading, now_ms - last_notice_ms(target))) return undefined
+
+	arm_throttle(target, now_ms)
+
+	return time_density.format_notice(reading)
+}
+
+// The whole call in one guard: every path above may throw on a file that moved or a payload that is
+// not JSON, and neither is worth failing an edit over.
+function density_notice(raw_payload: string, now_ms: number = Date.now()): string | undefined {
+	try {
+		return notice_for(raw_payload, now_ms)
+	} catch {
+		return undefined
+	}
+}
+
+const time_density_hook = {
+	NOTICE_PREFIX,
+	TAIL_BYTES,
+	density_notice,
+	notice_path,
+	read_tail,
+}
+
+export { time_density_hook }

package/scripts/time-runtime/time-density.ts

@@ -0,0 +1,147 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { time_round_trips } from './time-round-trips'
+import { time_spans, type TranscriptLine } from './time-spans'
+
+// The round-trip density a run can be told **while it is still running** (joshuafolkken/kit#1329).
+//
+// `time-round-trips.ts` already computes the number this reads, and `josh time` already warns on it
+// — after the run has ended. Measured on run #1299, that report changed nothing: the density stayed
+// at 1.08 with 159 of 172 tool-issuing turns making a single call, because the norm
+// joshuafolkken/kit#1304 shipped as prose in `CLAUDE.md` reaches a reader who has already finished.
+// What was missing is the number arriving in time to change the next turn.
+//
+// **The density is `time_round_trips`, reused rather than restated.** A second calculation here
+// would be the clone `CLAUDE.md` prohibits, and worse than an ordinary one: the live line and the
+// end-of-run report would come to disagree about the very quantity the change is measured on.
+//
+// **The turn's own call count is read from the transcript, not inferred from timing.** Guessing turn
+// boundaries from the gaps between calls would make the signal a heuristic about the thing it is
+// trying to correct — a slow turn would look batched and a fast pair would look like one turn. Claude
+// Code writes one line per content block with the assistant message's id on each, so the exact count
+// is the `tool_use` blocks across the lines carrying the newest id.
+
+// How many round trips the window must hold before it is allowed to say anything. A tail that caught
+// three calls has no density worth quoting, and a warning drawn from one is noise the reader learns
+// to skip — which costs more than the line saves.
+const MIN_ROUND_TRIPS = 10
+// At most one line per this interval, per checkout. The line lands in the run's context and stays
+// there, so a reminder with no throttle would spend exactly the budget joshuafolkken/kit#1322 is
+// about: 65 edits of run #1299 would have carried 65 copies of it. Five minutes is roughly 30 round
+// trips at
+// the 9.7s each cost in that run — often enough to reach the phase that is drifting, rare enough that
+// a whole run pays well under a thousand tokens for the feedback.
+const NOTICE_INTERVAL_MS = 300_000
+// The count that means "this turn batched nothing". Zero is not that: it means the newest assistant
+// message could not be identified, and a run is never told off on an unread transcript.
+const ONE_CALL = 1
+const NONE = 0
+
+// What one look at the transcript tail found. `round_trip_count` rides along because the line quotes
+// it — a density without the sample it was taken over cannot be judged by whoever reads it.
+interface DensityReading {
+	density: number
+	round_trip_count: number
+	turn_calls: number
+}
+
+// **A tail whose final line does not parse is not read at all.** That is the shape a transcript
+// caught mid-append has, and the line it truncates belongs to the *newest* turn — the one the count
+// is about. Dropping the torn line the way an unparseable leading line is dropped would read a turn
+// of `[thinking, tool_use, tool_use]` as one call and warn a turn that batched, which is the advice
+// inverted. Withholding is the only answer that cannot be wrong. The leading line is a different
+// case: it belongs to a turn already long past, and no count is taken from it.
+function has_whole_tail(text: string): boolean {
+	const last = text.split('\n').findLast((line) => line.trim() !== '')
+
+	return last !== undefined && time_spans.parse_line(last) !== undefined
+}
+
+function assistant_lines(text: string): Array<TranscriptLine> {
+	return text
+		.split('\n')
+		.map((line) => time_spans.parse_line(line))
+		.filter((line): line is TranscriptLine => line?.type === time_spans.ASSISTANT_TYPE)
+}
+
+// The tool calls the newest assistant message issued, or `NONE` when there is no message to read.
+//
+// **Grouped by message id rather than taken off the last line.** One line holds one content block, so
+// a turn that thought and then issued three calls is four lines; reading only the last of them would
+// report every turn as having made exactly one call, which is the very verdict this line delivers.
+// A line written without an id is left ungrouped for the same reason — every such line shares the
+// empty string, and a bucket spanning the whole file would answer with the window's total.
+function last_turn_calls(text: string): number {
+	if (!has_whole_tail(text)) return NONE
+
+	const lines = assistant_lines(text)
+	const message_id = lines.at(-1)?.message_id
+
+	if (message_id === undefined || message_id === time_spans.NO_MESSAGE_ID) return NONE
+
+	return lines
+		.filter((line) => line.message_id === message_id)
+		.flatMap((line) => line.blocks)
+		.filter((block) => block.type === cost_blocks.TOOL_USE_TYPE).length
+}
+
+// The reading over whatever stretch of transcript was handed in. The caller passes a tail rather than
+// the whole file, so this is deliberately a *recent* density: a run that batched for its first hour
+// and stopped is one the line should still reach.
+function read_window(text: string): DensityReading {
+	const { spans } = time_spans.parse_timeline(text)
+	const round_trip_count = time_round_trips.count_round_trips(spans)
+	const call_count = time_round_trips.count_calls(spans)
+
+	return {
+		density: time_round_trips.per_round_trip(call_count, round_trip_count),
+		round_trip_count,
+		turn_calls: last_turn_calls(text),
+	}
+}
+
+// Four conditions, and each one withholds the line for a different reason: too little evidence, a
+// turn that did batch, a run already clearing the floor, and one told recently enough.
+//
+// **The floor is `time_round_trips.is_below_floor`, not a threshold of its own.** The end-of-run
+// warning and this line have to fire on the same runs, or a run is told it is fine while the report
+// it gets afterwards says it was not.
+function is_due(reading: DensityReading, since_last_ms: number): boolean {
+	if (
+		reading.round_trip_count < MIN_ROUND_TRIPS ||
+		reading.turn_calls !== ONE_CALL ||
+		!time_round_trips.is_below_floor(reading.density)
+	) {
+		return false
+	}
+
+	return since_last_ms >= NOTICE_INTERVAL_MS
+}
+
+// One line, and it says three things: what the density is, what it is being measured against, and
+// what to do differently. The instruction is last because it is the only part worth acting on, and it
+// names the resident rule rather than restating it — the rule is already in the run's context, and a
+// second wording of it would be a clone that can drift.
+function format_notice(reading: DensityReading): string {
+	const density = time_round_trips.format_density(reading.density)
+	const floor = time_round_trips.format_density(time_round_trips.CALLS_PER_ROUND_TRIP_FLOOR)
+
+	return (
+		`⚠ batching: ${density} calls per round trip over the last ${String(reading.round_trip_count)}, ` +
+		`under the ${floor} floor, and this turn issued one call. ` +
+		`Independent reads, greps, gh queries and edits go out together; the criterion is whether this ` +
+		`call's input needs another call's result, not what kind of call it is — ` +
+		`prompts/collaboration-workflow/turn-batching.md.`
+	)
+}
+
+const time_density = {
+	MIN_ROUND_TRIPS,
+	NOTICE_INTERVAL_MS,
+	format_notice,
+	is_due,
+	last_turn_calls,
+	read_window,
+}
+
+export type { DensityReading }
+export { time_density }

package/scripts/time-runtime/time-followup-stage.ts

@@ -0,0 +1,107 @@
+import { git_followup_stages, type FollowupStage } from '#scripts/git/git-followup-stages'
+
+// Reading `followup`'s own stage rows back out of what it printed (joshuafolkken/kit#1445).
+//
+// joshuafolkken/kit#1349 gave `pnpm josh followup` a per-stage block — one
+// `followup stage: <name> <n> s` row per lap — and declared the prefix as a constant so a reader
+// could be added without matching a string the printer is free to reword. **There was no reader.**
+// `josh time` sees a `followup` invocation as one Bash span, so the breakdown existed only on the
+// screen of whoever happened to be watching that run: two runs could not be compared stage by stage,
+// and a transcript recorded last week could not be read at all.
+//
+// **The prefix is imported rather than retyped**, which is the whole of what keeps this from being a
+// guess about another module's output — the shape `time-reported-failure.ts` already uses for
+// `status_icons`. A rename over there breaks the build here rather than silently emptying the table.
+//
+// **The parse is split from the aggregation, and the split is structural rather than tidy.** This
+// module is reached from `time-transcript-line.ts`, which `time-spans.ts` imports; a single module
+// that also aggregated would need `Span`, and `time-spans → time-transcript-line → here → time-spans`
+// is a cycle. `time-single-check.ts` beside `time-single-checks.ts` is the same pair for the same
+// reason, so this is that seam applied again rather than a new one.
+//
+// **What is read is the row, never the total.** `followup stages total:` is the sum of the rows, so
+// parsing it would give this module a second source for one number and a way for the two to
+// disagree; the caller sums the rows it has. The two prefixes do not collide — the total's fourteenth
+// character is `s` where the row's is `:` — so a row scan cannot pick the total up by accident.
+
+const LINE_SEPARATOR = '\n'
+// **The row is read from its end, not from the gap in its middle.** The printer pads the stage name
+// to a fixed width so the durations line up, and reading the two as whitespace-separated fields works
+// only for as long as every name is shorter than that width — `completion-and-epic-close` is already
+// 25 of the 26. A name that reached it would make `padEnd` a no-op, the printer would emit
+// `some-very-long-stage12.3 s`, and a field split would take `some-very-long-stage12.3` for the name
+// and `NaN` for the seconds — dropping the row silently, which is the going-quiet-without-failing this
+// module's header argues against. The duration and its unit are `time_format.format_seconds`'s output,
+// so the tail is the one part of the row whose shape the alignment cannot move.
+const SECONDS_SUFFIX = ' s'
+const DIGIT_OR_POINT = /[\d.]/u
+// Written here rather than imported: `time-format.ts` keeps its own copy private, and reaching for
+// `run-progress.ts` would pull a command module into the parse for one number.
+const MS_PER_SECOND = 1000
+const NO_STAGES: ReadonlyArray<FollowupStage> = []
+
+// Leading whitespace is trimmed for the same reason `time-reported-failure.ts` trims it: the printer
+// indents nothing, but a harness that wraps or previews a body may, and the row is still the row.
+function stage_body(line: string): string | undefined {
+	const trimmed = line.trimStart()
+
+	if (!trimmed.startsWith(git_followup_stages.STAGE_LINE_PREFIX)) return undefined
+
+	return trimmed.slice(git_followup_stages.STAGE_LINE_PREFIX.length)
+}
+
+// Where the duration begins: the run of digits and points closing the row. **Walked rather than
+// matched.** A pattern describing the name as well would need a lazy or greedy prefix beside the
+// number, which backtracks — `sonarjs/super-linear-regex` refuses it, and it is right to: this is one
+// pass over a row whose length nothing bounds.
+function digits_start(head: string): number {
+	let index = head.length
+
+	while (index > 0 && DIGIT_OR_POINT.test(head.charAt(index - 1))) index -= 1
+
+	return index
+}
+
+// **An empty run is not a zero-second stage**, and it is tested for rather than folded into the
+// number: `Number('')` is `0`, so a row that ended in the unit with no digits in front of it would
+// otherwise be reported as a lap that ran and took no time — which is the reading this module exists
+// to keep the table out of.
+function is_duration(digits: string): boolean {
+	return digits !== '' && Number.isFinite(Number(digits))
+}
+
+// A row that does not end in a duration is dropped rather than counted as zero — a body the harness
+// truncated is the common cause, and a zero there would read as a stage that ran and took no time.
+function to_stage(body: string): FollowupStage | undefined {
+	const text = body.trimEnd()
+
+	if (!text.endsWith(SECONDS_SUFFIX)) return undefined
+
+	const head = text.slice(0, -SECONDS_SUFFIX.length)
+	const start = digits_start(head)
+	const name = head.slice(0, start).trim()
+	const digits = head.slice(start)
+
+	if (name === '' || !is_duration(digits)) return undefined
+
+	return { name, duration_ms: Number(digits) * MS_PER_SECOND }
+}
+
+// **The `includes` guard is the whole of what keeps this cheap.** `to_block` runs it over every tool
+// result of every session, and almost none of them are a `followup` run: a scan that found nothing
+// would still have allocated a line array per body. A substring test allocates nothing, and the split
+// below is paid only by the handful of bodies that actually carry the block.
+function read_stages(text: string): ReadonlyArray<FollowupStage> {
+	if (!text.includes(git_followup_stages.STAGE_LINE_PREFIX)) return NO_STAGES
+
+	return text
+		.split(LINE_SEPARATOR)
+		.map((line) => stage_body(line))
+		.filter((body): body is string => body !== undefined)
+		.map((body) => to_stage(body))
+		.filter((stage): stage is FollowupStage => stage !== undefined)
+}
+
+const time_followup_stage = { NO_STAGES, read_stages }
+
+export { time_followup_stage }

package/scripts/time-runtime/time-format.ts

@@ -0,0 +1,186 @@
+// The column and number formatting every timing report is laid out through (joshuafolkken/kit#1309).
+//
+// It was `time-report.ts`'s until three renderers shared it: the run scope's own tables, the epic
+// scope's child rows, and the failure block `time-failures.ts` prints. Two of those already reached
+// in through the `time_report` namespace for the widths, which is what made the split the honest
+// place to cut — a second set of column rules beside a second renderer is the clone `CLAUDE.md`
+// prohibits, in the one place where a drift would make two tables of the same report disagree about
+// where the numeric column starts.
+//
+// **It holds no timing knowledge at all** — no spans, no categories, no phases. That is what keeps
+// the dependency one-way: `time-report.ts` and `time-failures.ts` both import this, and nothing here
+// imports either of them. **The words two blocks must spell identically are the exception**, and they
+// are here for the reason `NO_CALLS` is: a label printed by two renderers, one of which cannot import
+// the other, has to be written once or the two reports come to disagree about what a row is called.
+
+const MS_PER_MINUTE = 60_000
+const MS_PER_SECOND = 1000
+const MINUTE_DECIMALS = 1
+const SECOND_DECIMALS = 1
+const PERCENT_SCALE = 100
+const PERCENT_DECIMALS = 1
+const LABEL_WIDTH = 24
+// Wide enough for a three-digit run (`335.4 min`), so a long session's rows stay in column with a
+// short one's rather than pushing the share out by a character.
+const MINUTES_WIDTH = 9
+// The answer a table gives where the half it sums was never read at all, kept apart from the phase
+// table's `not detected` because the two ask different questions: a phase is about a marker, this is
+// about whether anything was read to measure.
+const NOT_MEASURED = 'not measured'
+// What a row says instead of a rate when there was no round trip to divide by. It sits here rather
+// than in `time-report.ts` because two blocks print it — the round-trip price and the bundling block —
+// and `time-bundles.ts` cannot import `time-report.ts`, which imports it (joshuafolkken/kit#1344).
+const NO_CALLS = 'no tool call to divide'
+// The word both the CI-cycle block and the gate-runtime block put in front of their naked-seconds
+// figure (joshuafolkken/kit#1812). Two renderers of the same report, and `time-cycles.ts` cannot
+// import `time-gate-runs.ts` nor the reverse, so it is written once here — the rule this file's header
+// states, and the reason `NO_CALLS` already sits beside it.
+const NAKED_PREFIX = 'naked '
+// The category labels, shared with the epic scope's table and with the round-trip block's price row
+// rather than spelled out in each. The tables answer the same question at three scales, so a label
+// renamed in one and not the others is a report that disagrees with itself — which is the defect
+// joshuafolkken/kit#1295 was filed for. They moved here from `time-report.ts` when the price row
+// became a third printer and its block a module that cannot import that file
+// (joshuafolkken/kit#1385).
+const MODEL_LABEL = 'model wait'
+const TOOL_LABEL = 'tool execution'
+const HUMAN_LABEL = 'human wait'
+const CI_LABEL = 'CI wait'
+// How many rows of a table any of these reports prints. Capped, because a long run touches thirty-odd
+// distinct leading commands and a table that long is read by nobody. `--json` carries every row the
+// report holds, so the display cap costs a caller nothing.
+//
+// **It moved here when the segment and per-invocation tables became the fourth and fifth renderers to
+// need it** (joshuafolkken/kit#1311). Those two cannot import `time-report.ts`, which imports them —
+// and a second cap beside a second renderer is exactly the drift this file was split out to prevent.
+const MAX_ROWS = 15
+// What separates the facts inside one row's third column — a check's conclusion from its outcome
+// note, a distribution's range from its sample count. Written once so two renderers of the same
+// report cannot come to punctuate their suffixes differently (joshuafolkken/kit#1312).
+const SUFFIX_SEPARATOR = ' · '
+// What joins the two ends of an aggregated row's range, and the unit the sample behind it is counted
+// in. They sit here rather than beside one renderer because two of them print a spread now — the
+// duration tables of `--last` and the turn-count table both scopes share — and a private copy beside
+// the second is how one report would come to punctuate its ranges two ways
+// (joshuafolkken/kit#1763).
+const RANGE_SEPARATOR = ' – '
+const RUN_UNIT = 'run(s)'
+// The `HH:MM:SS` slice of an ISO instant, and what joins two of them into a window. UTC rather than
+// local time, because the report's own `started_at` / `ended_at` already are — a table in one zone
+// beside a header in another is a report that cannot be read against itself.
+//
+// **They moved here from `time-segments.ts` when the model-gap block became a second renderer of a
+// clock window** (joshuafolkken/kit#1386). A private copy beside the second block is the clone
+// `CLAUDE.md` prohibits, in the one place a drift would make two tables of the same report disagree
+// about which hour a stretch sat in.
+const CLOCK_START = 11
+const CLOCK_END = 19
+const WINDOW_ARROW = ' → '
+
+// **The parenthetical says "this report" rather than "them all"** (joshuafolkken/kit#1301): since
+// `--top` can cut the record itself before either rendering, a promise that `--json` carries every row
+// *there ever was* would be false beside a `--top` above this display cap — and the report would then
+// contradict its own truncation note. What was cut from the record, if anything, is said in `notes`;
+// what is cut from a table is said here.
+function overflow_line(row_count: number): Array<string> {
+	if (row_count <= MAX_ROWS) return []
+
+	return [
+		`  … and ${String(row_count - MAX_ROWS)} more (--json carries every row this report holds)`,
+	]
+}
+
+function format_minutes(duration_ms: number): string {
+	return `${(duration_ms / MS_PER_MINUTE).toFixed(MINUTE_DECIMALS)} min`
+}
+
+// Seconds rather than minutes for a per-turn figure: one turn is tens of seconds, and `0.1 min` is
+// too coarse to show the rise across a batch that this scale exists to make visible.
+function format_seconds(duration_ms: number): string {
+	return `${(duration_ms / MS_PER_SECOND).toFixed(SECOND_DECIMALS)} s`
+}
+
+function format_share(part: number, whole: number): string {
+	if (whole === 0) return 'n/a'
+
+	return `${((part / whole) * PERCENT_SCALE).toFixed(PERCENT_DECIMALS)}%`
+}
+
+// A dollar figure, to the caller's own precision. Two cost blocks print money now — the phase costs
+// and the per-subagent context-construction costs — and each rounds to a different place (a run total
+// to the cent, a per-round-trip figure finer), so the decimals are the caller's and only the `$` and
+// the `toFixed` are shared. It sits here beside the other number formatters rather than in one block,
+// for the reason `format_minutes` does: a second copy beside the second renderer is how two cost rows
+// of one report come to punctuate a dollar amount two ways (joshuafolkken/kit#1606).
+function usd(amount: number, decimals: number): string {
+	return `$${amount.toFixed(decimals)}`
+}
+
+// The one place the three columns are laid out, so a row carrying words instead of a duration lines
+// up with the rows that carry one rather than overrunning the numeric column.
+function format_columns(label: string, minutes: string, suffix: string): string {
+	return `  ${label.padEnd(LABEL_WIDTH)}${minutes.padStart(MINUTES_WIDTH)}   ${suffix}`
+}
+
+function format_row(label: string, duration_ms: number, suffix: string): string {
+	return format_columns(label, format_minutes(duration_ms), suffix)
+}
+
+// **A share nobody read says so rather than totalling zero.** The duration column is left empty
+// because there is no duration — not a short one — which is the same shape an undetected phase and a
+// child that never ran already print.
+function unmeasured_row(label: string): string {
+	return format_columns(label, '', NOT_MEASURED)
+}
+
+// **The ends are handed over already formatted**, so one aggregated table can spell its range in
+// minutes and another in turns while both are punctuated identically. The sample count rides at the
+// end because it is the qualifier: two rows with the same spread are not the same evidence when one
+// was read from nine runs and the other from two.
+function format_spread(min: string, max: string, sample_count: number): string {
+	const range = `${min}${RANGE_SEPARATOR}${max}`
+
+	return `${range}${SUFFIX_SEPARATOR}${String(sample_count)} ${RUN_UNIT}`
+}
+
+function format_clock(timestamp_ms: number): string {
+	return new Date(timestamp_ms).toISOString().slice(CLOCK_START, CLOCK_END)
+}
+
+function format_window(started_ms: number, ended_ms: number): string {
+	return `${format_clock(started_ms)}${WINDOW_ARROW}${format_clock(ended_ms)}`
+}
+
+// The indent a report's notes sit under, beneath its heading. Written once because three renderers
+// print them — the run scope, the epic scope and the distribution — and a fourth copy is how two
+// tables of one command would come to indent the same sentence differently (joshuafolkken/kit#1312).
+function note_lines(notes: ReadonlyArray<string>): Array<string> {
+	return notes.map((note) => `  ${note}`)
+}
+
+const time_format = {
+	MAX_ROWS,
+	NO_CALLS,
+	NAKED_PREFIX,
+	SUFFIX_SEPARATOR,
+	NOT_MEASURED,
+	MODEL_LABEL,
+	TOOL_LABEL,
+	HUMAN_LABEL,
+	CI_LABEL,
+	overflow_line,
+	format_minutes,
+	format_seconds,
+	format_share,
+	usd,
+	format_columns,
+	format_row,
+	format_spread,
+	// `format_clock` stays private: `format_window` is its only caller, and a namespace that offers
+	// both invites a second renderer to join the two with its own arrow.
+	format_window,
+	unmeasured_row,
+	note_lines,
+}
+
+export { time_format }