@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/cost-runtime/context-cut-payback.ts

@@ -19,55 +19,57 @@ import { cost_pricing } from './cost-pricing'
 const POST_CUT_CONTEXT = 60_000
 
 // The requests a resumed session is expected to still run — the horizon the break-even is measured
-// against. A cut only pays if enough requests remain to recoup the preamble rewrite; even the shortest
-// resume (into the gate, commit, PR and merge) runs on the order of ten. Ten is the conservative
-// horizon: it keeps the shared threshold near the empirically validated 150_000 (this lands at
-// 135_000, inside the simulated 100k–200k band) while pricing the decision from the cost model. It is the knob a before/after lane measurement tunes.
-const EXPECTED_REMAINING_REQUESTS = 10
+// against. A cut only pays if enough requests remain to recoup the preamble rewrite. Measured, not
+// chosen: the lane children resumed after a cut over the 14 days to 2026-10-28 ran a median of 23
+// requests per resumed session (748 sessions; p25 11, p90 68 — #5341). The median, not the mean, so a
+// few long resumes do not pull every cut earlier.
+const EXPECTED_REMAINING_REQUESTS = 23
 
 // The price of a dropped token relative to a rewritten one, from `cost-pricing.ts`. A cache read bills
-// `DEFAULT_CACHE_READ_MULTIPLIER` of base input and a 5-minute cache write `CACHE_WRITE_5M_MULTIPLIER`,
-// so a preamble rewrite costs this many per-request cache reads. The base input rate is common to both
-// and cancels, which is why only the ratio appears.
-//
-// **The standard cache-read rate, deliberately, not the running model's.** Opus 5.5 reads cache at
-// 0.05x and Fable 5.1 at 0.025x, which would move the threshold from 135,000 to 210,000 and 360,000 —
-// outside the 100k–200k band the cut was validated in. That changes when a cut fires, a decision that
-// needs a lane measurement of its own rather than arriving as a side effect of a corrected price list.
-function write_over_read(): number {
-	return cost_pricing.CACHE_WRITE_5M_MULTIPLIER / cost_pricing.DEFAULT_CACHE_READ_MULTIPLIER
+// the running model's cache-read multiplier of base input and a 5-minute cache write
+// `CACHE_WRITE_5M_MULTIPLIER`, so a preamble rewrite costs this many per-request cache reads. The base
+// input rate is common to both and cancels, which is why only the ratio appears. A model that reads
+// cache cheaper (Opus 5.5 at 0.05x, Fable 5.1 at 0.025x) saves less per dropped token, so its cut
+// breaks even later; an unpriced model reads at the standard rate.
+function write_over_read(model: string | undefined): number {
+	return cost_pricing.CACHE_WRITE_5M_MULTIPLIER / cost_pricing.cache_read_multiplier_of(model)
 }
 
-// The current per-request context at which a cut breaks even over exactly `remaining` requests. The
-// shared cut threshold is this evaluated at `EXPECTED_REMAINING_REQUESTS`; rounded to an integer so the
+// The current per-request context at which a cut breaks even for `model` over exactly `remaining`
+// requests. The cut threshold `pnpm josh cost --cut` applies is this evaluated at
+// `EXPECTED_REMAINING_REQUESTS` for the session's newest request's model; rounded to an integer so the
 // `>` comparison against a per-request billed-input count has no floating-point seam.
-function break_even_context(remaining: number = EXPECTED_REMAINING_REQUESTS): number {
+function break_even_context(
+	model: string | undefined,
+	remaining: number = EXPECTED_REMAINING_REQUESTS,
+): number {
 	if (remaining <= 0) return Infinity
 
-	return Math.round(POST_CUT_CONTEXT * (1 + write_over_read() / remaining))
+	return Math.round(POST_CUT_CONTEXT * (1 + write_over_read(model) / remaining))
 }
 
 // The requests a cut must save over before it recoups its own preamble rewrite, at a given current
 // per-request context. Decreasing in context: the more a request currently pays, the fewer resumed
 // requests are needed to earn the cut back. Exposed as the diagnostic the break-even is read in —
-// `break_even_requests(current) < remaining` is the same decision as `pays_back`.
-function break_even_requests(current_context: number): number {
+// `break_even_requests(current, model) < remaining` is the same decision as `pays_back`.
+function break_even_requests(current_context: number, model: string | undefined): number {
 	const saved_per_request = current_context - POST_CUT_CONTEXT
 
 	if (saved_per_request <= 0) return Infinity
 
-	return (POST_CUT_CONTEXT * write_over_read()) / saved_per_request
+	return (POST_CUT_CONTEXT * write_over_read(model)) / saved_per_request
 }
 
 // Whether cutting now pays back: the current per-request context has grown past the break-even point
 // for the expected remaining requests. Compared against the rounded `break_even_context` with `>`, so
-// it agrees to the token with `cost_verdict.classify` reading the derived `CONTEXT_CUT_THRESHOLD` — the
-// same one decision, whether a caller holds the threshold or asks this function.
+// it agrees to the token with `cost_verdict.classify` reading the same threshold — the same one
+// decision, whether a caller holds the threshold or asks this function.
 function pays_back(
 	current_context: number,
+	model: string | undefined,
 	remaining: number = EXPECTED_REMAINING_REQUESTS,
 ): boolean {
-	return current_context > break_even_context(remaining)
+	return current_context > break_even_context(model, remaining)
 }
 
 const context_cut_payback = {

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,9 +1,7 @@
-#!/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'
-import { CONTEXT_CUT_THRESHOLD } from './context-cut-threshold'
+import { context_cut_payback } from './context-cut-payback'
 import { cost_corpus } from './cost-corpus'
 import { cost_transcript, type SessionUsage } from './cost-transcript'
 import { cost_usage } from './cost-usage'
@@ -18,9 +16,8 @@ import { transcript_cwd } from './transcript-cwd'
 // (`--session` / `--issue` / `--all` / `--run` / `--json`) and the `--cap` counterfactual were
 // retired because no rule or decision read them — leaving only the entry judgment `fullrun` /
 // `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.
+// hand-off aggregates used to compare the `--cut` break-even.
 
-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,8 +26,20 @@ const UNMEASURABLE_VERDICT = 'unmeasurable'
 
 type CostVerdict = ReturnType<typeof cost_verdict.classify> | typeof UNMEASURABLE_VERDICT
 
+interface SessionFigures {
+	verdict: CostVerdict
+	cost: number | undefined
+	threshold: number
+}
+
+// `--cut` is not a number at parse time: its threshold is the break-even of the model the session's
+// newest request ran on, known only once the transcript is read.
+const CUT_LIMIT = 'cut'
+
+type Limit = number | typeof CUT_LIMIT
+
 interface Options {
-	over?: number
+	over?: Limit
 	// The target project whose transcripts to read, or absent for this process's own working
 	// directory. From the kit checkout, `--path <dir>` reads another
 	// project's cost.
@@ -46,7 +55,7 @@ interface RawValues {
 type Environment = Readonly<Record<string, string | undefined>>
 
 interface RunContext {
-	over: number
+	over: Limit
 	path: string | undefined
 	provider: AgentProvider
 }
@@ -69,10 +78,14 @@ function is_unparsed(raw: string | undefined, parsed: number | undefined): boole
 	return parsed === undefined && raw !== undefined
 }
 
-function selected_threshold(values: RawValues): number | undefined {
-	if (values.cut === true) return CONTEXT_CUT_THRESHOLD
+// The cut threshold of a measured session: the break-even for its newest request's model. With no
+// measurement it is the standard-rate break-even, the figure a report quotes beside no cost.
+function cut_threshold(measurement: OverMeasurement | undefined): number {
+	return context_cut_payback.break_even_context(measurement?.model)
+}
 
-	return to_threshold(values.over)
+function limit_of(limit: Limit, measurement: OverMeasurement): number {
+	return limit === CUT_LIMIT ? cut_threshold(measurement) : limit
 }
 
 function threshold_option(over: number | undefined): Pick<Options, 'over'> {
@@ -83,12 +96,17 @@ function path_option(path: string | undefined): Pick<Options, 'path'> {
 	return path === undefined ? {} : { path }
 }
 
+// `--cut` and `--over` name the same limit, so giving both is a refusal.
+function cut_options(values: RawValues): Options | undefined {
+	return values.over === undefined ? { over: CUT_LIMIT, ...path_option(values.path) } : undefined
+}
+
 // `exactOptionalPropertyTypes` rejects `{ over: undefined }`, so an absent flag contributes no key
 // at all rather than an undefined one.
 function to_options(values: RawValues): Options | undefined {
-	if (values.cut === true && values.over !== undefined) return undefined
+	if (values.cut === true) return cut_options(values)
 
-	const over = selected_threshold(values)
+	const over = to_threshold(values.over)
 
 	if (is_unparsed(values.over, over)) return undefined
 
@@ -144,6 +162,7 @@ function measurement_of(session: SessionUsage): OverMeasurement {
 		billed_input_per_request: session.records.map((record) =>
 			cost_usage.billed_input(record.totals),
 		),
+		model: session.records.at(-1)?.model,
 	}
 }
 
@@ -203,15 +222,20 @@ function measure(
 // missing message; `empty` → the whole-corpus missing message. A measured session that billed
 // nothing falls to `report_over`'s "no requests", which keeps a 0-request transcript distinct from a
 // transcript that is not there at all.
-function run_over_anthropic(own: OwnMeasurement, target: string, limit: number): number {
-	if (own.kind === 'measured') return cost_verdict.report_over(own.measurement, limit)
+function run_over_anthropic(own: OwnMeasurement, target: string, limit: Limit): number {
+	if (own.kind === 'measured') {
+		return cost_verdict.report_over(own.measurement, limit_of(limit, own.measurement))
+	}
 
 	return report_empty(target, own.kind === 'absent' ? own.session_id : undefined)
 }
 
-function run_over_codex(target: string, limit: number, environment: Environment): number {
+function run_over_codex(target: string, limit: Limit, environment: Environment): number {
 	const measurement = measure(target, 'openai', environment)
-	if (measurement !== undefined) return cost_verdict.report_over(measurement, limit)
+
+	if (measurement !== undefined) {
+		return cost_verdict.report_over(measurement, limit_of(limit, measurement))
+	}
 
 	console.error(`No Codex usage found for the current OpenAI thread under ${target}.`)
 
@@ -222,7 +246,7 @@ function run_over_codex(target: string, limit: number, environment: Environment)
 // alone — identified by id, not by mtime.
 function run_over(
 	target: string,
-	limit: number,
+	limit: Limit,
 	provider: AgentProvider,
 	environment: Environment,
 ): number {
@@ -240,7 +264,29 @@ function verdict_of(measurement: OverMeasurement | undefined): CostVerdict {
 		return UNMEASURABLE_VERDICT
 	}
 
-	return cost_verdict.classify(measurement, CONTEXT_CUT_THRESHOLD)
+	return cost_verdict.classify(measurement, cut_threshold(measurement))
+}
+
+// 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: cut_threshold(measurement) }
+}
+
+// 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
@@ -252,10 +298,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 +337,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-pricing.ts

@@ -111,6 +111,14 @@ function cache_read_multiplier(price: ModelPrice): number {
 	return price.cache_read_multiplier ?? DEFAULT_CACHE_READ_MULTIPLIER
 }
 
+// The cache-read multiplier a model bills, by id. A model with no price row — an unpriced id, or no
+// model at all — reads at the standard rate.
+function cache_read_multiplier_of(model: string | undefined): number {
+	const price = model === undefined ? undefined : resolve_price(model)
+
+	return price === undefined ? DEFAULT_CACHE_READ_MULTIPLIER : cache_read_multiplier(price)
+}
+
 function estimate_cost(totals: UsageTotals, price: ModelPrice): number {
 	const weighted_input =
 		totals.input_tokens +
@@ -225,6 +233,7 @@ const cost_pricing = {
 	DEFAULT_CACHE_READ_MULTIPLIER,
 	LONG_PROMPT_THRESHOLD,
 	resolve_price,
+	cache_read_multiplier_of,
 	estimate_cost,
 	estimate_composition,
 	cost_by_model,

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/cost-runtime/cost-verdict.ts

@@ -9,9 +9,12 @@ const UNDER_VERDICT = 'under'
 
 // What `--over` reads of a session: the billed input each request paid, oldest first. The sequence
 // is carried rather than a single sum because the hand-off prices the newest request alone
-// — a sum could not answer what the session's current context costs.
+// — a sum could not answer what the session's current context costs. `model` is the newest request's
+// model, which prices the cut threshold (`context-cut-payback.ts`); a provider that records none
+// leaves it absent and is read at the standard cache rate.
 interface OverMeasurement {
 	billed_input_per_request: ReadonlyArray<number>
+	model?: string | undefined
 }
 
 // What a turn costs is decided by the accumulated preamble, not by what the turn does, so the

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) with \`run_in_background: false\`; 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,13 +69,13 @@ 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.
-		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',
+		// 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 (lint, labels, scout, 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,

package/scripts/delegation/duplicate-read-guard.ts

@@ -1,7 +1,4 @@
-#!/usr/bin/env tsx
 import { statSync } from 'node:fs'
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
 import { json_value } from '#scripts/lib/json-value'
@@ -213,15 +210,11 @@ const notice_refusal_path = hook_decision.create_refusal_stamp(NOTICE_STAMP_PREF
 const { deny_envelope, DISABLED_VALUES } = hook_decision
 
 const duplicate_reads = {
+	is_successful_read,
 	REASON,
 	NOTICE,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('duplicate-read:guard')
-	else hook_decision.write_outcome(await text(process.stdin), duplicate_read_outcome)
-}
-
 export {
 	deny_envelope,
 	DISABLED_VALUES,

package/scripts/delegation/investigation-guard.ts

@@ -1,6 +1,3 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
 import { lane_guard_policy } from '#scripts/lane/lane-guard-policy'
@@ -27,8 +24,9 @@ const STAMP_PREFIX = 'josh-investigation-guard-'
 // **How the guard behaves for the session in hand, decided from the one-place enumeration**. It is
 // `refuse` in a dispatched lane child too (joshuafolkken/kit#3927): a hook denial returns to the model
 // as guidance, and the notice it replaced was measured not to move the reading. It wraps
-// `investigation_reads.should_block` here rather than inside it so the pure counting rule stays free of
-// process state and its own suite keeps testing it directly. A reviewer session stands down: reading
+// `investigation_reads.should_block` here rather than inside it so the counting rule stays free of the
+// session's switch state and its own suite keeps testing it directly — its only process read is the
+// branch diff it asks before a refusal. A reviewer session stands down: reading
 // the diff's files is its whole task, and it carries the lane's marker, so it would otherwise be refused
 // like the child it reviews — the stand-down `implementation-cut.ts` takes for the same session.
 function should_block(
@@ -59,10 +57,15 @@ const investigation_refusal = GUARD.refusal
 const investigation_outcome = GUARD.outcome
 const { is_enabled, refusal_path } = GUARD
 const { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision
+const STAMP = hook_decision.create_refusal_stamp(STAMP_PREFIX)
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('investigation:guard')
-	else hook_decision.write_outcome(await text(process.stdin), investigation_outcome)
+// Whether this guard refuses the call in hand, asked with its real record — so the batching guard's
+// lane-child search refusal can stand aside for it: only one reason surfaces per call, and delegating
+// the reading supersedes batching it.
+function will_refuse(tail: string, call: GuardedCall, run: GuardRun): boolean {
+	if (!is_enabled() || !investigation_reads.is_refusable_call(call)) return false
+
+	return should_block(tail, call, STAMP.last_ms(STAMP.path(run.transcript)), run)
 }
 
 export {
@@ -72,6 +75,7 @@ export {
 	is_enabled,
 	load_environment_file,
 	refusal_path,
+	will_refuse,
 	DISABLED_VALUES,
 	SWITCH_ENV_KEY,
 }