@joshuafolkken/kit 1.2114.0 → 1.3000.0

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

@@ -2,6 +2,7 @@ import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import type { FollowupStage } from '#scripts/followup/git-followup-stages'
 import { time_background } from './time-background'
 import { time_followup_stage } from './time-followup-stage'
+import { time_josh_names } from './time-josh-names'
 import { time_reported_failure } from './time-reported-failure'
 import { time_shell } from './time-shell'
 import { time_tool_call, type ToolCall } from './time-tool-call'
@@ -28,8 +29,8 @@ const { NO_CALL, UNKNOWN_CALL, UNKNOWN_TOOL, to_tool_call } = time_tool_call
 // ending at a tool result is that tool's execution, one ending at a user prompt is human wait.
 // Classifying by pairs instead would double-count parallel tool calls and leave the three shares
 // summing to something other than the elapsed time — the property that makes two runs comparable.
-// Measured against three sessions restored by hand: 49.6 / 73.3 / 54.6 minutes, every share within
-// 0.4 points of the hand figure.
+// Measured against three sessions restored by hand, every share within 0.4 points of the hand
+// figure.
 
 const ASSISTANT_TYPE = 'assistant'
 const USER_TYPE = 'user'
@@ -372,10 +373,9 @@ function parse_timeline(text: string): Timeline {
 }
 
 // **"No span was read" is the one criterion every scope withholds a transcript figure on**.
-// A run whose transcript could not be attributed, a child of an epic in
-// that state, and a batch no child contributed to are the same fact asked at three scales, and each
-// used to spell it out for itself — which is how the run scope came to print three `0.0 min` rows
-// beside the epic scope's `not measured` for the very same child.
+// A run without an attributed transcript, an epic child in that state, and a batch without child
+// contributions are the same missing measurement at three scales. Sharing the criterion keeps
+// every scope from presenting missing data as a zero duration.
 //
 // It takes the count rather than the array so the three callers can pass what they hold: the spans
 // themselves before a report exists, and `TimeReport.span_count` afterwards.
@@ -399,8 +399,8 @@ const time_spans = {
 	// Re-exported so the suites that measure how a command is read keep asking one namespace, and so
 	// `time-shell.ts` moving out of this file changed no call site.
 	bash_label: time_shell.bash_label,
-	josh_command_of: time_shell.josh_command_of,
-	josh_commands_of: time_shell.josh_commands_of,
+	josh_command_of: time_josh_names.josh_command_of,
+	josh_commands_of: time_josh_names.josh_commands_of,
 	to_tool_call,
 	parse_line,
 	parse_timeline,

package/scripts/time-runtime/time-tool-call.ts

@@ -1,6 +1,7 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import { time_background } from './time-background'
 import { time_bundle_call } from './time-bundle-call'
+import { time_josh_names } from './time-josh-names'
 import { time_markers, type PhaseMarker } from './time-markers'
 import { time_shell } from './time-shell'
 import { time_single_check } from './time-single-check'
@@ -132,13 +133,13 @@ function non_bash_call(name: string, input: unknown, message_id: string): ToolCa
 
 function bash_call(input: unknown, message_id: string): ToolCall {
 	const command = time_shell.bash_command(input)
-	const josh_command = time_shell.josh_command_of(command)
+	const josh_command = time_josh_names.josh_command_of(command)
 
 	return {
 		label: time_shell.bash_label(command),
 		josh_command,
-		josh_commands: time_shell.josh_commands_of(command),
-		josh_signatures: time_shell.josh_signatures_of(command),
+		josh_commands: time_josh_names.josh_commands_of(command),
+		josh_signatures: time_josh_names.josh_signatures_of(command),
 		check_key: time_single_check.check_key(josh_command, command),
 		marker: time_markers.bash_marker(command),
 		message_id,

package/scripts/time-runtime/time-transcript-block.ts

@@ -0,0 +1,172 @@
+import type { FollowupStage } from '#scripts/followup/git-followup-stages'
+import type { TranscriptBlock, TranscriptContent } from '#scripts/lib/transcript-record'
+import { time_background } from './time-background'
+import { time_followup_stage } from './time-followup-stage'
+import { time_reported_failure } from './time-reported-failure'
+
+// One content block of a transcript line, read into the shape the span walk works on.
+//
+// It moved out of `time-transcript-line.ts` when that file reached its length limit
+// (joshuafolkken/kit#7055): the block is read on its own, and the line only gathers its blocks beside
+// the fields read off the line itself.
+//
+// **The block reader is not `cost-blocks.ts` and could not have been.** That module flattens every
+// line into one list of blocks for a token estimate, dropping the `id` / `tool_use_id` pair a call is
+// matched to its result by. A `tool_result`'s `is_error` is read as three answers — absent for the
+// tools that never report one — and its `content` only to recover the outcome a pipeline threw away.
+
+// How much of an errored body is kept. A refusal's body *is* the reason the
+// harness wrote back, from its first character, so an opening this long identifies the speaker
+// without retaining the output of every failed command a session ran.
+const ERROR_TEXT_LIMIT = 256
+// The icon every guard refusal opens with. It is not `status_icons.FAIL_ICON`
+// — that one (`✗`) marks a josh check's failing item, which `has_failure_line` scans for; this one
+// marks a PreToolUse hook's *deny* reason, which is a different body carried in a different result. No
+// shared constant exists because each guard writes the literal in its own reason, so the one place a
+// refusal is *detected* names it here.
+const REFUSAL_MARKER = '⛔'
+// The label the harness puts in front of a PreToolUse hook's deny reason, naming the hook and the tool.
+const HOOK_ERROR_LABEL = /^PreToolUse:\S+ hook error: /u
+// A line that is one bare verdict token — `cut`, `busy`, `not-a-lane` — the single word a josh verdict
+// command prints on standard output. How many are kept bounds the field the
+// way `ERROR_TEXT_LIMIT` bounds `error_text`.
+const TOKEN_LINE = /^[a-z][a-z-]*$/u
+const TOKEN_LINE_LIMIT = 8
+
+interface Block {
+	type: string
+	name: string
+	id: string
+	result_id: string
+	input: unknown
+	// `undefined` where the block carried no `is_error` field, which is a different fact from
+	// `false`: one is a tool that reports no outcome, the other a call that succeeded.
+	is_error: boolean | undefined
+	// Whether the body carried a line opening with josh's failure icon — the one bit of it anything
+	// reads. The text itself is deliberately not kept: a field holding it
+	// would retain every byte the session's tools printed for the length of the parse.
+	has_failure_line: boolean
+	// The stage rows a `pnpm josh followup` call printed into its own output.
+	// Read here for the same reason the bit above is, and it obeys the same
+	// prohibition: what is kept is the ten-odd parsed laps, never the body they were read from. Empty
+	// for every other tool result, which is nearly all of them.
+	followup_stages: ReadonlyArray<FollowupStage>
+	// The opening of the body of a result the harness wrote back as a failure, and `''` for every
+	// other block. It obeys the same prohibition as the two fields above —
+	// what is kept is a bounded opening, never the whole body — and it exists so a reader asking
+	// which refusal a line carried can be answered from the parsed block rather than by matching
+	// `"is_error":true` against the raw line, a test one whitespace in the serializer defeats and
+	// which cannot tell one errored block from another on the same line.
+	error_text: string
+	// Which guard refused this call, read off the opening of an errored result and `''` for every other
+	// block. It obeys the same prohibition as `error_text` — what is kept is a
+	// short label, never the body — and it exists so the per-guard refusal breakdown can be answered from
+	// the parsed block rather than by re-scanning the body downstream. `''` where the result was not a
+	// `⛔` refusal, so a reader tells "no guard spoke" from "this guard spoke" without a second parse.
+	refusal_guard: string
+	// The bare-token lines of a result that did not fail, and `[]` for every other block.
+	// It obeys the same prohibition as `error_text` — what is kept is a few
+	// single words, never the body — and it exists so the verdict a josh command answered with
+	// (`run:cut`'s `cut`) is read from the parsed block rather than by searching the raw line.
+	token_lines: ReadonlyArray<string>
+	// The id the harness assigned to a command it took into the background, and `''` for every other
+	// block. It is the fourth field read off the body under the same
+	// prohibition as the three above — what is kept is the id, never the text it was read from — and
+	// it is what pairs a launch with the call that later reads its output, so the minutes the command
+	// actually ran can be placed on the timeline instead of only the seconds its launch call took.
+	background_id: string
+	// The id of a subagent this block launched into the background, and `''` for every other block
+	// — apart from `background_id` so the timeline windows stay commands only.
+	agent_id: string
+	// How many characters the body carried, and `0` for a block with none — the size a tool result
+	// adds to every later request's context, which `cost:audit` sums per tool (joshuafolkken/kit#7055).
+	// It obeys the same prohibition: the count is kept, never the body.
+	result_chars: number
+}
+
+// The four string fields, defaulted together and apart from the two that are not strings. Split out
+// so neither half carries every `??` in the block: read as one function the defaulting alone reached
+// the complexity limit, and the next field added would have had to be squeezed in beside them.
+function block_names(raw: TranscriptBlock): Pick<Block, 'type' | 'name' | 'id' | 'result_id'> {
+	return {
+		type: raw.type ?? '',
+		name: raw.name ?? '',
+		id: raw.id ?? '',
+		result_id: raw.tool_use_id ?? '',
+	}
+}
+
+// The body a refusal opens with, the harness's own label stripped — shared with `rule-value.ts`.
+function refusal_body(text: string): string {
+	return text.trimStart().replace(HOOK_ERROR_LABEL, '')
+}
+
+// **A refusal is identified by what its body opens with, never by what it carries inside**.
+// The hook denies a call on behalf of the one guard whose trigger fired and
+// writes that guard's reason back as the whole result, so the speaker is the token after the `⛔` and
+// before the first `:` — `⛔ pre-gate cut: …` is `pre-gate cut`. A reason with no colon (a headline
+// like `⛔ scoped checks not green on this tree`) is taken whole. Reading the opening rather than
+// searching the body is what stops a result that merely quoted a reason being read as a refusal.
+//
+// **The harness writes the reason behind its own label** — `PreToolUse:Edit hook error: ⛔ …` — so that
+// label is stripped before the opening is read. Without it no live refusal
+// carried a guard: the fixtures wrote the bare `⛔` body and passed while every recorded one read `''`.
+function guard_from_refusal(text: string): string {
+	const trimmed = refusal_body(text)
+	if (!trimmed.startsWith(REFUSAL_MARKER)) return ''
+
+	const headline = trimmed.slice(REFUSAL_MARKER.length).split('\n', 1)[0]?.trimStart() ?? ''
+	const colon = headline.indexOf(':')
+
+	return (colon === -1 ? headline : headline.slice(0, colon)).trim()
+}
+
+function token_lines_of(text: string): Array<string> {
+	return text
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => TOKEN_LINE.test(line))
+		.slice(0, TOKEN_LINE_LIMIT)
+}
+
+// **The body is flattened once and every reader is handed the text.** `result_text` is what turns a
+// content field that may be a string or a list of blocks into one string, and it is idempotent on a
+// string — so passing its own output back to `has_failure_line` reads exactly as passing the raw
+// field did, at one flattening instead of two.
+function to_block(raw: TranscriptBlock): Block {
+	const text = time_reported_failure.result_text(raw.content)
+	const is_error = raw.is_error ?? undefined
+
+	return {
+		...block_names(raw),
+		input: raw.input,
+		is_error,
+		has_failure_line: time_reported_failure.has_failure_line(text),
+		followup_stages: time_followup_stage.read_stages(text),
+		error_text: is_error === true ? text.slice(0, ERROR_TEXT_LIMIT) : '',
+		refusal_guard: is_error === true ? guard_from_refusal(text) : '',
+		token_lines: is_error === true ? [] : token_lines_of(text),
+		background_id: time_background.launch_id(text),
+		agent_id: time_background.agent_launch_id(text),
+		result_chars: text.length,
+	}
+}
+
+// A user turn written as a bare string carries no blocks, which is exactly right: it is a prompt,
+// and a prompt has no tool result to match.
+function to_blocks(content: TranscriptContent | null | undefined): Array<Block> {
+	return typeof content === 'string' || content === null || content === undefined
+		? []
+		: content.map((block) => to_block(block))
+}
+
+const time_transcript_block = {
+	ERROR_TEXT_LIMIT,
+	TOKEN_LINE_LIMIT,
+	guard_from_refusal,
+	refusal_body,
+	to_blocks,
+}
+
+export type { Block }
+export { time_transcript_block }

package/scripts/time-runtime/time-transcript-line.ts

@@ -1,107 +1,36 @@
-import type { FollowupStage } from '#scripts/followup/git-followup-stages'
 import { json_value } from '#scripts/lib/json-value'
 import {
 	transcript_record,
-	type TranscriptBlock,
 	type TranscriptContent,
 	type TranscriptMessage,
 	type TranscriptRecord,
 } from '#scripts/lib/transcript-record'
 import { time_background } from './time-background'
-import { time_followup_stage } from './time-followup-stage'
 import { time_instant } from './time-instant'
-import { time_reported_failure } from './time-reported-failure'
+import { time_transcript_block, type Block } from './time-transcript-block'
 
 // One line of a session transcript, read into the shape the span walk works on.
 //
 // It moved out of `time-spans.ts` when that file passed its length limit — the seam that file is
 // already cut along elsewhere (`time-shell.ts`, `time-single-check.ts`), where the *reading* of a
 // field lives beside the field and the arithmetic stays next door. What is here is nothing about
-// time: the two records a line yields, and the read that turns a parsed line into one.
-//
-// **The block reader is not `cost-blocks.ts` and could not have been.** That module flattens every
-// line into one list of blocks for a token estimate, dropping the `id` / `tool_use_id` pair a call is
-// matched to its result by and the line boundary a timestamp belongs to. Both are the whole input
-// here.
+// time: the record a line yields, and the read that turns a parsed line into one. Its blocks are read
+// by `time-transcript-block.ts`, split out when this file reached its length limit
+// (joshuafolkken/kit#7055).
 //
 // The line's schema is `transcript-record.ts`'s, shared with every other reader of these lines. A
 // message `id` groups the lines of one assistant turn — Claude Code writes one line per content block
 // — so "how many calls did that turn make" groups by it. `gitBranch` is where the issue number lives
 // (`josh git` names a branch `<N>-<slug>`), read here so `josh time --issue` and `josh cost --issue`
-// answer from the same field. A `tool_result`'s `is_error` is read as three answers — absent for the
-// tools that never report one — and its `content` only to recover the outcome a pipeline threw away.
+// answer from the same field.
 
 const UNKNOWN_BRANCH = ''
 // The field an attachment line carries the notice in, named rather than written as a literal.
 const PROMPT_KEY = 'prompt'
 const NO_MESSAGE_ID = ''
-// How much of an errored body is kept. A refusal's body *is* the reason the
-// harness wrote back, from its first character, so an opening this long identifies the speaker
-// without retaining the output of every failed command a session ran.
-const ERROR_TEXT_LIMIT = 256
-// The icon every guard refusal opens with. It is not `status_icons.FAIL_ICON`
-// — that one (`✗`) marks a josh check's failing item, which `has_failure_line` scans for; this one
-// marks a PreToolUse hook's *deny* reason, which is a different body carried in a different result. No
-// shared constant exists because each guard writes the literal in its own reason, so the one place a
-// refusal is *detected* names it here.
-const REFUSAL_MARKER = '⛔'
-// The label the harness puts in front of a PreToolUse hook's deny reason, naming the hook and the tool.
-const HOOK_ERROR_LABEL = /^PreToolUse:\S+ hook error: /u
 // The label the harness puts in front of a Stop hook's block reason when it sends the turn back.
 // The reason follows on the next line, opening with the same `⛔` a deny does.
 const STOP_FEEDBACK_LABEL = /^Stop hook feedback:\s*/u
-// A line that is one bare verdict token — `cut`, `busy`, `not-a-lane` — the single word a josh verdict
-// command prints on standard output. How many are kept bounds the field the
-// way `ERROR_TEXT_LIMIT` bounds `error_text`.
-const TOKEN_LINE = /^[a-z][a-z-]*$/u
-const TOKEN_LINE_LIMIT = 8
-
-interface Block {
-	type: string
-	name: string
-	id: string
-	result_id: string
-	input: unknown
-	// `undefined` where the block carried no `is_error` field, which is a different fact from
-	// `false`: one is a tool that reports no outcome, the other a call that succeeded.
-	is_error: boolean | undefined
-	// Whether the body carried a line opening with josh's failure icon — the one bit of it anything
-	// reads. The text itself is deliberately not kept: a field holding it
-	// would retain every byte the session's tools printed for the length of the parse.
-	has_failure_line: boolean
-	// The stage rows a `pnpm josh followup` call printed into its own output.
-	// Read here for the same reason the bit above is, and it obeys the same
-	// prohibition: what is kept is the ten-odd parsed laps, never the body they were read from. Empty
-	// for every other tool result, which is nearly all of them.
-	followup_stages: ReadonlyArray<FollowupStage>
-	// The opening of the body of a result the harness wrote back as a failure, and `''` for every
-	// other block. It obeys the same prohibition as the two fields above —
-	// what is kept is a bounded opening, never the whole body — and it exists so a reader asking
-	// which refusal a line carried can be answered from the parsed block rather than by matching
-	// `"is_error":true` against the raw line, a test one whitespace in the serializer defeats and
-	// which cannot tell one errored block from another on the same line.
-	error_text: string
-	// Which guard refused this call, read off the opening of an errored result and `''` for every other
-	// block. It obeys the same prohibition as `error_text` — what is kept is a
-	// short label, never the body — and it exists so the per-guard refusal breakdown can be answered from
-	// the parsed block rather than by re-scanning the body downstream. `''` where the result was not a
-	// `⛔` refusal, so a reader tells "no guard spoke" from "this guard spoke" without a second parse.
-	refusal_guard: string
-	// The bare-token lines of a result that did not fail, and `[]` for every other block.
-	// It obeys the same prohibition as `error_text` — what is kept is a few
-	// single words, never the body — and it exists so the verdict a josh command answered with
-	// (`run:cut`'s `cut`) is read from the parsed block rather than by searching the raw line.
-	token_lines: ReadonlyArray<string>
-	// The id the harness assigned to a command it took into the background, and `''` for every other
-	// block. It is the fourth field read off the body under the same
-	// prohibition as the three above — what is kept is the id, never the text it was read from — and
-	// it is what pairs a launch with the call that later reads its output, so the minutes the command
-	// actually ran can be placed on the timeline instead of only the seconds its launch call took.
-	background_id: string
-	// The id of a subagent this block launched into the background, and `''` for every other block
-	// — apart from `background_id` so the timeline windows stay commands only.
-	agent_id: string
-}
 
 interface TranscriptLine {
 	type: string
@@ -124,43 +53,10 @@ interface TranscriptLine {
 	// The guard whose Stop-hook block sent this turn back, or `''` for every other line
 	// — read the way `Block.refusal_guard` is, off the reason's opening.
 	stop_guard: string
-}
-
-// The four string fields, defaulted together and apart from the two that are not strings. Split out
-// so neither half carries every `??` in the block: read as one function the defaulting alone reached
-// the complexity limit, and the next field added would have had to be squeezed in beside them.
-function block_names(raw: TranscriptBlock): Pick<Block, 'type' | 'name' | 'id' | 'result_id'> {
-	return {
-		type: raw.type ?? '',
-		name: raw.name ?? '',
-		id: raw.id ?? '',
-		result_id: raw.tool_use_id ?? '',
-	}
-}
-
-// The body a refusal opens with, the harness's own label stripped — shared with `rule-value.ts`.
-function refusal_body(text: string): string {
-	return text.trimStart().replace(HOOK_ERROR_LABEL, '')
-}
-
-// **A refusal is identified by what its body opens with, never by what it carries inside**.
-// The hook denies a call on behalf of the one guard whose trigger fired and
-// writes that guard's reason back as the whole result, so the speaker is the token after the `⛔` and
-// before the first `:` — `⛔ pre-gate cut: …` is `pre-gate cut`. A reason with no colon (a headline
-// like `⛔ scoped checks not green on this tree`) is taken whole. Reading the opening rather than
-// searching the body is what stops a result that merely quoted a reason being read as a refusal.
-//
-// **The harness writes the reason behind its own label** — `PreToolUse:Edit hook error: ⛔ …` — so that
-// label is stripped before the opening is read. Without it no live refusal
-// carried a guard: the fixtures wrote the bare `⛔` body and passed while every recorded one read `''`.
-function guard_from_refusal(text: string): string {
-	const trimmed = refusal_body(text)
-	if (!trimmed.startsWith(REFUSAL_MARKER)) return ''
-
-	const headline = trimmed.slice(REFUSAL_MARKER.length).split('\n', 1)[0]?.trimStart() ?? ''
-	const colon = headline.indexOf(':')
-
-	return (colon === -1 ? headline : headline.slice(0, colon)).trim()
+	// The billed request an assistant line belongs to and the reasoning effort it ran at, `''` on every
+	// other line — the pair `cost:audit` prices its effort breakdown by (joshuafolkken/kit#7055).
+	request_id: string
+	effort: string
 }
 
 // **Only the harness's own feedback line counts.** It writes a Stop block back as a user turn whose
@@ -173,51 +69,16 @@ function stop_feedback_of(data: TranscriptRecord): string {
 	return content.replace(STOP_FEEDBACK_LABEL, '').trim()
 }
 
-function token_lines_of(text: string): Array<string> {
-	return text
-		.split('\n')
-		.map((line) => line.trim())
-		.filter((line) => TOKEN_LINE.test(line))
-		.slice(0, TOKEN_LINE_LIMIT)
-}
-
-// **The body is flattened once and both readers are handed the text.** `result_text` is what turns a
-// content field that may be a string or a list of blocks into one string, and it is idempotent on a
-// string — so passing its own output back to `has_failure_line` reads exactly as passing the raw
-// field did, at one flattening instead of two.
-function to_block(raw: TranscriptBlock): Block {
-	const text = time_reported_failure.result_text(raw.content)
-	const is_error = raw.is_error ?? undefined
-
-	return {
-		...block_names(raw),
-		input: raw.input,
-		is_error,
-		has_failure_line: time_reported_failure.has_failure_line(text),
-		followup_stages: time_followup_stage.read_stages(text),
-		error_text: is_error === true ? text.slice(0, ERROR_TEXT_LIMIT) : '',
-		refusal_guard: is_error === true ? guard_from_refusal(text) : '',
-		token_lines: is_error === true ? [] : token_lines_of(text),
-		background_id: time_background.launch_id(text),
-		agent_id: time_background.agent_launch_id(text),
-	}
-}
-
-// A user turn written as a bare string carries no blocks, which is exactly right: it is a prompt,
-// and a prompt has no tool result to match.
-function to_blocks(content: TranscriptContent | null | undefined): Array<Block> {
-	return typeof content === 'string' || content === null || content === undefined
-		? []
-		: content.map((block) => to_block(block))
-}
-
 // The two fields read off `message`, taken together because they are one reading: an assistant turn
 // is written as one line per content block with the message's id repeated on each, so the id is what
 // says which blocks belonged to the same turn.
 function message_fields(
 	message: TranscriptMessage | null | undefined,
 ): Pick<TranscriptLine, 'message_id' | 'blocks'> {
-	return { message_id: message?.id ?? NO_MESSAGE_ID, blocks: to_blocks(message?.content) }
+	return {
+		message_id: message?.id ?? NO_MESSAGE_ID,
+		blocks: time_transcript_block.to_blocks(message?.content),
+	}
 }
 
 // **One notice reaches the transcript on any of three line kinds, and which of them a session holds
@@ -255,6 +116,10 @@ function finished_background(data: TranscriptRecord): string {
 		: notice
 }
 
+function request_fields(data: TranscriptRecord): Pick<TranscriptLine, 'request_id' | 'effort'> {
+	return { request_id: data.requestId ?? '', effort: data.effort ?? '' }
+}
+
 // A line without a parseable timestamp is dropped rather than dated: it has no place on a timeline,
 // and inventing one would move every span around it.
 function to_line(data: TranscriptRecord): TranscriptLine | undefined {
@@ -270,7 +135,8 @@ function to_line(data: TranscriptRecord): TranscriptLine | undefined {
 		branch: data.gitBranch ?? UNKNOWN_BRANCH,
 		finished_background: finished_background(data),
 		stop_feedback,
-		stop_guard: guard_from_refusal(stop_feedback),
+		stop_guard: time_transcript_block.guard_from_refusal(stop_feedback),
+		...request_fields(data),
 		...message_fields(data.message),
 	}
 }
@@ -287,14 +153,16 @@ function parse_text(text: string): Array<TranscriptLine> {
 }
 
 const time_transcript_line = {
-	ERROR_TEXT_LIMIT,
+	ERROR_TEXT_LIMIT: time_transcript_block.ERROR_TEXT_LIMIT,
 	NO_MESSAGE_ID,
-	TOKEN_LINE_LIMIT,
-	guard_from_refusal,
+	TOKEN_LINE_LIMIT: time_transcript_block.TOKEN_LINE_LIMIT,
+	guard_from_refusal: time_transcript_block.guard_from_refusal,
 	parse_line,
 	parse_text,
-	refusal_body,
+	refusal_body: time_transcript_block.refusal_body,
 }
 
-export type { Block, TranscriptLine }
+export type { TranscriptLine }
 export { time_transcript_line }
+
+export type { Block } from './time-transcript-block'

package/scripts/time-runtime/transcript-tail.ts

@@ -0,0 +1,39 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
+
+// **The transcript's tail, read with no reader attached** (joshuafolkken/kit#6151): `hook-decision.ts`
+// needs these bytes and nothing else, and reading them through `time-density-hook.ts` pulled the batch
+// guard, the shell parser and the josh alias table into every hook's import graph — a one-line alias
+// edit reached 551 test files.
+
+// How much of the transcript's end is read. The file grows to several megabytes over a long run,
+// 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
+
+// The last `max_bytes` of a file, as text. The leading line is usually cut mid-way, which every
+// reader 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)
+	}
+}
+
+const transcript_tail = { TAIL_BYTES, read_tail }
+
+export { transcript_tail }

package/scripts/ui/ui-shot-cli.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { TOOLKIT_BINS, type_check_step } from '#scripts/gate/type-check-step'
+import { find_package_directory } from '#scripts/josh/package-directory'
+import { package_manifest } from '#scripts/lib/package-manifest'
+import { execa } from 'execa'
+import { z } from 'zod'
+import { ui_shot, type ShotCommand, type ToolkitProbe } from './ui-shot'
+
+// `josh ui:shot <route> [route...]` — the I/O around `ui-shot.ts`: probe the project's toolkit bins
+// and `package.json` scripts, then run the resolved command with the terminal attached, so its image
+// paths and its exit status are the result.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh ui:shot <route> [route...]'
+const FAILURE_EXIT_CODE = 1
+
+const SCRIPTS_MANIFEST_SCHEMA = z.object({ scripts: z.record(z.string(), z.string()).optional() })
+
+// The nearest `package.json` upwards, the one `pnpm run` itself would read from `directory`.
+function read_scripts(directory: string): ReadonlyArray<string> {
+	const manifest = package_manifest.read_manifest_if_valid(
+		find_package_directory(directory),
+		SCRIPTS_MANIFEST_SCHEMA,
+	)
+
+	return Object.keys(manifest?.scripts ?? {})
+}
+
+async function probe_toolkit(
+	directory: string,
+	bin_name: string,
+): Promise<ToolkitProbe | undefined> {
+	const bin_path = find_local_bin_upwards(directory, bin_name)
+	if (bin_path === undefined) return undefined
+
+	return { path: bin_path, commands: await type_check_step.read_toolkit_commands(bin_path) }
+}
+
+async function run_command(command: ShotCommand, directory: string): Promise<number> {
+	const result = await execa(command.file, command.args, {
+		cwd: directory,
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>, directory: string): Promise<number> {
+	if (argv.length === 0) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const resolution = await ui_shot.resolve_shot_command(
+		{
+			toolkit_bins: TOOLKIT_BINS,
+			probe_toolkit: async (bin_name) => await probe_toolkit(directory, bin_name),
+			scripts: read_scripts(directory),
+		},
+		argv,
+	)
+
+	if (resolution.kind === 'missing') {
+		console.error(ui_shot.describe_missing(resolution.tried))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await run_command(resolution.command, directory)
+}
+
+async function main(argv: ReadonlyArray<string>, directory: string): Promise<void> {
+	process.exitCode = await run(argv, directory)
+}
+
+const ui_shot_cli = {
+	main,
+	run,
+	USAGE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	await main(process.argv.slice(ARGV_OFFSET), process.cwd())
+}
+
+export { ui_shot_cli }