@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/cases/cases-interaction.ts

@@ -0,0 +1,183 @@
+import { session_language } from '#scripts/josh/session-language'
+
+// `josh cases`' two interaction boundaries (joshuafolkken/kit#4491), read off the changed source with
+// no I/O: the persistent state paths it names (`state`) and the environment it reads (`env`). The four
+// I/O boundaries in `cases-logic.ts` name what a call can return; these name who else shares the
+// state or the environment — the breakages found only after a merge, in another component's run.
+
+type Interaction = 'state' | 'env'
+
+interface StatePath {
+	// The literal as written, cut before a template placeholder so a search finds its fixed head.
+	path: string
+	// The constants this source binds the literal to — the names another module reaches it through.
+	constants: ReadonlyArray<string>
+}
+
+interface Environment {
+	variables: ReadonlyArray<string>
+	residents: ReadonlyArray<string>
+}
+
+interface Binding {
+	name: string
+	value: string
+}
+
+interface Wording {
+	state: string
+	variable: string
+	resident: string
+	others: string
+	no_others: string
+	search_failed: string
+	state_cases: ReadonlyArray<string>
+	variable_cases: ReadonlyArray<string>
+	resident_cases: ReadonlyArray<string>
+}
+
+const INTERACTIONS: ReadonlyArray<Interaction> = ['state', 'env']
+const QUOTED_LITERAL = /(?<quote>['"`])(?<literal>[^'"`\s]+)\k<quote>/gu
+// A path under `.josh/` with something after the slash, a named lock file, or a `josh-<name>-` file
+// prefix — the temporary-directory records (lane state, ledger, run events) are named that way. The
+// bare `.josh/` root names every state at once, and a bare `.lock` suffix matches every lock in the
+// repository; a `josh-` name with no trailing hyphen is a tag or a keychain service, not a file.
+const STATE_PATH = /(?:\.josh\/[^/])|(?:[^/]\.lock$)|(?:^josh-[a-z][\w-]*-$)/u
+const PLACEHOLDER = /\$\{|<|\*/u
+const CONSTANT_BINDING =
+	/\b(?:const|let)\s+(?<name>[A-Za-z_]\w*)\s*(?::[^=\n]+)?=\s*(?<quote>['"`])(?<value>[^'"`\n]+)\k<quote>/gu
+const ENV_MARK = 'process.env'
+const ENV_LITERAL_KEY =
+	/\bprocess\.env\.(?<dotted>[A-Za-z_]\w*)|\b(?:process\.env|environment)\[\s*['"](?<quoted>\w+)['"]\s*\]/gu
+// The `environment: X = process.env` default-parameter form reads `environment[KEY]` through a
+// constant, so a key held in a constant is resolved against this source's own bindings.
+const ENV_CONSTANT_KEY = /\b(?:process\.env|environment)\[\s*(?<key>[A-Za-z_]\w*)\s*\]/gu
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/u
+// A daemon or a beacon named as an identifier or a module (`eslint-daemon`, `daemon_status`), never
+// the bare word, so prose about "the daemon" does not fire the boundary.
+const RESIDENT = /\b[\w-]*(?:[_-](?:daemon|beacon)|(?:daemon|beacon)[_-])[\w-]*/giu
+// A source names one daemon in many identifiers (`spawn_daemon`, `DAEMON_STOP`); its cases are the
+// kind's, so the kind is the subject.
+const RESIDENT_KIND = /daemon|beacon/iu
+const SLASH = '/'
+
+const JAPANESE: Wording = {
+	state: '共有状態',
+	variable: '環境変数',
+	resident: '常駐プロセス',
+	others: '他の読み書き',
+	no_others: 'なし',
+	search_failed: '検索失敗',
+	state_cases: [
+		'他の書き手との並行書き込み',
+		'他の読み手が古い形式・途中の状態を読む',
+		'自分が書く前に他の書き手が消す',
+	],
+	variable_cases: [
+		'未設定',
+		'親プロセスから継承した値（例 GIT_DIR）',
+		'lane の work tree と main で値が違う',
+	],
+	resident_cases: [
+		'常駐プロセスが古い',
+		'常駐プロセスが不在',
+		'lane の work tree と main で別のプロセスに繋がる',
+	],
+}
+
+const ENGLISH: Wording = {
+	state: 'shared state',
+	variable: 'environment variable',
+	resident: 'resident process',
+	others: 'also read or written by',
+	no_others: 'none',
+	search_failed: 'search failed',
+	state_cases: [
+		'concurrent write by another writer',
+		'another reader reads an old format or a partial state',
+		'another writer deletes it before this write',
+	],
+	variable_cases: [
+		'unset',
+		'value inherited from the parent process (e.g. GIT_DIR)',
+		'differs between the lane work tree and main',
+	],
+	resident_cases: [
+		'resident process is stale',
+		'resident process is absent',
+		'the lane work tree and main reach different processes',
+	],
+}
+
+function fixed_head(literal: string): string {
+	const placeholder = PLACEHOLDER.exec(literal)
+
+	const head = placeholder === null ? literal : literal.slice(0, placeholder.index)
+
+	// `.josh/observations/` and `.josh/observations` name one state, so both search as the latter.
+	return head.endsWith(SLASH) ? head.slice(0, -1) : head
+}
+
+function bindings(content: string): ReadonlyArray<Binding> {
+	return [...content.matchAll(CONSTANT_BINDING)].map((match) => ({
+		name: match.groups?.['name'] ?? '',
+		value: match.groups?.['value'] ?? '',
+	}))
+}
+
+function state_literals(content: string): ReadonlyArray<string> {
+	const heads = [...content.matchAll(QUOTED_LITERAL)].map((match) =>
+		fixed_head(match.groups?.['literal'] ?? ''),
+	)
+
+	return [...new Set(heads.filter((head) => STATE_PATH.test(head)))]
+}
+
+function state_paths_in(content: string): ReadonlyArray<StatePath> {
+	const declared = bindings(content)
+
+	return state_literals(content).map((path) => ({
+		path,
+		constants: declared
+			.filter((binding) => fixed_head(binding.value) === path)
+			.map((binding) => binding.name),
+	}))
+}
+
+function constant_keys(content: string): ReadonlyArray<string> {
+	const values = new Map(bindings(content).map((binding) => [binding.name, binding.value]))
+	const keys = [...content.matchAll(ENV_CONSTANT_KEY)].map((match) =>
+		values.get(match.groups?.['key'] ?? ''),
+	)
+
+	return keys.filter((name): name is string => name !== undefined && ENV_NAME.test(name))
+}
+
+// A source that hands `process.env` on whole, naming no variable, still reads the environment.
+function variables_in(content: string): ReadonlyArray<string> {
+	if (!content.includes(ENV_MARK)) return []
+
+	const literal = [...content.matchAll(ENV_LITERAL_KEY)].map(
+		(match) => match.groups?.['dotted'] ?? match.groups?.['quoted'] ?? '',
+	)
+	const names = [...new Set([...literal, ...constant_keys(content)])]
+
+	return names.length === 0 ? [ENV_MARK] : names
+}
+
+function environment_in(content: string): Environment {
+	const residents = [...content.matchAll(RESIDENT)].map((match) =>
+		(RESIDENT_KIND.exec(match[0])?.[0] ?? '').toLowerCase(),
+	)
+
+	return { variables: variables_in(content), residents: [...new Set(residents)] }
+}
+
+function wording(lang: string = session_language.DEFAULT_SESSION_LANG): Wording {
+	return session_language.is_japanese(lang) ? JAPANESE : ENGLISH
+}
+
+const cases_interaction = { INTERACTIONS, state_paths_in, environment_in, wording }
+
+export type { Environment, Interaction, StatePath, Wording }
+export { cases_interaction }

package/scripts/cases/cases-logic.ts

@@ -1,9 +1,11 @@
+import { session_language } from '#scripts/josh/session-language'
 import { file_reader } from '#scripts/lib/read-file'
+import { cases_interaction } from './cases-interaction'
 
 // `josh cases <path...>`: read the changed paths and answer which I/O
 // boundaries the code crosses — network, process start, filesystem — then name the abnormal cases
 // that boundary always owes. The unit suite blocks network by construction
-// (`scripts/test/test-network-guard.ts`), so a boundary's abnormal cases never run there; this makes
+// (`tools/test/test-network-guard.ts`), so a boundary's abnormal cases never run there; this makes
 // the declaration side name them instead, read off the diff rather than off judgement.
 // `prompts/collaboration-workflow/report-format.md` is the single source of where the answer goes —
 // the second tier of the case-based test declaration ("if it breaks").
@@ -17,6 +19,8 @@ interface BoundaryDefinition {
 	pattern: RegExp
 	// The abnormal cases this boundary always owes, so they land in the second tier.
 	cases: ReadonlyArray<string>
+	// The same cases for an English session, in the same order.
+	english_cases: ReadonlyArray<string>
 }
 
 const BOUNDARIES: ReadonlyArray<BoundaryDefinition> = [
@@ -27,6 +31,14 @@ const BOUNDARIES: ReadonlyArray<BoundaryDefinition> = [
 		// would fire `network` on every markdown edit and defeat the oracle.
 		pattern: /\b(?:fetch|axios|undici|node:https?|XMLHttpRequest)\b/u,
 		cases: ['非200', 'タイムアウト', '接続断', '空レスポンス', '不正JSON', 'レート制限'],
+		english_cases: [
+			'non-200',
+			'timeout',
+			'connection drop',
+			'empty response',
+			'invalid JSON',
+			'rate limit',
+		],
 	},
 	{
 		boundary: 'process',
@@ -36,6 +48,7 @@ const BOUNDARIES: ReadonlyArray<BoundaryDefinition> = [
 		pattern:
 			/\b(?:child_process|execSync|execFileSync|spawnSync)\b|\b(?:exec|execFile|spawn)\s*\(/u,
 		cases: ['非ゼロ終了', 'タイムアウト', '標準エラー出力', '実行ファイル不在'],
+		english_cases: ['non-zero exit', 'timeout', 'stderr output', 'missing executable'],
 	},
 	{
 		boundary: 'fs',
@@ -45,6 +58,13 @@ const BOUNDARIES: ReadonlyArray<BoundaryDefinition> = [
 		pattern:
 			/\b(?:node:fs|fs\/promises|readFileSync|writeFileSync)\b|\b(?:readFile|writeFile|mkdir|unlink|readdir|rm)\s*\(/u,
 		cases: ['ファイル不在', '権限エラー', '空ファイル', '不正な内容', '並行書き込み'],
+		english_cases: [
+			'missing file',
+			'permission error',
+			'empty file',
+			'invalid content',
+			'concurrent write',
+		],
 	},
 	{
 		boundary: 'time',
@@ -57,6 +77,12 @@ const BOUNDARIES: ReadonlyArray<BoundaryDefinition> = [
 		pattern:
 			/\b(?:setInterval|setTimeout|setImmediate|schedule|reschedule|retry)\s*\(|\b(?:cron|crontab|heartbeat|watchdog|liveness)\b/u,
 		cases: ['期待した事象が到来しない', '期限超過', '重複発火', '再試行が尽きる'],
+		english_cases: [
+			'awaited event never arrives',
+			'deadline exceeded',
+			'duplicate firing',
+			'retries exhausted',
+		],
 	},
 ]
 
@@ -76,17 +102,24 @@ function boundaries_in(paths: ReadonlyArray<string>): ReadonlyArray<Boundary> {
 	)
 }
 
-// The abnormal cases owed by the given boundaries, in the fixed boundary order.
-function cases_for(boundaries: ReadonlyArray<Boundary>): ReadonlyArray<string> {
+// The abnormal cases owed by the given boundaries, in the fixed boundary order and in `lang`.
+function cases_for(
+	boundaries: ReadonlyArray<Boundary>,
+	lang: string = session_language.DEFAULT_SESSION_LANG,
+): ReadonlyArray<string> {
+	const is_japanese = session_language.is_japanese(lang)
+
 	return BOUNDARIES.filter((definition) => boundaries.includes(definition.boundary)).flatMap(
-		(definition) => definition.cases,
+		(definition) => (is_japanese ? definition.cases : definition.english_cases),
 	)
 }
 
-// The fixed verdict vocabulary the command can print — the three boundary tokens and `none`. The
-// decision-oracle test asserts its registered vocabulary equals this.
+// The fixed verdict vocabulary the command can print — the four boundary tokens, the two interaction
+// tokens (`cases-interaction.ts`) and `none`. The decision-oracle test asserts its registered
+// vocabulary equals this.
 const VOCABULARY: ReadonlyArray<string> = [
 	...BOUNDARIES.map((definition) => definition.boundary),
+	...cases_interaction.INTERACTIONS,
 	NONE,
 ]
 

package/scripts/ci/pr-classification-main.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { pr_classification } from './pr-classification'
+
+// The `josh pr:classification` entry, kept apart from `pr-classification.ts` because other modules
+// import that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const event_path = process.env['GITHUB_EVENT_PATH']
+	if (!event_path) throw new Error('GITHUB_EVENT_PATH is required')
+
+	const error = pr_classification.check_event(event_path)
+
+	if (error) {
+		console.error(`::error::${error}`)
+		process.exitCode = 1
+	}
+}

package/scripts/ci/pr-classification.ts

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import {
 	BREAKING_CHANGE_LABEL as BREAKING,
+	BUG_LABEL,
 	BUGFIX_LABEL as BUGFIX,
 	RELEASE_CLASSIFICATION_NAMES as CLASSIFICATION_LABELS,
 	ENHANCEMENT_LABEL,
@@ -12,13 +13,13 @@ import { error_text } from '#scripts/lib/error-message'
 import { z } from 'zod'
 
 const CLASSIFICATION_SET: ReadonlySet<string> = new Set(CLASSIFICATION_LABELS)
-const ISSUE_BUG_LABEL = 'bug'
 // The line an Issue body declares its release classification with. A body written by a script
 // (`josh propagate`'s upgrade issue) builds it with `declaration`, so the writer and this parser share
 // one format.
 const DECLARATION_PREFIX = '- リリース分類: '
 const DECLARATION = new RegExp(`^${DECLARATION_PREFIX}(.+)$`, 'gmu')
 const LEGACY_LABELS: ReadonlySet<string> = new Set(['semver-major', 'semver-minor'])
+const LABEL_NAMES_FILTER = '.[].name'
 
 const LABEL = z.object({ name: z.string() })
 const USER = z.object({ login: z.string() })
@@ -70,7 +71,7 @@ function issue_candidates(issue_json: string): ReadonlyArray<ReleaseClassificati
 
 	if (unknown.length > 0) throw new Error(`Unknown release classification: ${unknown.join(', ')}`)
 
-	if (names.includes(ISSUE_BUG_LABEL) && !candidates.includes(BREAKING)) {
+	if (names.includes(BUG_LABEL) && !candidates.includes(BREAKING)) {
 		candidates.push(BUGFIX)
 	}
 
@@ -96,10 +97,14 @@ function select_issue_classification(issue_json: string): ReleaseClassification
 // payload, that run fails, and when it lands in the newer check suite GitHub keeps its red result —
 // a rerun replays the same payload and fails again.
 function fetch_current_labels(repository: string, pull_number: number): ReadonlyArray<string> {
-	const path = `repos/${repository}/issues/${String(pull_number)}/labels`
+	const path = git_gh_api_path.issue_labels_api_path(String(pull_number), repository)
 
 	try {
-		const names = git_gh_exec.exec_gh_api_sync({ path, jq_filter: '.[].name' })
+		const names = git_gh_exec.exec_gh_api_sync({
+			path,
+			should_paginate: true,
+			jq_filter: LABEL_NAMES_FILTER,
+		})
 
 		return names.split('\n').filter((name) => name !== '')
 	} catch (error) {
@@ -119,18 +124,6 @@ function check_event(
 	return classification_error(labels, event.pull_request.user.login)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	const event_path = process.env['GITHUB_EVENT_PATH']
-	if (!event_path) throw new Error('GITHUB_EVENT_PATH is required')
-
-	const error = check_event(event_path)
-
-	if (error) {
-		console.error(`::error::${error}`)
-		process.exitCode = 1
-	}
-}
-
 const pr_classification = {
 	classification_error,
 	check_event,

package/scripts/clone/clone-scan.ts

@@ -17,7 +17,7 @@ import { clone_fingerprint } from './clone-fingerprint'
 // which is what makes two identical relative paths in different repositories a cross-repository clone.
 
 // The directories a package keeps its source in; whichever exist are scanned.
-const SOURCE_ROOTS = ['scripts', 'src']
+const SOURCE_ROOTS = ['scripts', 'tools', 'src']
 const SOURCE_EXTENSION = '.ts'
 // Test files and declarations are not product code, so a shared test helper is not a clone to report.
 const IGNORED_SUFFIXES = ['.test.ts', '.svelte.test.ts', '.d.ts']

package/scripts/cost-runtime/cost-blocks.ts

@@ -1,4 +1,9 @@
 import { json_value } from '#scripts/lib/json-value'
+import {
+	transcript_record,
+	type TranscriptBlock,
+	type TranscriptContent,
+} from '#scripts/lib/transcript-record'
 import { z } from 'zod'
 
 // Reading the content blocks out of a session transcript.
@@ -18,27 +23,7 @@ import { z } from 'zod'
 const CONTENT_ITEM_SCHEMA = z.object({ text: z.string().nullish() })
 const RESULT_CONTENT_SCHEMA = z.union([z.string(), z.array(CONTENT_ITEM_SCHEMA)])
 
-// Every field is optional, including `type`. A required field would make one unexpected block fail
-// the whole array it sits in, and with it every other block on that line — an entire assistant turn
-// dropped from the table because one tool wrote a shape this reader had not seen. A block that
-// parses to nothing contributes nothing, which is the cost it should have.
-const BLOCK_SCHEMA = z.object({
-	type: z.string().nullish(),
-	text: z.string().nullish(),
-	name: z.string().nullish(),
-	input: z.unknown().nullish(),
-	content: RESULT_CONTENT_SCHEMA.nullish(),
-})
-
-const LINE_CONTENT_SCHEMA = z.union([z.string(), z.array(BLOCK_SCHEMA)])
-const MESSAGE_SCHEMA = z.object({ content: LINE_CONTENT_SCHEMA.nullish() })
-const CONTENT_LINE_SCHEMA = z.object({ type: z.string(), message: MESSAGE_SCHEMA.nullish() })
-
-type RawBlock = z.infer<typeof BLOCK_SCHEMA>
-
-const TEXT_TYPE = 'text'
-const TOOL_USE_TYPE = 'tool_use'
-const TOOL_RESULT_TYPE = 'tool_result'
+const { TEXT_TYPE, TOOL_USE_TYPE, TOOL_RESULT_TYPE } = transcript_record
 const BASH_TOOL = 'Bash'
 const COMMAND_KEY = 'command'
 
@@ -71,7 +56,7 @@ function split_bash_input(input: unknown): { command: string; rest: string } {
 	}
 }
 
-function to_tool_use(block: RawBlock): ContentBlock {
+function to_tool_use(block: TranscriptBlock): ContentBlock {
 	const tool_name = block.name ?? ''
 	const is_bash = tool_name === BASH_TOOL
 	const { command, rest } = is_bash
@@ -83,31 +68,33 @@ function to_tool_use(block: RawBlock): ContentBlock {
 
 // A tool result is either a plain string or a list of blocks. Only the textual items are counted:
 // an image block carries no text here, and inventing a size for it would put a made-up number in a
-// table whose whole purpose is to be compared against another run's.
-function result_text(content: string | ReadonlyArray<z.infer<typeof CONTENT_ITEM_SCHEMA>>): string {
-	if (typeof content === 'string') return content
-
-	return content.map((item) => item.text ?? '').join('')
+// table whose whole purpose is to be compared against another run's. A body of neither shape
+// contributes nothing rather than dropping the line it sits on.
+function result_text(content: unknown): string {
+	const parsed = RESULT_CONTENT_SCHEMA.safeParse(content)
+	if (!parsed.success) return ''
+	if (typeof parsed.data === 'string') return parsed.data
+
+	return parsed.data.map((item) => item.text ?? '').join('')
 }
 
 // Everything that is not a tool call: a result contributes its textual content, and anything else —
 // text, thinking, a block type this reader has never seen — contributes its `text`, which for
 // thinking is the empty string Claude Code writes there.
-function to_plain_block(block: RawBlock): ContentBlock {
+function to_plain_block(block: TranscriptBlock): ContentBlock {
 	const base = { type: block.type ?? '', tool_name: '', command: '' }
-	const text =
-		block.type === TOOL_RESULT_TYPE ? result_text(block.content ?? '') : (block.text ?? '')
+	const text = block.type === TOOL_RESULT_TYPE ? result_text(block.content) : (block.text ?? '')
 
 	return { ...base, text }
 }
 
-function to_block(block: RawBlock): ContentBlock {
+function to_block(block: TranscriptBlock): ContentBlock {
 	return block.type === TOOL_USE_TYPE ? to_tool_use(block) : to_plain_block(block)
 }
 
 // A user turn whose content is a bare string — the prompt itself, plus whatever a `UserPromptSubmit`
 // hook injected into it. Counted as text, which is what it is.
-function to_blocks(content: string | ReadonlyArray<RawBlock>): Array<ContentBlock> {
+function to_blocks(content: string | ReadonlyArray<TranscriptBlock>): Array<ContentBlock> {
 	if (typeof content === 'string') {
 		return [{ type: TEXT_TYPE, tool_name: '', command: '', text: content }]
 	}
@@ -116,13 +103,11 @@ function to_blocks(content: string | ReadonlyArray<RawBlock>): Array<ContentBloc
 }
 
 // A blank line, a line that is not JSON, and a line carrying no message content are one answer:
-// nothing to count. With `BLOCK_SCHEMA` accepting anything object-shaped, the only line lost whole
+// nothing to count. With the block schema accepting anything object-shaped, the only line lost whole
 // is one that is not JSON at all — which `cost-usage.ts` already counts as unparseable, so
 // reporting it again here would double one missing-data figure.
-function content_of(line: string): z.infer<typeof LINE_CONTENT_SCHEMA> | undefined {
-	const parsed = CONTENT_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
-
-	return parsed.success ? (parsed.data.message?.content ?? undefined) : undefined
+function content_of(line: string): TranscriptContent | undefined {
+	return transcript_record.parse(line)?.message?.content ?? undefined
 }
 
 function parse_line(line: string): Array<ContentBlock> {

package/scripts/cost-runtime/cost-cli.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { codex_usage } from './codex-usage'
@@ -20,7 +18,6 @@ import { transcript_cwd } from './transcript-cwd'
 // `backlogrun` / `halfrun` / `pre-gate-cut` ask, and the `josh time` run-timing report keeps the
 // hand-off aggregates used to compare the shared context-cut threshold.
 
-const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const USAGE = 'Usage: josh cost (--cut | --over <tokens-per-request>) [--path <dir>]'
 // The read-only verdict's third answer, beside `cost_verdict`'s over/under: a session that cannot be
@@ -29,6 +26,12 @@ const UNMEASURABLE_VERDICT = 'unmeasurable'
 
 type CostVerdict = ReturnType<typeof cost_verdict.classify> | typeof UNMEASURABLE_VERDICT
 
+interface SessionFigures {
+	verdict: CostVerdict
+	cost: number | undefined
+	threshold: number
+}
+
 interface Options {
 	over?: number
 	// The target project whose transcripts to read, or absent for this process's own working
@@ -243,6 +246,28 @@ function verdict_of(measurement: OverMeasurement | undefined): CostVerdict {
 	return cost_verdict.classify(measurement, CONTEXT_CUT_THRESHOLD)
 }
 
+// The verdict with the figures it was decided on — the newest request's billed input and the shared
+// threshold — so a report that cites the verdict quotes the same numbers rather than re-measuring.
+// An unmeasurable session has no cost to quote, which is `undefined`, never `0`.
+function figures_of(measurement: OverMeasurement | undefined): SessionFigures {
+	const verdict = verdict_of(measurement)
+	const is_priced = measurement !== undefined && verdict !== UNMEASURABLE_VERDICT
+	const cost = is_priced ? cost_verdict.per_request_cost(measurement) : undefined
+
+	return { verdict, cost, threshold: CONTEXT_CUT_THRESHOLD }
+}
+
+// The `--cut` verdict and its figures as a value, printing nothing. `run:report --handoff` quotes the
+// figures in the hand-off report; `session_verdict` reads the verdict alone.
+function session_figures(
+	cwd: string = process.cwd(),
+	environment: Environment = process.env,
+): SessionFigures {
+	const provider = provider_of(environment)
+
+	return figures_of(provider === undefined ? undefined : measure(cwd, provider, environment))
+}
+
 // The `--cut` verdict as a value, printing nothing. `run:status` bundles
 // this beside the issue state and the carry record, so it needs the token rather than the exit code
 // `run` returns. `unmeasurable` is the read-only counterpart of `report_empty` / the empty-session
@@ -252,10 +277,7 @@ function session_verdict(
 	cwd: string = process.cwd(),
 	environment: Environment = process.env,
 ): CostVerdict {
-	const provider = provider_of(environment)
-	if (provider === undefined) return UNMEASURABLE_VERDICT
-
-	return verdict_of(measure(cwd, provider, environment))
+	return session_figures(cwd, environment).verdict
 }
 
 function run_context(
@@ -294,20 +316,15 @@ function run(
 	return run_over(target, context.over, context.provider, environment)
 }
 
-function main(argv: ReadonlyArray<string>): void {
-	process.exitCode = run(argv)
-}
-
 const cost_cli = {
 	UNMEASURABLE_VERDICT,
 	USAGE,
 	parse_options,
 	to_threshold,
 	run,
+	session_figures,
 	session_verdict,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
-
-export type { CostVerdict, Options }
+export type { CostVerdict, Options, SessionFigures }
 export { cost_cli }

package/scripts/cost-runtime/cost-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cost_cli } from './cost-cli'
+
+// The `josh cost` entry, kept apart from `cost-cli.ts` because `implementation-cut.ts` imports that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = cost_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/cost-runtime/cost-transcript.ts

@@ -505,6 +505,7 @@ const cost_transcript = {
 	transcript_directory,
 	transcript_directories,
 	session_cwd,
+	lane_transcript_directories,
 	unit_directory,
 	list_sessions,
 	list_sessions_across,

package/scripts/delegation/delegation-policy.ts

@@ -26,8 +26,9 @@ interface DelegatableStep {
 // Where the pre-implementation reading stops being cheaper in the main line.
 //
 // **A count, not a forecast.** The reads are counted as they are made rather than predicted before
-// the investigation starts, so nothing here rests on guessing how large it will be. Two files the run
-// will not edit stay in the main line, because delegating costs two extra main-line turns — one to
+// the investigation starts, so nothing here rests on guessing how large it will be. It is where the
+// guard refuses, not a budget: a run that knows its subject needs reading delegates before the first
+// read (`run:prep`, #4345). Two stray files the run will not edit are tolerated, because delegating costs two extra main-line turns — one to
 // write the brief, one to read the result, about 18 seconds at roughly 8.8 s of model
 // wait per turn — and below the threshold that round trip costs more than carrying the text.
 const INVESTIGATION_FILE_THRESHOLD = 3
@@ -38,6 +39,15 @@ const INVESTIGATION_FILE_THRESHOLD = 3
 // target, in the main line and sends the continuing sweep to a unit.
 const INVESTIGATION_SEARCH_TURN_THRESHOLD = 3
 
+// `.claude/agents/investigator.md`; a consumer receives it through the plugin as `kit:investigator`.
+const INVESTIGATOR_AGENT = 'investigator'
+
+// The limit and the remedy, worded once: the guard's refusal and `run:prep`'s entry notice both print
+// them, so a run told the step up front is told the same step the refusal would name.
+const INVESTIGATION_LIMIT = `${String(INVESTIGATION_FILE_THRESHOLD)} files read and not edited, or ${String(INVESTIGATION_SEARCH_TURN_THRESHOLD)} search turns, since the last delegated unit`
+// Only the dispatch resets the count, so the step names no `josh delegate` call before it (#4345).
+const INVESTIGATION_STEP = `Dispatch the \`${INVESTIGATOR_AGENT}\` agent (\`kit:${INVESTIGATOR_AGENT}\` in a consumer); it returns \`file:line\` citations, never the file text.`
+
 // The enumeration. Short on purpose: every entry had to name a verifier, and most candidates could
 // not (below).
 const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
@@ -59,12 +69,12 @@ const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
 	{
 		name: 'followup-filing',
 		// The late-run follow-up filing chain — `issue:file` (which scouts, lints, labels and runs
-		// epic:bundle itself) → epic --add — is a dependency chain `batch:guard`
+		// epic:bundle itself) → epic --add — is a dependency chain the batching guard
 		// correctly keeps one call per step, and what makes it expensive is the ~340k context it runs in
 		// at the tail of a run, not the step count. A fresh unit runs the same
 		// chain at a small context, and the review round cap already composed the finding text, so what
 		// the unit is handed is mechanical: run the commands and act on their deterministic answers. This
-		// is not `batch:guard`'s business — delegation only moves the chain to a cheaper context.
+		// is not the batching guard's business — delegation only moves the chain to a cheaper context.
 		does: 'run the late-run follow-up filing chain in an isolated unit — issue:file (scout, lint, labels, epic:bundle), then epic --add — given the finding text the parent already composed, and return the new Issue number and the epic:bundle answer',
 		verifier:
 			"the parent reads the filed Issue from GitHub with `pnpm josh issue:state <new>`, not the unit's summary; a follow-up reported filed but not created is still absent, the way `epic-child`'s reported-done-but-not-merged child is still open. The finding text came from the parent and `issue:file`'s steps are deterministic, so the unit's work is the mechanical execution `issue:state` confirms",
@@ -181,7 +191,10 @@ function reason_for(name: string): string {
 const delegation_policy = {
 	DELEGATE_VERDICT,
 	INVESTIGATION_FILE_THRESHOLD,
+	INVESTIGATION_LIMIT,
 	INVESTIGATION_SEARCH_TURN_THRESHOLD,
+	INVESTIGATION_STEP,
+	INVESTIGATOR_AGENT,
 	KEEP_VERDICT,
 	DELEGATABLE_STEPS,
 	REJECTED_STEPS,