@joshuafolkken/kit 1.872.0

package/scripts/cost-runtime/codex-usage.ts

@@ -0,0 +1,119 @@
+import { globSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { z } from 'zod'
+import { cost_transcript } from './cost-transcript'
+import type { OverMeasurement } from './cost-verdict'
+
+const THREAD_ID_PATTERN = /^[A-Za-z0-9-]+$/u
+const SESSION_META_SCHEMA = z.looseObject({
+	type: z.literal('session_meta'),
+	payload: z.looseObject({ id: z.string(), cwd: z.string() }),
+})
+const TOTAL_USAGE_SCHEMA = z.looseObject({ input_tokens: z.number().nonnegative() })
+const TOKEN_COUNT_SCHEMA = z.looseObject({
+	type: z.literal('event_msg'),
+	payload: z.looseObject({
+		type: z.literal('token_count'),
+		info: z.looseObject({
+			total_token_usage: TOTAL_USAGE_SCHEMA,
+			last_token_usage: TOTAL_USAGE_SCHEMA,
+		}),
+	}),
+})
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+function decode(line: string): unknown {
+	try {
+		return JSON.parse(line)
+	} catch {
+		return undefined
+	}
+}
+
+function same_project(cwd: string, target: string): boolean {
+	return cost_transcript.session_cwd(cwd) === cost_transcript.session_cwd(target)
+}
+
+// The billed input each request paid, oldest first (joshuafolkken/kit#2295). Each `token_count`
+// event carries `last_token_usage` — that request's own input — so the per-request sequence the
+// hand-off's recent window reads is those deltas, not a cumulative-total difference. A session
+// resumed with inherited context is excluded for free: the inherited tokens are in the cumulative
+// total, never in a request's own `last_token_usage`.
+function billed_per_request(
+	usages: ReadonlyArray<z.infer<typeof TOKEN_COUNT_SCHEMA>['payload']['info']>,
+): ReadonlyArray<number> {
+	return usages.map((usage) => usage.last_token_usage.input_tokens)
+}
+
+function measurement_from(
+	content: string,
+	target: string,
+	thread_id: string,
+): OverMeasurement | undefined {
+	const values = content.split('\n').map((line) => decode(line))
+	const metadata = values.flatMap((value) => {
+		const parsed = SESSION_META_SCHEMA.safeParse(value)
+
+		return parsed.success ? [parsed.data] : []
+	})
+	const usages = values.flatMap((value) => {
+		const parsed = TOKEN_COUNT_SCHEMA.safeParse(value)
+
+		return parsed.success ? [parsed.data.payload.info] : []
+	})
+	const session = metadata.find((entry) => entry.payload.id === thread_id)
+	if (session === undefined || usages.length === 0) return undefined
+	if (!same_project(session.payload.cwd, target)) return undefined
+
+	return { billed_input_per_request: billed_per_request(usages) }
+}
+
+function rollout_files(home: string, thread_id: string): Array<string> {
+	if (!THREAD_ID_PATTERN.test(thread_id)) return []
+
+	return globSync(`sessions/**/*${thread_id}.jsonl`, { cwd: home }).map((file) =>
+		path.join(home, file),
+	)
+}
+
+function read_measurement(
+	file: string,
+	target: string,
+	thread_id: string,
+): OverMeasurement | undefined {
+	try {
+		return measurement_from(readFileSync(file, 'utf8'), target, thread_id)
+	} catch {
+		return undefined
+	}
+}
+
+function latest_measurement(
+	files: ReadonlyArray<string>,
+	target: string,
+	thread_id: string,
+): OverMeasurement | undefined {
+	for (const file of files.toReversed()) {
+		const measured = read_measurement(file, target, thread_id)
+		if (measured !== undefined) return measured
+	}
+
+	return undefined
+}
+
+function measurement(
+	target: string,
+	default_home: string,
+	environment: Environment = process.env,
+): OverMeasurement | undefined {
+	const thread_id = environment['CODEX_THREAD_ID']
+	if (thread_id === undefined) return undefined
+	const home = environment['CODEX_HOME'] ?? path.join(default_home, '.codex')
+
+	return latest_measurement(rollout_files(home, thread_id), target, thread_id)
+}
+
+const codex_usage = { measurement }
+
+export { codex_usage }

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

@@ -0,0 +1,77 @@
+import { cost_pricing } from './cost-pricing'
+
+// **When a context cut pays back, priced from the cost model rather than fixed at a ceiling**
+// (joshuafolkken/kit#2406). A cut ends the oversized session and relaunches a fresh one that rebuilds
+// only its preamble, so what it saves is not decided by a ceiling on the accumulated context but by a
+// *rate*: a cache read bills the whole context on every request, so whether to cut turns on how many
+// requests are still to come and what each would pay, not on how much has piled up.
+//
+// The arithmetic is a break-even. A cut costs one preamble rewrite — `POST_CUT_CONTEXT` tokens written
+// to cache once — and saves, on every later request, the cache read of the context it dropped
+// (`current − POST_CUT_CONTEXT` tokens). The base input rate cancels: both the cost and the saving are
+// billed at the same model's input rate, so only the two cache multipliers survive, and they are read
+// from `cost-pricing.ts` rather than restated here — no second price list.
+
+// The context a resumed request pays: the preamble plus the carried hand-off a fresh process rebuilds.
+// Measured at ~60,000 — `.claude/skills/workflow-commands/pre-gate-cut.md` records the cut carrying a
+// request from ~130k down to ~60k. It is both the cut's one-time cost (written once) and the floor the
+// per-request saving is measured above.
+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 joshuafolkken/kit#2374's empirically validated 150_000
+// (this lands at 135_000, inside the 100k–200k band that PR simulated) while pricing the decision from
+// the cost model. It is the knob a before/after lane measurement tunes.
+const EXPECTED_REMAINING_REQUESTS = 10
+
+// The price of a dropped token relative to a rewritten one, from `cost-pricing.ts`. A cache read bills
+// `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.
+function write_over_read(): number {
+	return cost_pricing.CACHE_WRITE_5M_MULTIPLIER / cost_pricing.CACHE_READ_MULTIPLIER
+}
+
+// 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
+// `>` comparison against a per-request billed-input count has no floating-point seam.
+function break_even_context(remaining: number = EXPECTED_REMAINING_REQUESTS): number {
+	if (remaining <= 0) return Infinity
+
+	return Math.round(POST_CUT_CONTEXT * (1 + write_over_read() / 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 {
+	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
+}
+
+// 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.
+function pays_back(
+	current_context: number,
+	remaining: number = EXPECTED_REMAINING_REQUESTS,
+): boolean {
+	return current_context > break_even_context(remaining)
+}
+
+const context_cut_payback = {
+	POST_CUT_CONTEXT,
+	EXPECTED_REMAINING_REQUESTS,
+	break_even_context,
+	break_even_requests,
+	pays_back,
+}
+
+export { context_cut_payback }

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

@@ -0,0 +1,21 @@
+import { context_cut_payback } from './context-cut-payback'
+
+// The scheduler entry/hand-off and lane worker implementation cut use one threshold. Keeping the
+// value here prevents either side from drifting when the context budget changes.
+// joshuafolkken/kit#2374 lowered it from 200_000 by simulation; joshuafolkken/kit#2406 replaced the
+// hand-picked ceiling with a break-even: the threshold is no longer a chosen number but the current
+// per-request context at which a cut pays back over the expected remaining requests
+// (`context-cut-payback.ts`). At `POST_CUT_CONTEXT` 60_000 and a 10-request horizon that is 135_000 —
+// 10% under #2374's empirical 150_000 and inside the 100k–200k band that PR simulated — now derived
+// from the cache-price multipliers and the horizon rather than restated, so it moves with the model.
+const CONTEXT_CUT_THRESHOLD = context_cut_payback.break_even_context()
+
+// The hand-off prices the average billed input of the most recent requests, not the whole session
+// (joshuafolkken/kit#2295). A long parent session's whole-session average lags its current context by
+// dozens of requests — measured at 85 requests (~4 hours) behind on the 2026-09-21 parent — so it
+// keeps supervising an already-oversized context long after a cut was due. Ten requests is enough to
+// smooth a single outlier without reaching back into the cheap early context; it sits beside the
+// threshold so the window and the limit are read from one place and cannot drift.
+const RECENT_REQUEST_WINDOW = 10
+
+export { CONTEXT_CUT_THRESHOLD, RECENT_REQUEST_WINDOW }

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

@@ -0,0 +1,168 @@
+import type { UsageRecord } from './cost-usage'
+
+// Which Issue a request belongs to (joshuafolkken/kit#962).
+//
+// **The walk is keyed on the branch and nothing else**, which is why its input is `BranchBearing`
+// rather than `UsageRecord` (joshuafolkken/kit#1268). `josh time` attributes *spans* to an issue by
+// exactly this rule, and the alternative to widening the parameter was a second copy of the
+// fill-forward walk over a different element type — the clone `CLAUDE.md` prohibits, in the one
+// place where a drift between the two would make `josh cost --issue` and `josh time --issue`
+// disagree about which issue a run belonged to.
+//
+// The transcript records `gitBranch` on every line, and `josh git` names a branch `<N>-<slug>`, so
+// the branch is where the Issue number is. What makes the mapping less than direct is that a child
+// is implemented on the **default branch** — `josh git` only creates the branch at commit time — so
+// most of a child's requests were made while `gitBranch` still said `main`.
+//
+// Hence the fill: a request on a non-issue branch is attributed to the nearest issue branch that
+// appears **later** in the session, because the work precedes the branch it will be committed to.
+// Only when nothing follows does it fall back to the nearest earlier one, which is what catches the
+// tail after a merge — `josh ms` returns to the default branch while the run is still reporting.
+
+const ISSUE_BRANCH_PATTERN = /^(\d+)-/u
+
+// The value that means "no issue". Issue numbers are positive, so a negative sentinel cannot be
+// mistaken for one, and one value used throughout removes the `undefined` juggling that each fill
+// direction would otherwise repeat.
+const UNATTRIBUTED_KEY = -1
+
+// Everything the attribution reads. `UsageRecord` satisfies it, and so does a timed span.
+//
+// **`issue` is the branch's answer where the branch cannot give one** (joshuafolkken/kit#1617). The
+// paragraph above assumes the session and the work share a checkout, and under lanes they do not: a
+// child's commands run in a linked work tree on `<N>-lane` while the session writing the transcript
+// sits on the default branch, so every line of a lane run reads `gitBranch: "main"` and no fill
+// direction has an issue branch to carry. Measured on 2026-09-09: issues 1445, 1510 and 1511 each
+// merged from a lane and left not one `<N>-` branch anywhere in the corpus.
+//
+// **It is a declaration, not a second walk.** The record says which issue it names and the existing
+// fill-forward carries it exactly as it carries a branch — the alternative was a lane-aware copy of
+// `attribute`, which is the clone `CLAUDE.md` prohibits in the one place a drift would make
+// `josh cost --issue` and `josh time --issue` disagree. `UsageRecord` declares nothing and is
+// unaffected.
+interface BranchBearing {
+	branch: string
+	issue?: number
+}
+
+function issue_from_branch(branch: string): number {
+	const matched = ISSUE_BRANCH_PATTERN.exec(branch)
+
+	return matched?.[1] === undefined ? UNATTRIBUTED_KEY : Number(matched[1])
+}
+
+// What a record says it belongs to. A declaration wins over the branch because it is the stronger
+// evidence: the branch is the checkout's and may be shared by every run of the day, while a
+// declaration was written by the run itself about itself.
+function declared_issue(record: BranchBearing): number {
+	const declared = record.issue ?? UNATTRIBUTED_KEY
+
+	return declared === UNATTRIBUTED_KEY ? issue_from_branch(record.branch) : declared
+}
+
+// The nearest declared issue in one direction, carried across the gaps. Both directions are the
+// same walk, so they are one function rather than two that would drift.
+function fill(declared: ReadonlyArray<number>, is_reverse: boolean): Array<number> {
+	const filled: Array<number> = Array.from({ length: declared.length }, () => UNATTRIBUTED_KEY)
+	const order = declared.map((_value, index) => (is_reverse ? declared.length - 1 - index : index))
+	let carried = UNATTRIBUTED_KEY
+
+	for (const index of order) {
+		const own = declared[index] ?? UNATTRIBUTED_KEY
+
+		carried = own === UNATTRIBUTED_KEY ? carried : own
+		filled[index] = carried
+	}
+
+	return filled
+}
+
+function is_attributed(value: number | undefined): value is number {
+	return value !== undefined && value !== UNATTRIBUTED_KEY
+}
+
+// **A declaration is carried forward, and it outranks both branch directions.** The preference for
+// `next` below is a statement about *branches*: work precedes the branch it will be committed to, so
+// the branch sits at the end of the run it names. A declaration sits at the *start* — the
+// `in-progress` label is the first thing a run writes — so carrying it backwards would give one
+// child's work to the next child declared after it, which is exactly the shape a lane transcript
+// holding two children has. `carried` is therefore the forward fill of declarations alone, and a
+// corpus with no declaration leaves every value `UNATTRIBUTED_KEY` and this branch inert.
+function pick(
+	own: number,
+	carried: number,
+	next: number | undefined,
+	previous: number | undefined,
+): number {
+	if (is_attributed(own)) return own
+	if (is_attributed(carried)) return carried
+	if (is_attributed(next)) return next
+
+	return previous ?? UNATTRIBUTED_KEY
+}
+
+function announcements(records: ReadonlyArray<BranchBearing>): Array<number> {
+	return fill(
+		records.map((record) => record.issue ?? UNATTRIBUTED_KEY),
+		false,
+	)
+}
+
+function attribute(records: ReadonlyArray<BranchBearing>): Array<number> {
+	const declared = records.map((record) => declared_issue(record))
+	const carried = announcements(records)
+	const next = fill(declared, true)
+	const previous = fill(declared, false)
+
+	return declared.map((own, index) =>
+		pick(own, carried[index] ?? UNATTRIBUTED_KEY, next[index], previous[index]),
+	)
+}
+
+interface IssueGroup {
+	// `UNATTRIBUTED_KEY` for requests made in a session that never touched an issue branch — a plain
+	// conversational session. Reported as its own bucket rather than dropped.
+	issue: number
+	records: Array<UsageRecord>
+}
+
+function group_by_issue(records: ReadonlyArray<UsageRecord>): Array<IssueGroup> {
+	const issues = attribute(records)
+	const grouped = new Map<number, Array<UsageRecord>>()
+
+	for (const [index, record] of records.entries()) {
+		const bucket = grouped.get(issues[index] ?? UNATTRIBUTED_KEY) ?? []
+
+		bucket.push(record)
+		grouped.set(issues[index] ?? UNATTRIBUTED_KEY, bucket)
+	}
+
+	return [...grouped]
+		.toSorted(([left], [right]) => left - right)
+		.map(([issue, bucket]) => ({ issue, records: bucket }))
+}
+
+// One issue's slice of a session's items, whatever the items are. Generic for the same reason
+// `attribute` is: `josh time` filters spans through it, and a second copy narrowed to spans would
+// be the fill-forward rule written twice.
+function records_for_issue<Item extends BranchBearing>(
+	records: ReadonlyArray<Item>,
+	issue_number: number,
+): Array<Item> {
+	const issues = attribute(records)
+
+	return records.filter((_record, index) => issues[index] === issue_number)
+}
+
+const cost_attribute = {
+	UNATTRIBUTED_KEY,
+	issue_from_branch,
+	declared_issue,
+	fill,
+	attribute,
+	group_by_issue,
+	records_for_issue,
+}
+
+export type { BranchBearing, IssueGroup }
+export { cost_attribute }

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

@@ -0,0 +1,149 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// Reading the content blocks out of a session transcript (joshuafolkken/kit#1151).
+//
+// `cost-usage.ts` reads the same file for what each request was billed and skips everything else.
+// This module reads the other half: what the conversation is actually made of. They stay apart
+// because they aggregate differently — usage is deduplicated per `requestId`, since one response is
+// written as several lines all carrying the same `usage`, while the content blocks on those lines
+// are each written exactly once and must not be deduplicated.
+//
+// **Thinking arrives here empty, and that is not a defect.** Claude Code writes a `thinking` block
+// with its `signature` but with `thinking` set to `''` — 118 blocks, 0 bytes, in the transcript this
+// was measured on, and the same in every other session checked. The thinking count therefore comes
+// from `usage.output_tokens_details.thinking_tokens`, which is a real API-reported number rather
+// than an estimate.
+
+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 BASH_TOOL = 'Bash'
+const COMMAND_KEY = 'command'
+
+// One block, reduced to what a token estimate needs. `command` is split out from the rest of a Bash
+// tool_use's input because the command body is the quantity joshuafolkken/kit#1150 measured at 30.2%
+// of one run's context and joshuafolkken/kit#1159 has to re-measure — folded into the rest of the
+// input it would not be readable at all.
+interface ContentBlock {
+	type: string
+	tool_name: string
+	command: string
+	text: string
+}
+
+function json_of(value: unknown): string {
+	return value === undefined || value === null ? '' : JSON.stringify(value)
+}
+
+// The Bash command body, and the input with that key removed. Only Bash is split: another tool's
+// `command` key, if one ever existed, is not the quantity being tracked and folding it in would
+// report a number nobody measured.
+function split_bash_input(input: unknown): { command: string; rest: string } {
+	if (!json_value.is_record(input)) return { command: '', rest: json_of(input) }
+
+	const command = input[COMMAND_KEY]
+	const rest = Object.entries(input).filter(([key]) => key !== COMMAND_KEY)
+
+	return {
+		command: typeof command === 'string' ? command : '',
+		rest: json_of(Object.fromEntries(rest)),
+	}
+}
+
+function to_tool_use(block: RawBlock): ContentBlock {
+	const tool_name = block.name ?? ''
+	const is_bash = tool_name === BASH_TOOL
+	const { command, rest } = is_bash
+		? split_bash_input(block.input)
+		: { command: '', rest: json_of(block.input) }
+
+	return { type: TOOL_USE_TYPE, tool_name, command, text: rest }
+}
+
+// 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('')
+}
+
+// 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 {
+	const base = { type: block.type ?? '', tool_name: '', command: '' }
+	const text =
+		block.type === TOOL_RESULT_TYPE ? result_text(block.content ?? '') : (block.text ?? '')
+
+	return { ...base, text }
+}
+
+function to_block(block: RawBlock): 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> {
+	if (typeof content === 'string') {
+		return [{ type: TEXT_TYPE, tool_name: '', command: '', text: content }]
+	}
+
+	return content.map((block) => to_block(block))
+}
+
+// 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
+// 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 parse_line(line: string): Array<ContentBlock> {
+	const content = content_of(line)
+
+	return content === undefined ? [] : to_blocks(content)
+}
+
+function parse_content(text: string): Array<ContentBlock> {
+	return text.split('\n').flatMap((line) => parse_line(line))
+}
+
+const cost_blocks = {
+	BASH_TOOL,
+	TEXT_TYPE,
+	TOOL_USE_TYPE,
+	TOOL_RESULT_TYPE,
+	parse_line,
+	parse_content,
+}
+
+export type { ContentBlock }
+export { cost_blocks }