@joshuafolkken/kit 1.1094.0 → 1.1128.0

package/scripts/backlog/backlog-arrival.ts

@@ -18,10 +18,11 @@ import { backlog_stalled } from './backlog-stalled'
 //
 // **"New" is measured against the watcher's own start**, so one issue wakes the parent once: the next
 // `--wait` the parent starts takes the pool as it stands then — the woken issue included, dispatched or
-// not — as its baseline. A reading that fails is not an arrival; the probe says nothing and the
-// interval still wakes the parent. A baseline that cannot be read leaves that one wait inert rather than
-// reading it as empty — an empty one would wake the parent for the whole pool — and the next `--wait`
-// reads it again.
+// not — as its baseline. A reading that fails is not an arrival; the probe says nothing and reads again
+// a minute later. A baseline that cannot be read is never read as empty — an empty one would wake the
+// parent for the whole pool — but it is not given up on either: the scheduled report no longer ends the
+// wait (joshuafolkken/kit#3102), so an inert probe would leave the parent without a wake until `--hours`. The
+// probe reads the baseline again each minute until one answers.
 //
 // **Every read is bounded.** The probe is awaited inside the watcher's tick loop, so a `gh` call that
 // hangs would otherwise freeze the loop — its `--hours` bound, its liveness ping and the exit that is
@@ -116,19 +117,40 @@ async function never_arrives(): Promise<boolean> {
 
 const INERT: ArrivalProbe = { has_arrived: never_arrives }
 
-// Only the next-probe instant changes between probes, and it is set before the read is awaited.
+// A probe spent on the baseline reports no arrival, whether or not the baseline answered.
+async function retry_baseline(
+	answered: Array<ReadonlySet<string>>,
+	ports: ReadyPorts,
+): Promise<boolean> {
+	const late = await read_baseline(ports)
+
+	if (late !== undefined) answered.push(late)
+
+	return false
+}
+
+// The next-probe instant is set before any read is awaited. A baseline that did not answer is read again
+// at the next probe instead of the reading, and the first one that answers is the baseline from then on
+// — never an arrival itself, since it is the pool as it stands.
 function probe_of(
-	baseline: ReadonlySet<string>,
+	initial: ReadonlySet<string> | undefined,
 	first_ms: number,
 	ports: ReadyPorts,
 ): ArrivalProbe {
 	let next_ms = first_ms
+	// At most one entry, held in a list so the baseline that answers after an await is added rather than
+	// reassigned over the value read before it.
+	const answered: Array<ReadonlySet<string>> = initial === undefined ? [] : [initial]
 
 	async function has_arrived(now_ms: number): Promise<boolean> {
 		if (now_ms < next_ms) return false
 
 		next_ms = now_ms + PROBE_INTERVAL_MS
 
+		const [baseline] = answered
+
+		if (baseline === undefined) return await retry_baseline(answered, ports)
+
 		const reading = await read_reading(ports)
 
 		return reading !== undefined && arrivals(baseline, reading).length > NONE
@@ -146,12 +168,10 @@ async function start(
 ): Promise<ArrivalProbe> {
 	if (!(await is_parent_safely(is_parent))) return INERT
 
-	const baseline = await read_baseline(ports)
-
-	return baseline === undefined ? INERT : probe_of(baseline, now_ms + PROBE_INTERVAL_MS, ports)
+	return probe_of(await read_baseline(ports), now_ms + PROBE_INTERVAL_MS, ports)
 }
 
-const backlog_arrival = { INERT, PROBE_INTERVAL_MS, answered_issues, arrivals, start }
+const backlog_arrival = { PROBE_INTERVAL_MS, answered_issues, arrivals, start }
 
 export type { ArrivalProbe }
 export { backlog_arrival }

package/scripts/backlog/backlog-budget-cli.ts

@@ -32,11 +32,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean>>
 // A misspelled flag is refused rather than defaulted, the contract `path_decision.has_unknown_flag`
 // states for the path-decided commands: an invocation nobody can read is never answered.
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-function text_of(value: string | boolean | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 // `find` rather than a cast: an unrecognized word has to be refused, and a type assertion would
@@ -79,15 +75,15 @@ type Counts = Record<(typeof COUNT_NAMES)[number], number | undefined>
 
 function counts_of(values: ParsedValues): Counts {
 	return {
-		idle: to_count(text_of(values.idle)),
-		max: to_count(text_of(values.max)),
-		merged: to_count(text_of(values.merged)),
-		running: to_count(text_of(values.running)),
+		idle: to_count(cli_flags.string_of(values.idle)),
+		max: to_count(cli_flags.string_of(values.max)),
+		merged: to_count(cli_flags.string_of(values.merged)),
+		running: to_count(cli_flags.string_of(values.running)),
 	}
 }
 
 function are_counts_readable(values: ParsedValues, counts: Counts): boolean {
-	return COUNT_NAMES.every((name) => is_readable(text_of(values[name]), counts[name]))
+	return COUNT_NAMES.every((name) => is_readable(cli_flags.string_of(values[name]), counts[name]))
 }
 
 // **`--idle 0` is how the watch is turned off, and omitting the flag takes the default**
@@ -116,14 +112,17 @@ function to_idle_ms(idle_minutes: number | undefined): number | undefined {
 // lands on the very first ask, before the run has started anything, and the fix is one flag the loop
 // already holds: it always knows when it last had work.
 function is_watch_readable(values: ParsedValues): boolean {
-	if (to_idle_ms(to_count(text_of(values.idle))) === undefined) return true
+	if (to_idle_ms(to_count(cli_flags.string_of(values.idle))) === undefined) return true
 
-	return text_of(values.active) !== undefined
+	return cli_flags.string_of(values.active) !== undefined
 }
 
 function are_values_readable(values: ParsedValues): boolean {
 	return (
-		is_readable(text_of(values.active), to_time_ms(text_of(values.active))) &&
+		is_readable(
+			cli_flags.string_of(values.active),
+			to_time_ms(cli_flags.string_of(values.active)),
+		) &&
 		is_watch_readable(values) &&
 		are_counts_readable(values, counts_of(values))
 	)
@@ -138,7 +137,7 @@ function input_of(values: ParsedValues, base: InputBase): BudgetInput {
 
 	return {
 		...base,
-		active_at_ms: to_time_ms(text_of(values.active)) ?? base.started_at_ms,
+		active_at_ms: to_time_ms(cli_flags.string_of(values.active)) ?? base.started_at_ms,
 		merged: counts.merged ?? 0,
 		running: counts.running ?? 0,
 		max_issues: counts.max,
@@ -147,11 +146,11 @@ function input_of(values: ParsedValues, base: InputBase): BudgetInput {
 }
 
 function build_input(values: ParsedValues, now_ms: number): BudgetInput | undefined {
-	const answer = to_answer(text_of(values.answer))
+	const answer = to_answer(cli_flags.string_of(values.answer))
 
 	if (answer === undefined) return undefined
 
-	const started_at_ms = to_time_ms(text_of(values.started))
+	const started_at_ms = to_time_ms(cli_flags.string_of(values.started))
 
 	if (started_at_ms === undefined) return undefined
 	if (!are_values_readable(values)) return undefined

package/scripts/backlog/backlog-offer-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { josh_command } from '#scripts/josh/josh-run'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { rule_value_cache } from '#scripts/rules/rule-value-cache'
 import { run_event_stream } from '#scripts/run/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
@@ -61,15 +61,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean | ReadonlyArray<
 const FORWARDED = ['started', 'active', 'merged', 'running', 'max', 'idle'] as const
 
 function read_values(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
-}
-
-function text_of(value: string | boolean | ReadonlyArray<string> | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 function to_count(raw: string | undefined): number | undefined {
@@ -94,8 +86,8 @@ interface OfferCounts {
 // The two counts the mapping needs: `--running` decides `wait`, `--retries` decides `retry`. Either
 // given but unreadable refuses the whole invocation.
 function counts_of(values: ParsedValues): OfferCounts | undefined {
-	const running = count_of(text_of(values.running), DEFAULT_COUNT)
-	const retries = count_of(text_of(values.retries), DEFAULT_COUNT)
+	const running = count_of(cli_flags.string_of(values.running), DEFAULT_COUNT)
+	const retries = count_of(cli_flags.string_of(values.retries), DEFAULT_COUNT)
 
 	if (running === undefined || retries === undefined) return undefined
 
@@ -109,7 +101,7 @@ function excludes_of(values: ParsedValues): ReadonlyArray<string> {
 }
 
 function next_argv(values: ParsedValues): ReadonlyArray<string> {
-	const repo = text_of(values.repo)
+	const repo = cli_flags.string_of(values.repo)
 
 	return [
 		'backlog:next',
@@ -120,7 +112,7 @@ function next_argv(values: ParsedValues): ReadonlyArray<string> {
 
 function budget_argv(values: ParsedValues, answer: string): ReadonlyArray<string> {
 	const forwarded = FORWARDED.flatMap((name) => {
-		const value = text_of(values[name])
+		const value = cli_flags.string_of(values[name])
 
 		return value === undefined ? [] : [`--${name}`, value]
 	})

package/scripts/backlog/backlog-plan.ts

@@ -3,6 +3,7 @@ import type { IssueReference } from '#scripts/epic/epic-reference'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo } from '#scripts/epic/epic-solo'
 import { epic_triage } from '#scripts/epic/epic-triage'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
@@ -57,23 +58,29 @@ interface PlanContext {
 
 // A child elsewhere is qualified, because a bare number would name *this* repository's issue of that
 // number — a different issue (joshuafolkken/kit#1016). Takes the reference rather than the child, so
-// a `blocked_by` edge is named by the same rule the child itself is.
-function reference_of(reference: IssueReference, repo: string): string {
+// a `blocked_by` edge is named by the same rule the child itself is. This repository's issue is cited
+// (joshuafolkken/kit#3099): the plan is copied into a report verbatim, so the line it prints is the
+// citation the report carries.
+function cite_of(reference: IssueReference, repo: string, title: string | undefined): string {
 	const number = String(reference.number)
 
-	return reference.repo === repo ? `#${number}` : `${reference.repo}#${number}`
+	return reference.repo === repo
+		? issue_cite.reference(repo, number, title)
+		: `${reference.repo}#${number}`
+}
+
+function reference_of(reference: IssueReference, repo: string): string {
+	return cite_of(reference, repo, undefined)
 }
 
 // A title is only known for this repository's issues — the open listing the titles come from is this
 // repository's. A child elsewhere is still named, just without one.
-function title_of(child: EpicChild, context: PlanContext): string {
-	return child.repo === context.repo ? (context.titles.get(child.number) ?? '') : ''
+function title_of(child: EpicChild, context: PlanContext): string | undefined {
+	return child.repo === context.repo ? context.titles.get(child.number) : undefined
 }
 
-function join_row(reference: string, title: string, note: string): string {
-	const parts = [reference, title, note === '' ? '' : `— ${note}`].filter((part) => part !== '')
-
-	return `${ROW_INDENT}${parts.join('  ')}`
+function join_row(reference: string, note: string): string {
+	return note === '' ? `${ROW_INDENT}${reference}` : `${ROW_INDENT}${reference}  — ${note}`
 }
 
 // A `run:solo` child is marked beside its number, so a person reading the plan sees which issues
@@ -89,15 +96,15 @@ function mark_of(child: EpicChild): string | undefined {
 	return epic_triage.is_triaged(child) ? undefined : UNTRIAGED_MARK
 }
 
-function marked_reference(child: EpicChild, repo: string): string {
-	const reference = reference_of(child, repo)
+function marked_reference(child: EpicChild, repo: string, title?: string): string {
+	const reference = cite_of(child, repo, title)
 	const mark = mark_of(child)
 
 	return mark === undefined ? reference : `${reference} ${mark}`
 }
 
 function row_of(child: EpicChild, context: PlanContext, note: string): string {
-	return join_row(marked_reference(child, context.repo), title_of(child, context), note)
+	return join_row(marked_reference(child, context.repo, title_of(child, context)), note)
 }
 
 // Why this one is not offered yet. The blocker numbers are the answer whenever there are any — that
@@ -164,8 +171,10 @@ function waiting_lines(children: ReadonlyArray<EpicChild>, context: PlanContext)
 	})
 }
 
-function scope_lines(rows: ReadonlyArray<OutOfScopeRow>): Array<string> {
-	return rows.map((row) => join_row(`#${String(row.number)}`, row.title, row.reason))
+function scope_lines(rows: ReadonlyArray<OutOfScopeRow>, repo: string): Array<string> {
+	return rows.map((row) =>
+		join_row(issue_cite.reference(repo, String(row.number), row.title), row.reason),
+	)
 }
 
 // The classification could not be made, so every section below it would be rendered from buckets
@@ -186,10 +195,12 @@ interface NamedPlan {
 	only: boolean
 }
 
-// The named issues are this repository's own, so a bare `#N` names them and a title is looked up the
-// same way the pool's rows are. The order is the invocation's, never sorted.
+// The named issues are this repository's own, so they are cited against it and a title is looked up
+// the same way the pool's rows are. The order is the invocation's, never sorted.
 function named_lines(named: ReadonlyArray<number>, context: PlanContext): Array<string> {
-	return named.map((issue) => join_row(`#${String(issue)}`, context.titles.get(issue) ?? '', ''))
+	return named.map((issue) =>
+		join_row(issue_cite.reference(context.repo, String(issue), context.titles.get(issue)), ''),
+	)
 }
 
 // The section leads the plan when the invocation named issues, and is absent otherwise — a bare
@@ -230,7 +241,7 @@ function format_plan(
 		'',
 		section(HUMAN_HEADING, child_lines(result.blocked_on_people, context, no_note)),
 		'',
-		section(SCOPE_HEADING, scope_lines(out_of_scope)),
+		section(SCOPE_HEADING, scope_lines(out_of_scope, context.repo)),
 	].join('\n')
 }
 

package/scripts/backlog/backlog-ready.ts

@@ -1,3 +1,5 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry } from '#scripts/lane/lane-registry'
@@ -92,35 +94,46 @@ async function read_ready(ports: ReadyPorts = DEFAULT_PORTS): Promise<ReadyReadi
 	return { issues: await ports.ready_issues(), free_lanes }
 }
 
-// `undefined` unless there is both runnable work and a lane for it — the only state worth a line.
-function ready_line(reading: ReadyReading): string | undefined {
+// `undefined` unless there is both runnable work and a lane for it — the only state worth a line. Each
+// issue is a number-link against `slug` (joshuafolkken/kit#3099): the parent copies this line into its
+// report, so a bare `#N` here is the citation the Stop guard sends back.
+function ready_line(reading: ReadyReading, slug: string | undefined): string | undefined {
 	if (reading.issues.length === NONE || reading.free_lanes <= NO_FREE) return undefined
 
-	const issues = reading.issues.map((issue) => `#${issue}`).join(' ')
+	const cite = issue_cite.citer(slug, new Map())
+	const issues = reading.issues.map((issue) => cite(issue)).join(' ')
 
 	return `ready ${issues} · free lanes ${String(reading.free_lanes)}`
 }
 
+type RepoRead = () => Promise<string | undefined>
+
 // The watcher's line on exit, for the driving parent alone — a `fullrun` watcher has no pool to pick
 // from. Best-effort: a reading that fails prints nothing rather than failing the watcher whose exit is
 // the wake.
 async function parent_ready_line(
 	ports: ReadyPorts,
 	is_parent: () => Promise<boolean>,
+	read_repo: RepoRead,
 ): Promise<string | undefined> {
 	if (!(await is_parent())) return undefined
 
-	return ready_line(await read_ready(ports))
+	const reading = await read_ready(ports)
+
+	return reading.issues.length === NONE ? undefined : ready_line(reading, await read_repo())
+}
+
+function print_line(line: string | undefined): void {
+	if (line !== undefined) console.info(line)
 }
 
 async function print_ready_line(
 	ports: ReadyPorts = DEFAULT_PORTS,
 	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+	read_repo: RepoRead = git_gh_command.repo_get_name_with_owner,
 ): Promise<void> {
 	try {
-		const line = await parent_ready_line(ports, is_parent)
-
-		if (line !== undefined) console.info(line)
+		print_line(await parent_ready_line(ports, is_parent, read_repo))
 	} catch {
 		// A pick-up line is a hint; the wake it rides must still be delivered.
 	}

package/scripts/config-merge/parse-jsonc.ts

@@ -1,14 +1,44 @@
 import { json_object_schema } from '#scripts/lib/schemas'
-import strip_json_comments from 'strip-json-comments'
+import { parseTree, printParseErrorCode, type Node, type ParseError } from 'jsonc-parser'
 
 // Every managed JSON config kit reads (tsconfig.json, package.json, .vscode/*.json) may legally
 // carry comments and trailing commas — TypeScript and VS Code both parse them as JSONC — so a plain
 // `JSON.parse` would throw on files consumers hand-authored. Single-sourced here because the
 // config-merge library and the init/sync merge helpers both need the exact same tolerant read.
+
+// Built from the tree rather than with jsonc-parser's own `parse` / `getNodeValue`, which assign each
+// key: a `"__proto__"` key would become the object's prototype instead of the own property
+// `JSON.parse` keeps, and the spread-and-stringify write-back would then drop it from the file.
+// `Object.fromEntries` defines properties, so every key stays data.
+function property_key(property: Node): string {
+	return String(property.children?.[0]?.value)
+}
+
+function node_value(node: Node | undefined): unknown {
+	if (node === undefined) return undefined
+	const children = node.children ?? []
+	if (node.type === 'array') return children.map((child) => node_value(child))
+	if (node.type !== 'object') return node.value
+
+	return Object.fromEntries(
+		children.map((property) => [property_key(property), node_value(property.children?.[1])]),
+	)
+}
+
+// jsonc-parser recovers from errors and returns a best-effort tree, so any reported error is
+// rethrown: a malformed document must fail the read the way `JSON.parse` would, not merge partially.
 function parse_jsonc(content: string): Record<string, unknown> {
-	const stripped = strip_json_comments(content, { trailingCommas: true })
+	const errors: Array<ParseError> = []
+	const tree = parseTree(content, errors, { allowTrailingComma: true })
+	const [first_error] = errors
+
+	if (first_error !== undefined) {
+		throw new SyntaxError(
+			`Invalid JSONC: ${printParseErrorCode(first_error.error)} at offset ${String(first_error.offset)}`,
+		)
+	}
 
-	return json_object_schema.parse(JSON.parse(stripped))
+	return json_object_schema.parse(node_value(tree))
 }
 
 export { parse_jsonc }

package/scripts/config-merge/patch-json-key.ts

@@ -1,5 +1,11 @@
-import { createScanner, findNodeAtLocation, getNodeValue, parseTree, type Node } from 'jsonc-parser'
-import strip_json_comments from 'strip-json-comments'
+import {
+	createScanner,
+	findNodeAtLocation,
+	getNodeValue,
+	parseTree,
+	stripComments,
+	type Node,
+} from 'jsonc-parser'
 import { json_format } from './json-format'
 
 // Set or remove one top-level key while leaving every other byte of the document alone.
@@ -163,13 +169,14 @@ function target_value_end(property: Node | undefined): number | undefined {
 	return value_node === undefined ? undefined : value_node.offset + value_node.length
 }
 
-// Whether the span holds a comment. `strip_json_comments` blanks comments while preserving length
-// and is string-aware, so a `//` inside a string value is not counted — a scanner-based check would
-// need `SyntaxKind`, which is an ambient const enum this project cannot import.
+// Whether the span holds a comment. `stripComments` drops every comment token the scanner finds, so
+// it changes the text exactly when a comment is present, and a `//` inside a string value is not
+// counted — comparing token kinds directly would need `SyntaxKind`, an ambient const enum this
+// project cannot import.
 function contains_comment(content: string, node: Node): boolean {
 	const text = content.slice(node.offset, node.offset + node.length)
 
-	return strip_json_comments(text) !== text
+	return stripComments(text) !== text
 }
 
 // Re-lay-out a property whose trailing comma has just appeared or disappeared. That one column

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 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 { cost_corpus } from './cost-corpus'
@@ -103,13 +103,9 @@ const PARSE_ARGS_OPTIONS = {
 } as const
 
 function parse_options(argv: ReadonlyArray<string>): Options | undefined {
-	try {
-		const { values } = parseArgs({ args: [...argv], options: PARSE_ARGS_OPTIONS, strict: true })
+	const values = cli_flags.values_of(argv, PARSE_ARGS_OPTIONS)
 
-		return to_options(values)
-	} catch {
-		return undefined
-	}
+	return values === undefined ? undefined : to_options(values)
 }
 
 // An empty corpus is reported, never priced at zero. "No transcript was found" and "this run was

package/scripts/doctor/doctor-consumer.ts

@@ -1,10 +1,9 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
-import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
-import { execaSync } from 'execa'
 import { z } from 'zod'
 
 // The consumer-setup checks `josh doctor` runs in a repository that installs kit (joshuafolkken/kit#1930).
@@ -77,11 +76,9 @@ function is_plugin_declared(root: string): boolean {
 // The value of `core.hooksPath`, or undefined when it is unset. A set value is what stops lefthook
 // from installing kit's git hooks — the failure is silent but for one stderr line.
 function configured_hooks_path(root: string): string | undefined {
-	const result = execaSync('git', ['-C', root, 'config', '--get', 'core.hooksPath'], {
-		reject: false,
+	const value = git_spawn_sync.read(['-C', root, 'config', '--get', 'core.hooksPath'], {
 		timeout: GIT_TIMEOUT_MS,
 	})
-	const value = read_spawn_stdout(result).trim()
 
 	return value === '' ? undefined : value
 }
@@ -159,6 +156,7 @@ function report_consumer_setup(root: string): void {
 const doctor_consumer = {
 	claude_md_line,
 	claude_md_state,
+	configured_hooks_path,
 	hooks_path_line,
 	is_kit_consumer,
 	is_plugin_declared,

package/scripts/doctor/doctor-io.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
-import { read_spawn_stderr, read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
@@ -69,18 +70,13 @@ function classify_git_failure(exit_code: number | undefined, stderr: string): Gi
 // caller's check, because reporting an unknown as a clean result is the false all-clear
 // joshuafolkken/kit#805 exists to remove. See the two classifiers above for what proves what.
 function resolve_git_top_level(): GitTopLevel {
-	const result = execaSync('git', ['rev-parse', '--show-toplevel'], {
-		reject: false,
-		timeout: GIT_TIMEOUT_MS,
-		// git translates its messages, so the match below would fail under any non-English locale and
-		// the spurious warning would come back. `C` pins the output this code was written against.
-		env: { LC_ALL: 'C', LANGUAGE: 'C' },
-		extendEnv: true,
-	})
-
-	if (result.exitCode === 0) return classify_top_level(read_spawn_stdout(result).trim())
-
-	return classify_git_failure(result.exitCode, read_spawn_stderr(result))
+	// The C locale `toplevel` asks under is what keeps the stderr match below from failing on a
+	// translated message and bringing the spurious warning back.
+	const result = git_spawn_sync.toplevel(GIT_TIMEOUT_MS)
+
+	if (result.exit_code === 0) return classify_top_level(result.stdout.trim())
+
+	return classify_git_failure(result.exit_code, result.stderr)
 }
 
 // Whether one line is the setting itself rather than prose about it. kit's own template explains the

package/scripts/document/backlogrun-parent-read-set.ts

@@ -34,15 +34,26 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 // the park — so it drops none. Named empty so the shared trim reads the same shape as the worker's.
 const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set<string>()
 
+// **The parent runs the end-of-run retrospective** (`SKILL.md` §2j) when `run:step` prints it, but its
+// manifest names `retrospective.md` only through `backlogrun-steps.md` — one hop further than the
+// derivation follows — so the parent's reach names it (joshuafolkken/kit#3078).
+const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['retrospective.md'])
+
 function costed(root: string): ReadSetCost {
 	return read_set_trim.costed(root, {
 		base_entry: BACKLOGRUN,
 		label: BACKLOGRUN,
 		unused_skill_sections: UNUSED_SKILL_SECTIONS,
 		skipped_point_of_use: SKIPPED_POINT_OF_USE,
+		reached_point_of_use: REACHED_POINT_OF_USE,
 	})
 }
 
-const backlogrun_parent_read_set = { BACKLOGRUN, UNUSED_SKILL_SECTIONS, costed }
+const backlogrun_parent_read_set = {
+	BACKLOGRUN,
+	REACHED_POINT_OF_USE,
+	UNUSED_SKILL_SECTIONS,
+	costed,
+}
 
 export { backlogrun_parent_read_set }

package/scripts/document/document-byte-budget.ts

@@ -88,6 +88,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 8192 },
 	// #2662 adds the feature and compatibility declarations to the canonical filing procedure.
 	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 28_672 },

package/scripts/document/entry-read-budget.ts

@@ -3,8 +3,9 @@
 //
 // **The per-document ceiling was a proxy for a run's cost, not the cost.** A run does not pay "one
 // document's size"; it pays the total its entry reads — the mandated skill files, the sections they
-// point out to, the point-of-use documents reached later, and the resident `CLAUDE.md` every request
-// carries. `read:set` already computes that total, so this budgets it directly: the entry total is
+// point out to, the point-of-use documents that entry reaches later, and the resident `CLAUDE.md` every
+// request carries. `read:set`'s `total read` is that sum less `CLAUDE.md`, which `entry_total_bytes`
+// adds back (`RESIDENT_BASE`), so this budgets the whole directly: the entry total is
 // the primary ceiling, and the per-document ceiling (`document-byte-budget.ts`) falls back to the
 // documents no entry reads (`document-reachability.ts` draws the line). A document an entry reads is
 // held by the entry total and carries no per-document ceiling, so neither budget holds it twice.
@@ -86,11 +87,16 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// `wip-cap.md`, so its ceiling stays.
 	// joshuafolkken/kit#3023 added the `prrun` keyword to `SKILL.md` and `CLAUDE.md`, tipping backlogrun
 	// one block over; `prrun` reads `fullrun`'s set plus its own short manifest.
-	{ entry: 'kickoff', bytes: 229_376 },
-	{ entry: 'fullrun', bytes: 225_280 },
-	{ entry: 'halfrun', bytes: 225_280 },
-	{ entry: 'prrun', bytes: 229_376 },
-	{ entry: 'backlogrun', bytes: 233_472 },
+	// Lowered in joshuafolkken/kit#3078 — a correction of an over-count, not a trim: every entry was
+	// charged for every global point-of-use document, so `kickoff` paid for `followup.md` and the
+	// `backlogrun-*` phase documents it never opens. Each total now counts only what its path reaches.
+	// joshuafolkken/kit#3077 trimmed non-resident rule bodies from `CLAUDE.md`, lowering fullrun, prrun
+	// and backlogrun one block each.
+	{ entry: 'kickoff', bytes: 65_536 },
+	{ entry: 'fullrun', bytes: 126_976 },
+	{ entry: 'halfrun', bytes: 106_496 },
+	{ entry: 'prrun', bytes: 131_072 },
+	{ entry: 'backlogrun', bytes: 212_992 },
 	{ entry: LANE_CHILD, bytes: 77_824 },
 ]