@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/backlog/backlog-stalled-detect.ts

@@ -1,6 +1,6 @@
 import { telegram_notify } from '#scripts/notify/telegram-notify'
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
 import { backlog_stalled, type StallReading, type StallVerdict } from './backlog-stalled'
 

package/scripts/backlog/backlog-stalled.ts

@@ -1,5 +1,5 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 // When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks
 // (joshuafolkken/kit#2359). This is the mechanical judge of that state: three facts read, never

package/scripts/backlog/backlog-waves.ts

@@ -10,7 +10,7 @@ import {
 	NEEDS_DECISION_LABEL,
 } from '#scripts/issue/issue-labels'
 import { backlog_plan, type PlanContext } from './backlog-plan'
-import { backlog_rank } from './backlog-rank'
+import { backlog_rank, type GateScope } from './backlog-rank'
 
 // The order a `backlogrun` takes, wave by wave, before it starts (joshuafolkken/kit#2778).
 //
@@ -18,7 +18,8 @@ import { backlog_rank } from './backlog-rank'
 // made from, so the order past the first answer was left for a person to work out by hand. This plays
 // the asks forward under one assumption: **every issue of a wave merges before the next wave starts**.
 //
-// **No rule is written twice.** The first wave is `backlog_rank.select` — rank, `run:solo` gate, cap —
+// **No rule is written twice.** The first wave is `backlog_rank.select` — rank, `run:solo` gate,
+// restructure separation, cap —
 // over the very candidates `backlog:next` resolves, asked of an idle repository — so it is what
 // `backlog:next` prints when nothing is running (joshuafolkken/kit#2928). Each later wave marks the earlier waves closed and re-classifies the same pool
 // through `epic_classify.classify_children` with the resolver `epic:next` sorted it with the first
@@ -28,6 +29,7 @@ import { backlog_rank } from './backlog-rank'
 
 const IDLE: BusyRead = { kind: 'idle' }
 const CLOSED = 'CLOSED'
+const EMPTY_SCOPE: GateScope = { standalone: new Set(), declared: new Map() }
 
 const HEADING_ASSUMPTION =
 	'Assumes every issue in a wave merges before the next wave starts. Issues a run already has are left out, and only issues of this repository are planned.'
@@ -59,17 +61,17 @@ interface WavePool {
 	children: ReadonlyArray<EpicChild>
 	running: ReadonlySet<string>
 	repo: string
-	standalone: ReadonlySet<string>
+	scope: GateScope
 }
 
-function pool_of(result: EpicNextResult, repo: string, standalone: ReadonlySet<string>): WavePool {
+function pool_of(result: EpicNextResult, repo: string, scope: GateScope): WavePool {
 	const all = backlog_rank.everything_in(result)
 
 	return {
 		children: all.filter((child) => !is_running(child)),
 		running: epic_outside_blocker.running_keys(all),
 		repo,
-		standalone,
+		scope,
 	}
 }
 
@@ -78,9 +80,9 @@ function offer(
 	children: ReadonlyArray<EpicChild>,
 	pool: WavePool,
 ): ReadonlyArray<EpicChild> {
-	const { repo, standalone } = pool
+	const { repo, scope } = pool
 
-	return backlog_rank.select({ candidates, pool: children, read: IDLE, repo, standalone }).offered
+	return backlog_rank.select({ candidates, pool: children, read: IDLE, repo, ...scope }).offered
 }
 
 // Ranked against the whole result, exactly as `backlog:next` ranks it, so the two agree.
@@ -106,14 +108,10 @@ function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<Epi
 }
 
 // Each wave is closed before the next is asked for; a wave that offers nothing ends the plan, which
-// the pool's size bounds because every wave closes at least one child. `standalone` names the rows the
-// offer's cap bounds; left empty, no wave is capped.
-function build(
-	result: EpicNextResult,
-	repo: string,
-	standalone: ReadonlySet<string> = new Set(),
-): WavePlan {
-	const pool = pool_of(result, repo, standalone)
+// the pool's size bounds because every wave closes at least one child. `scope` names the rows the
+// offer's cap bounds and the paths each issue restructures; left empty, no wave is capped or separated.
+function build(result: EpicNextResult, repo: string, scope: GateScope = EMPTY_SCOPE): WavePlan {
+	const pool = pool_of(result, repo, scope)
 	const done = new Set<string>()
 	const waves: Array<ReadonlyArray<EpicChild>> = []
 
@@ -155,11 +153,11 @@ function unreached_lines(plan: WavePlan, context: PlanContext): Array<string> {
 function format_waves(
 	result: EpicNextResult,
 	context: PlanContext,
-	standalone: ReadonlySet<string> = new Set(),
+	scope: GateScope = EMPTY_SCOPE,
 ): string {
 	if (result.verdict === 'error') return backlog_plan.format_unusable(result)
 
-	const plan = build(result, context.repo, standalone)
+	const plan = build(result, context.repo, scope)
 	const waves = plan.waves.map((wave, index) => wave_line(wave, index, context.repo))
 
 	return [

package/scripts/build/build-codex-hooks.ts

@@ -10,7 +10,9 @@ const CODEX_HOOKS = path.join(REPO_ROOT, '.codex', 'hooks.json')
 
 // Regenerate `.codex/hooks.json` from `.claude/settings.json` (joshuafolkken/kit#2997). The output is
 // committed rather than gitignored: Codex reads it straight from a fresh clone of kit, before any
-// build has run, and `josh init` / `josh sync` copy it to consumers from the package.
+// build has run, and `josh init` / `josh sync` copy it to consumers from the package. It is run by
+// hand, never from `pnpm build`, so a build never rewrites a committed file (joshuafolkken/kit#3324):
+// `codex-project-config.test.ts` fails the gate when the committed copy has drifted.
 function build_codex_hooks(): string {
 	writeFileSync(CODEX_HOOKS, codex_hooks.codex_hooks_text(readFileSync(CLAUDE_SETTINGS, 'utf8')))
 

package/scripts/build/build-commands.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env tsx
+import { rmSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { COMMAND_MAP } from '#scripts/josh/josh-command-map'
+import { BUNDLED_COMMAND_DIRECTORY, josh_in_process } from '#scripts/josh/josh-in-process'
+import { error_text } from '#scripts/lib/error-message'
+import { build } from 'esbuild'
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const OUT_DIR = path.join(PACKAGE_DIR, BUNDLED_COMMAND_DIRECTORY)
+
+// Each `is_bundled` command is pre-built to its own `dist/commands/<script basename>.js`, so a
+// consumer's `dist/josh.js` imports it under plain node instead of spawning tsx for its `.ts`
+// (joshuafolkken/kit#3328, `docs/maintainers/runtime-bundling.md`).
+//
+// **No code splitting, and that is why the import closure is checked.** Every entry is one
+// self-contained file, so every module it imports shares the entry's `import.meta.url`; a second
+// `process.argv[1] === fileURLToPath(import.meta.url)` guard inside the closure would fire with the
+// entry's own. `build-commands.test.ts` refuses a bundled command whose closure carries one.
+//
+// The bundle sits two levels under the package root, exactly as its source does under `scripts/`,
+// so a module that finds the package from its own `import.meta.url` resolves the same directory.
+function bundled_scripts(): Array<string> {
+	return Object.values(COMMAND_MAP)
+		.filter((entry) => entry.is_bundled === true)
+		.map((entry) => entry.script ?? '')
+}
+
+function entry_point(script: string): { in: string; out: string } {
+	const out = path.basename(josh_in_process.bundled_script_path(PACKAGE_DIR, script), '.js')
+
+	return { in: path.join(PACKAGE_DIR, script), out }
+}
+
+// Nothing in this checkout launches `dist/commands/` (kit's own `pnpm josh` runs the source), so the
+// directory is emptied first rather than pruned after, which drops the output of a command no longer
+// bundled.
+async function build_commands(out_directory: string = OUT_DIR): Promise<string> {
+	rmSync(out_directory, { recursive: true, force: true })
+	await build({
+		absWorkingDir: PACKAGE_DIR,
+		entryPoints: bundled_scripts().map((script) => entry_point(script)),
+		outdir: out_directory,
+		bundle: true,
+		platform: 'node',
+		format: 'esm',
+		target: 'node22',
+		packages: 'external',
+	})
+
+	return out_directory
+}
+
+async function main(): Promise<void> {
+	try {
+		console.info(`  ✔ ${await build_commands()} built`)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_commands, bundled_scripts, OUT_DIR }

package/scripts/build/build-hooks.ts

@@ -49,7 +49,7 @@ interface HookBundle {
 	out: string
 }
 
-// The three settings.json hooks, the Codex input adapter, and the three guards `pretool-guard`
+// The settings.json hooks (the session-start audit provisioner among them), the Codex input adapter, and the three guards `pretool-guard`
 // composes: `batch-guard`, `investigation-guard` and `duplicate-read-guard` each self-invoke, so they
 // must be their own entries to keep their `import.meta.url` out of `pretool-guard`'s file.
 // `delivered-rules` (the fourth guard) has no self-invoke, so it stays inlined.
@@ -59,6 +59,7 @@ const HOOK_BUNDLES: ReadonlyArray<HookBundle> = [
 	{ source: 'scripts/hooks/stop-guard.ts', out: 'stop-guard' },
 	{ source: 'scripts/hooks/format-edited-cli.ts', out: 'format-edited' },
 	{ source: 'scripts/josh/session-language-cli.ts', out: 'session-lang' },
+	{ source: 'scripts/security/security-audit-provision.ts', out: 'audit-provision' },
 	{ source: 'scripts/hooks/batch-guard.ts', out: 'batch-guard' },
 	{ source: 'scripts/delegation/investigation-guard.ts', out: 'investigation-guard' },
 	{ source: 'scripts/delegation/duplicate-read-guard.ts', out: 'duplicate-read-guard' },

package/scripts/build/build-library.ts

@@ -7,6 +7,13 @@ import { dts } from 'rollup-plugin-dts'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const SCRIPTS_IMPORT_PREFIX = '#scripts/'
+// Every public library `pnpm build` bundles — each one a `./<name>` export in package.json.
+const PUBLIC_LIBRARIES: ReadonlyArray<string> = [
+	'version',
+	'config-merge',
+	'managed-marker',
+	'self-sync-guard',
+]
 
 interface LibraryPaths {
 	entry_point: string
@@ -73,11 +80,13 @@ async function build_library_dts(entry_point: string, dts_file: string): Promise
 async function build_library(name: string): Promise<LibraryPaths> {
 	const paths = library_paths(name)
 
-	await build_library_js(paths.entry_point, paths.outfile)
-	await build_library_dts(paths.entry_point, paths.dts_file)
+	await Promise.all([
+		build_library_js(paths.entry_point, paths.outfile),
+		build_library_dts(paths.entry_point, paths.dts_file),
+	])
 
 	return paths
 }
 
 export type { LibraryPaths }
-export { build_library, library_paths }
+export { build_library, library_paths, PUBLIC_LIBRARIES }

package/scripts/build/build.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
+import { OUTFILE as BIN_OUTFILE, build_bin } from './build-bin'
+import { build_claude_md } from './build-claude-md'
+import { build_commands } from './build-commands'
+import { build_hooks, OUT_DIR as HOOKS_OUT_DIR } from './build-hooks'
+import { build_library, PUBLIC_LIBRARIES } from './build-library'
+
+interface BuildStep {
+	name: string
+	run: () => Promise<string>
+}
+
+async function bin_step(): Promise<string> {
+	await build_bin()
+
+	return BIN_OUTFILE
+}
+
+async function hooks_step(): Promise<string> {
+	await build_hooks()
+
+	return HOOKS_OUT_DIR
+}
+
+async function library_step(name: string): Promise<string> {
+	const { outfile } = await build_library(name)
+
+	return outfile
+}
+
+async function claude_md_step(): Promise<string> {
+	return build_claude_md()
+}
+
+// Every step `pnpm build` runs (joshuafolkken/kit#3324). The steps write disjoint paths under
+// `dist/`, so they run concurrently from this one entry instead of eight serial `tsx` launches.
+// Nothing here writes a git-tracked file: `.codex/hooks.json` is regenerated by hand with
+// `tsx scripts/build/build-codex-hooks.ts`, and `codex-project-config.test.ts` fails the gate when
+// the committed copy drifts from `.claude/settings.json`.
+function build_steps(): ReadonlyArray<BuildStep> {
+	return [
+		{ name: 'bin', run: bin_step },
+		{ name: 'hooks', run: hooks_step },
+		{ name: 'commands', run: async () => await build_commands() },
+		...PUBLIC_LIBRARIES.map((name) => ({ name, run: async () => await library_step(name) })),
+		{ name: 'claude-md', run: claude_md_step },
+	]
+}
+
+async function build_all(): Promise<ReadonlyArray<string>> {
+	return await Promise.all(build_steps().map(async (step) => await step.run()))
+}
+
+async function main(): Promise<void> {
+	try {
+		const outputs = await build_all()
+
+		for (const output of outputs) console.info(`  ✔ ${output} built`)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export type { BuildStep }
+export { build_all, build_steps }

package/scripts/build/local-bin.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { package_bin_schema } from '#scripts/lib/schemas'
 
 const NODE_MODULES = 'node_modules'
@@ -27,20 +28,9 @@ function resolve_local_bin(project_root: string, bin_name: string): string {
 // in `src/lib` would miss the toolkit its sibling checks resolve fine (joshuafolkken/kit#934).
 // Ascending for the shim itself, rather than for a `package.json` first, is what keeps the two in
 // step: a nested manifest that owns no `node_modules` is not where pnpm would stop either.
-function ancestor_directories(start_directory: string): ReadonlyArray<string> {
-	const directories: Array<string> = []
-	let current = start_directory
-
-	while (!directories.includes(current)) {
-		directories.push(current)
-		current = path.dirname(current)
-	}
-
-	return directories
-}
-
 function find_local_bin_upwards(start_directory: string, bin_name: string): string | undefined {
-	return ancestor_directories(start_directory)
+	return ancestor_directories
+		.list(start_directory)
 		.map((directory) => resolve_local_bin(directory, bin_name))
 		.find((candidate) => existsSync(candidate))
 }

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

@@ -10,12 +10,4 @@ import { context_cut_payback } from './context-cut-payback'
 // 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 }
+export { CONTEXT_CUT_THRESHOLD }

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

@@ -3,42 +3,31 @@
 // of a session will cost, and takes only the figures its verdict needs — an over measurement — never
 // a whole report. The `--cap` counterfactual it once sat beside was retired in #2016 as readerless.
 
-import { RECENT_REQUEST_WINDOW } from './context-cut-threshold'
-
 const FAILURE_EXIT_CODE = 1
 const OVER_VERDICT = 'over'
 const UNDER_VERDICT = 'under'
 
-// What `--over` reads of a session: the billed input each request paid, oldest first. The whole
-// per-request sequence is carried rather than a single sum because the hand-off prices the recent
-// tail alone (joshuafolkken/kit#2295) — a long session's whole-session average lags its current
-// context by dozens of requests, so a sum could not answer what the recent window actually cost.
+// 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
+// (joshuafolkken/kit#3224) — a sum could not answer what the session's current context costs.
 interface OverMeasurement {
 	billed_input_per_request: ReadonlyArray<number>
 }
 
-// The most recent requests the hand-off prices, oldest first — the whole sequence when it is shorter
-// than the window, so a session with fewer than `RECENT_REQUEST_WINDOW` requests is priced on what it
-// has rather than padded.
-function recent_requests(measurement: OverMeasurement): ReadonlyArray<number> {
-	return measurement.billed_input_per_request.slice(-RECENT_REQUEST_WINDOW)
-}
-
 // What a turn costs is decided by the accumulated preamble, not by what the turn does, so the
-// marginal cost of a session is the billed input its recent requests paid. Measured across one
+// marginal cost of a session is the billed input its newest request paid. Measured across one
 // `epicrun` that ran six children in one context: 222k per request during the first child, 645k
 // during the sixth — the same work at 2.9x the price (joshuafolkken/kit#968).
 //
-// The recent window rather than the whole session, because a long parent's whole-session average
-// lags its current context by dozens of requests (joshuafolkken/kit#2295); the recent average says
-// what the *next* turn will cost, which is the thing a hand-off decision turns on.
+// **The newest request, not an average.** joshuafolkken/kit#2295 replaced the whole-session average,
+// which lagged a long parent by dozens of requests, with the average of the last ten; that still
+// lagged. A session's billed input only grows between compactions (a unit writes its own transcript),
+// so an average smooths no outlier — it only trails the context it averages. On 2026-10-05 wake
+// session 03367124 crossed the threshold at request 65 and its ten-request average at request 70
+// (joshuafolkken/kit#3224). The threshold is a break-even on the *current* context
+// (`context-cut-payback.ts`), so the current context is what it is compared against.
 function per_request_cost(measurement: OverMeasurement): number {
-	const window = recent_requests(measurement)
-	if (window.length === 0) return 0
-
-	const total = window.reduce((sum, billed) => sum + billed, 0)
-
-	return Math.round(total / window.length)
+	return measurement.billed_input_per_request.at(-1) ?? 0
 }
 
 // The bare over/under decision, without a report: `run:status` reads this same verdict read-only
@@ -51,14 +40,12 @@ function classify(
 	return per_request_cost(measurement) > limit ? OVER_VERDICT : UNDER_VERDICT
 }
 
-// The stderr line names the window the average covers, so the reader can tell a recent-tail average
-// from a whole-session one (joshuafolkken/kit#2295): "the last W of T request(s)" reads W when the
-// session is longer than the window and the whole count when it is shorter.
+// The stderr line names which request was priced, so the reader can tell the newest request's cost
+// from an average over the session (joshuafolkken/kit#3224).
 function over_summary(measurement: OverMeasurement, limit: number): string {
 	const total = measurement.billed_input_per_request.length
-	const window = recent_requests(measurement).length
 
-	return `${String(per_request_cost(measurement))} billed input tokens per request over the last ${String(window)} of ${String(total)} request(s); limit ${String(limit)}`
+	return `${String(per_request_cost(measurement))} billed input tokens per request, on the newest of ${String(total)} request(s); limit ${String(limit)}`
 }
 
 // A verdict, not a table: the point of the flag is that the hand-off is decided by a number rather

package/scripts/delegation/investigation-reads.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { capped_print_part } from '#scripts/document/capped-print-part'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
 import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_bundle_call } from '#scripts/time-runtime/time-bundle-call'
@@ -212,7 +213,8 @@ function is_session_artifact(target: string): boolean {
 
 	return (
 		segments.some((_segment, index) => has_state_root(segments, index)) ||
-		is_harness_output(segments)
+		is_harness_output(segments) ||
+		capped_print_part.is_part_file(absolute)
 	)
 }
 

package/scripts/discovery/repo-origin.ts

@@ -111,12 +111,12 @@ function origin_section_lines(lines: ReadonlyArray<string>): Array<string> {
 	return end === NOT_FOUND ? rest : rest.slice(0, end)
 }
 
-// The value of a `key = value` entry, or nothing when the line declares a different key. Split on
+// The value of a `url = value` entry, or nothing when the line declares a different key. Split on
 // the first separator rather than matched, for the reason `parse_scp_like` is split by hand.
-function entry_value(line: string, key: string): string | undefined {
+function url_value(line: string): string | undefined {
 	const separator = line.indexOf('=')
 	if (separator === NOT_FOUND) return undefined
-	if (line.slice(0, separator).trim() !== key) return undefined
+	if (line.slice(0, separator).trim() !== URL_KEY) return undefined
 
 	return line.slice(separator + 1).trim()
 }
@@ -129,7 +129,7 @@ function parse_origin_from_config(content: string): string | undefined {
 	const lines = content.split('\n').map((line) => line.trim())
 
 	return origin_section_lines(lines)
-		.map((line) => entry_value(line, URL_KEY))
+		.map((line) => url_value(line))
 		.find((url) => url !== undefined)
 }
 
@@ -153,7 +153,7 @@ function parse_remote_urls_from_config(content: string): Array<string> {
 
 	return section_groups(lines)
 		.filter((group) => REMOTE_SECTION.test(group[0] ?? ''))
-		.flatMap((group) => group.map((line) => entry_value(line, URL_KEY)))
+		.flatMap((group) => group.map((line) => url_value(line)))
 		.filter((url) => url !== undefined)
 }
 

package/scripts/doctor/doctor-consumer.ts

@@ -3,6 +3,7 @@ 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 { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { z } from 'zod'
 
@@ -20,7 +21,6 @@ const PLUGIN_ID = 'kit@kit'
 // full document, so this pointer is also what tells a consumer repository apart from kit itself.
 const CLAUDE_MD_POINTER = `@${NODE_MODULES}/${KIT_PACKAGE_NAME}/dist/${CLAUDE_MD}`
 const SECRETLINT_BIN = path.join(NODE_MODULES, '.bin', 'secretlint')
-const GIT_TIMEOUT_MS = 2000
 
 const manifest_schema = z.object({
 	name: z.string().optional(),
@@ -77,7 +77,7 @@ function is_plugin_declared(root: string): boolean {
 // from installing kit's git hooks — the failure is silent but for one stderr line.
 function configured_hooks_path(root: string): string | undefined {
 	const value = git_spawn_sync.read(['-C', root, 'config', '--get', 'core.hooksPath'], {
-		timeout: GIT_TIMEOUT_MS,
+		timeout: PROBE_TIMEOUT_MS,
 	})
 
 	return value === '' ? undefined : value

package/scripts/doctor/doctor-io.ts

@@ -2,11 +2,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
 const JOSH_BIN = 'josh'
-const GIT_TIMEOUT_MS = 2000
 const NOT_A_REPOSITORY_MESSAGE = 'not a git repository'
 const NPM_VERSION_UPDATES_DISABLED = 'open-pull-requests-limit: 0'
 const DEPENDABOT_CONFIG_PATH = '.github/dependabot.yml'
@@ -72,7 +72,7 @@ function classify_git_failure(exit_code: number | undefined, stderr: string): Gi
 function resolve_git_top_level(): GitTopLevel {
 	// 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)
+	const result = git_spawn_sync.toplevel(PROBE_TIMEOUT_MS)
 
 	if (result.exit_code === 0) return classify_top_level(result.stdout.trim())
 
@@ -194,7 +194,6 @@ type GitTopLevel =
 	{ state: 'inside'; top_level: string } | { state: 'outside' } | { state: 'undetermined' }
 
 const doctor_io = {
-	GIT_TIMEOUT_MS,
 	resolve_path_josh,
 	resolve_pnpm_global_josh,
 	has_distributed_dependabot_config,

package/scripts/document/capped-print-part.ts

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+// Where `capped-print.ts` writes the parts of an over-cap output, and how a path is recognized as one
+// of them (joshuafolkken/kit#3332). Both halves live here so the writer and the investigation guard,
+// which must not count a read of a part as reading the Issue's subject, share one spelling of the
+// shape — kept free of the writer's own imports, since the guard runs as a hook on every tool call.
+
+const DIRECTORY_PREFIX = 'josh-capped-print-'
+const PART_PREFIX = 'part-'
+const PART_SUFFIX = '.md'
+// A part is `part-<N>.md` and nothing else, so a run's own file that happens to sit beside one is not
+// mistaken for it.
+const PART_PATTERN = /^part-[1-9]\d*\.md$/u
+
+function part_name(index: number): string {
+	return `${PART_PREFIX}${String(index + 1)}${PART_SUFFIX}`
+}
+
+// **The file's own parent, and the file's own name, both have to match.** A directory prefix alone
+// would exempt anything a run unpacked under a similarly named directory; the caller also requires the
+// path to lie outside the checkout, so no repository file is ever exempted by its name.
+function is_part_file(absolute: string): boolean {
+	const parent = path.basename(path.dirname(absolute))
+
+	return parent.startsWith(DIRECTORY_PREFIX) && PART_PATTERN.test(path.basename(absolute))
+}
+
+const capped_print_part = { DIRECTORY_PREFIX, part_name, is_part_file }
+
+export { capped_print_part }

package/scripts/document/capped-print.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { review_diff_parts } from '#scripts/review/review-diff-parts'
 import { bash_output_cap_reader } from './bash-output-cap'
+import { capped_print_part } from './capped-print-part'
 
 // Prints a command's output whole when it fits under the Bash output cap, and as part files when it
 // does not (joshuafolkken/kit#3143). Past `BASH_MAX_OUTPUT_LENGTH` Claude Code saves the output and
@@ -17,9 +18,7 @@ import { bash_output_cap_reader } from './bash-output-cap'
 // in one turn, and a shared directory replaced on every call would delete one call's parts while
 // another call's listing still names them.
 
-const DIRECTORY_PREFIX = 'josh-capped-print-'
 const FILE_MODE = 0o600
-const PART_SUFFIX = '.md'
 const LINE_BREAK = '\n'
 // What else shares the Bash result with this output: the launcher line, a script banner, a few
 // stderr lines. Measured at about 80 characters for `pnpm josh doc:section` in kit, so 512 holds the
@@ -27,10 +26,10 @@ const LINE_BREAK = '\n'
 const HEADROOM_CHARS = 512
 
 function write_parts(label: string, text: string, cap: number): Array<string> {
-	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, DIRECTORY_PREFIX))
+	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, capped_print_part.DIRECTORY_PREFIX))
 
 	return review_diff_parts.part_texts(label, text, cap).map((part, index) => {
-		const file = path.join(directory, `part-${String(index + 1)}${PART_SUFFIX}`)
+		const file = path.join(directory, capped_print_part.part_name(index))
 
 		writeFileSync(file, part, { flag: 'wx', mode: FILE_MODE })
 

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

@@ -88,8 +88,17 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	// joshuafolkken/kit#2998 split the reference: the developer commands stay, the rest moved out.
 	// joshuafolkken/kit#3175 raised it: the supervisor, provider-table and answer-to-budget prose moved
 	// here out of `backlogrun-steps.md`, so a run reads it only when it asks about those commands.
-	{ path: 'docs/josh-commands-automation.md', bytes: 159_744 },
-	{ path: 'docs/josh-commands.md', bytes: 36_864 },
+	// joshuafolkken/kit#3277 moved the run, lane and session commands to `docs/josh-commands-run.md`.
+	// joshuafolkken/kit#3280 moved the issue, epic, backlog and review commands to
+	// `docs/josh-commands-backlog.md`.
+	// joshuafolkken/kit#3278 moved `josh latest` and `josh overrides` — commands a person types — from
+	// the automation page to `docs/josh-commands.md`, which grew one block and the automation page shrank one.
+	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
+	{ path: 'docs/josh-commands-run.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands.md', bytes: 40_960 },
+	// joshuafolkken/kit#3279 moved the label sections here out of `docs/josh-commands-backlog.md`.
+	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },