@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/security/secretlint-scan.ts

@@ -7,7 +7,11 @@ import { execaSync } from 'execa'
 
 const SECRETLINT_BIN = 'secretlint'
 const NO_GLOB_FLAG = '--no-glob'
+const END_OF_OPTIONS = '--'
 const ARGV_OFFSET = 2
+// Set by the CI `Secret Scan` job, where nothing provisions the binary later: there a missing
+// secretlint would turn the scan into a silent pass, so it fails instead (kit#4657).
+const REQUIRE_ENV = 'JOSH_SECRETLINT_REQUIRE'
 
 // The scan is defense in depth ahead of GitHub push protection, not the only gate, so a
 // missing binary must not block the commit. kit ships the pre-commit rule inside
@@ -21,7 +25,14 @@ const MISSING_NOTICE =
 	`   The kit pre-commit hook ships ahead of the dependency it needs.\n` +
 	`   Run \`pnpm josh sync && pnpm install\` to provision it.`
 
-type ScanDecision = { kind: 'skip'; notice?: string } | { kind: 'scan'; binary: string }
+const REQUIRED_MISSING_ERROR =
+	`❌ secretlint is not installed, and ${REQUIRE_ENV} requires the scan.\n` +
+	`   Add it to the devDependencies with \`pnpm josh sync && pnpm install\`.`
+
+type ScanDecision =
+	| { kind: 'skip'; notice?: string }
+	| { kind: 'fail'; error: string }
+	| { kind: 'scan'; binary: string }
 
 function resolve_secretlint_binary(project_root: string): string | undefined {
 	const candidate = resolve_local_bin(project_root, SECRETLINT_BIN)
@@ -31,17 +42,28 @@ function resolve_secretlint_binary(project_root: string): string | undefined {
 
 // lefthook substitutes literal paths, so `--no-glob` is mandatory: a SvelteKit route directory
 // such as `(app)` or `[id]` would otherwise reach secretlint's glob engine as a pattern.
-// Masking and the .gitignore cascade are both on by default in v13 — no flag adds them.
+// Masking and the .gitignore cascade are both on by default in v13 — no flag adds them. `--` ends
+// the options, so a staged file named like `--secretlintrc=evil.json` stays a path, not a flag.
 function build_scan_arguments(staged_files: ReadonlyArray<string>): Array<string> {
-	return [NO_GLOB_FLAG, ...staged_files]
+	return [NO_GLOB_FLAG, END_OF_OPTIONS, ...staged_files]
+}
+
+function plan_missing(is_required: boolean): ScanDecision {
+	return is_required
+		? { kind: 'fail', error: REQUIRED_MISSING_ERROR }
+		: { kind: 'skip', notice: MISSING_NOTICE }
 }
 
-function plan_scan(staged_files: ReadonlyArray<string>, project_root: string): ScanDecision {
+function plan_scan(
+	staged_files: ReadonlyArray<string>,
+	project_root: string,
+	is_required = false,
+): ScanDecision {
 	if (staged_files.length === 0) return { kind: 'skip' }
 
 	const binary = resolve_secretlint_binary(project_root)
 
-	if (binary === undefined) return { kind: 'skip', notice: MISSING_NOTICE }
+	if (binary === undefined) return plan_missing(is_required)
 
 	return { kind: 'scan', binary }
 }
@@ -59,18 +81,29 @@ function run_scan(binary: string, staged_files: ReadonlyArray<string>): number {
 	return resolve_spawn_exit(binary, result)
 }
 
-function main(staged_files: ReadonlyArray<string>, project_root: string): number {
-	const decision = plan_scan(staged_files, project_root)
+function main(
+	staged_files: ReadonlyArray<string>,
+	project_root: string,
+	is_required = false,
+): number {
+	const decision = plan_scan(staged_files, project_root, is_required)
 
 	if (decision.kind === 'scan') return run_scan(decision.binary, staged_files)
 
+	if (decision.kind === 'fail') {
+		console.error(decision.error)
+
+		return 1
+	}
+
 	if (decision.notice !== undefined) console.warn(decision.notice)
 
 	return 0
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	const exit_code = main(process.argv.slice(ARGV_OFFSET), process.cwd())
+	const is_required = process.env[REQUIRE_ENV] === '1'
+	const exit_code = main(process.argv.slice(ARGV_OFFSET), process.cwd(), is_required)
 
 	if (exit_code !== 0) process.exit(exit_code)
 }
@@ -83,4 +116,4 @@ const secretlint_scan = {
 	run_scan,
 }
 
-export { MISSING_NOTICE, secretlint_scan }
+export { MISSING_NOTICE, REQUIRE_ENV, REQUIRED_MISSING_ERROR, secretlint_scan }

package/scripts/security/security-audit-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { security_audit } from './security-audit'
+
+// The `josh audit` entry, kept apart from `security-audit.ts` because `start-steps.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). The audit takes no arguments.
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = security_audit.run()

package/scripts/security/security-audit-provision-logic.ts

@@ -14,7 +14,6 @@ const RELEASE_BASE_URL = 'https://github.com/google/osv-scanner/releases/downloa
 
 const WINDOWS_PLATFORM = 'win32'
 const WINDOWS_ASSET_SUFFIX = '.exe'
-const STAGING_SUFFIX = '.download'
 
 // The asset is ~55 MB, and a link delivering it at 300 KB/s — measured, not hypothetical — takes
 // over three minutes. A `SessionStart` hook is waited on, so a single bound generous enough to
@@ -91,15 +90,6 @@ function build_download_url(asset_name: string): string {
 	return `${RELEASE_BASE_URL}/v${SCANNER_VERSION}/${asset_name}`
 }
 
-// The staging file the download is written to before it is renamed onto the target. The process id
-// is what keeps two sessions of one project apart — the `SessionStart` matcher is empty, so a
-// `clear` during a startup's download is exactly that — and without it their writes interleave into
-// one file that both then rename into place, which the checksum cannot catch because each verified
-// its own buffer.
-function build_staging_path(target_path: string, process_id: number): string {
-	return `${target_path}.${String(process_id)}${STAGING_SUFFIX}`
-}
-
 // The whole "where do we fetch from" decision in one pure call, so the table above is testable
 // without a network round trip — which the unit suite forbids anyway (`test-network-guard.ts`).
 function resolve_asset(platform: string, architecture: string): ScannerAsset | undefined {
@@ -198,7 +188,6 @@ const security_audit_provision_logic = {
 	build_asset_name,
 	build_download_timeout,
 	build_download_url,
-	build_staging_path,
 	format_already_present,
 	format_below_floor,
 	format_checksum_mismatch,

package/scripts/security/security-audit-provision-main.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { session_owner_pin } from '#scripts/discovery/session-owner-pin'
+import { security_audit_provision } from './security-audit-provision'
+
+// The `josh audit:provision` entry and the session-start hook's bundle, kept apart from
+// `security-audit-provision.ts` because `start-steps.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).
+//
+// Run by the session-start hook (`--session-start`), it also pins the session's owner
+// (`session-owner-pin.ts`) at no spawn of its own. A manual `josh audit:provision` pins only when
+// passed `--session-start`, which re-pins to whatever owner `origin` names at that moment.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+	const SESSION_START_FLAG = '--session-start'
+	const argv = process.argv.slice(ARGV_OFFSET)
+
+	if (argv.includes(SESSION_START_FLAG)) session_owner_pin.pin()
+	await security_audit_provision.run(argv)
+}

package/scripts/security/security-audit-provision.ts

@@ -1,9 +1,6 @@
-#!/usr/bin/env tsx
-import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { atomic_write } from '#scripts/lib/atomic-write'
 import { error_text } from '#scripts/lib/error-message'
 import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { security_audit } from './security-audit'
@@ -43,24 +40,14 @@ async function download(url: string, timeout_ms: number): Promise<DownloadOutcom
 	}
 }
 
-// Staged beside the target and renamed onto it, under a name carrying this process's id. A download
-// interrupted halfway would otherwise leave a truncated file at the path `josh audit` spawns; and a
-// shared staging name would let two sessions of the same project — the `SessionStart` matcher is
-// empty, so a `clear` during a startup's download is exactly that — interleave their writes into one
-// file that both then rename into place, which the checksum cannot catch because it was verified
-// against each process's own buffer. The `finally` removes the staging file on every failing path.
+// Staged beside the target and renamed onto it (`atomic-write.ts`). A download interrupted halfway
+// would otherwise leave a truncated file at the path `josh audit` spawns; and a shared staging name
+// would let two sessions of the same project — the `SessionStart` matcher is empty, so a `clear`
+// during a startup's download is exactly that — interleave their writes into one file that both then
+// rename into place, which the checksum cannot catch because it was verified against each process's
+// own buffer.
 function install(target_path: string, content: Buffer): void {
-	const staging_path = security_audit_provision_logic.build_staging_path(target_path, process.pid)
-
-	mkdirSync(path.dirname(target_path), { recursive: true })
-
-	try {
-		writeFileSync(staging_path, content)
-		chmodSync(staging_path, EXECUTABLE_MODE)
-		renameSync(staging_path, target_path)
-	} finally {
-		rmSync(staging_path, { force: true })
-	}
+	atomic_write.replace_file(target_path, content, { mode: EXECUTABLE_MODE })
 }
 
 function failure_stamp_path(target_path: string): string {
@@ -153,7 +140,7 @@ async function report(
 	is_forced: boolean,
 ): Promise<string> {
 	const logic = security_audit_provision_logic
-	const target_path = security_audit_logic.build_managed_binary_path(project_root, platform)
+	const target_path = security_audit.managed_binary_path(project_root, platform)
 	const existing = existing_scanner(target_path)
 	if (existing !== undefined) return logic.format_already_present(existing)
 
@@ -167,8 +154,8 @@ async function report(
 // Every failure is a printed line and a zero exit, deliberately: this runs at session start, and a
 // non-zero exit there would take an agent's whole session away over a tool it does not need yet.
 // The audit's own gate is unchanged — a scanner that never arrived still fails the pre-push run.
-async function main(): Promise<void> {
-	const is_forced = process.argv.includes(FORCE_FLAG)
+async function run(argv: ReadonlyArray<string>): Promise<void> {
+	const is_forced = argv.includes(FORCE_FLAG)
 
 	try {
 		console.info(await report(PROJECT_ROOT, process.platform, process.arch, is_forced))
@@ -179,8 +166,6 @@ async function main(): Promise<void> {
 	}
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-const security_audit_provision = { attempt, provision, report }
+const security_audit_provision = { attempt, provision, report, run }
 
 export { security_audit_provision }

package/scripts/security/security-audit.ts

@@ -1,12 +1,13 @@
-#!/usr/bin/env tsx
 import { accessSync, constants, statSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { execaSync } from 'execa'
 import { security_audit_logic } from './security-audit-logic'
 import { security_audit_provision_logic } from './security-audit-provision-logic'
 
 const FAILURE_EXIT_CODE = 1
+const GIT_DIRECTORY_NAME = '.git'
 const UNKNOWN_VERSION = 'unknown'
 
 // execa reports `exitCode: undefined` only when the binary could not be spawned
@@ -58,11 +59,27 @@ interface ScannerChoice {
 	is_below_floor: boolean
 }
 
+// A linked work tree shares the primary checkout's managed scanner, so a lane neither downloads its
+// own copy at every session start nor keeps its own no-retry record (joshuafolkken/kit#4942). Where
+// the primary checkout cannot be named — a bare repository, a submodule, or no repository — the root
+// is the project's own. The primary checkout reads git's answer too, so it keys the no-retry record
+// on the same real path its lanes do even when it was entered through a symlink.
+function managed_root(project_root: string): string {
+	const common = git_common_directory.repository(project_root)
+	if (common === undefined || path.basename(common) !== GIT_DIRECTORY_NAME) return project_root
+
+	return path.dirname(common)
+}
+
+function managed_binary_path(project_root: string, platform: string): string {
+	return security_audit_logic.build_managed_binary_path(managed_root(project_root), platform)
+}
+
 // A provisioned copy counts only when it is both a real executable and at or above the floor: a
 // leftover from an earlier pinned version would otherwise be preferred over the PATH binary while
 // reading less of the lockfile than it should.
 function managed_scanner(project_root: string, platform: string): string | undefined {
-	const managed_path = security_audit_logic.build_managed_binary_path(project_root, platform)
+	const managed_path = managed_binary_path(project_root, platform)
 
 	return is_executable_file(managed_path) && meets_floor(managed_path) ? managed_path : undefined
 }
@@ -115,27 +132,29 @@ function warn_below_floor(scanner_path: string): void {
 	console.warn(security_audit_provision_logic.format_below_floor(version))
 }
 
-function main(): never {
+// The `josh audit` run: the scanner's exit code, or a failure when there is no scanner at all.
+function run(): number {
 	const { BINARY_NAME, format_missing_binary_error } = security_audit_logic
 	const choice = resolve_scanner(PROJECT_ROOT, process.platform)
 
 	if (choice === undefined) {
 		console.error(format_missing_binary_error(BINARY_NAME))
-		process.exit(FAILURE_EXIT_CODE)
+
+		return FAILURE_EXIT_CODE
 	}
 
 	if (choice.is_below_floor) warn_below_floor(choice.path)
 
-	process.exit(run_scanner(choice.path))
+	return run_scanner(choice.path)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
-
 const security_audit = {
 	is_binary_available,
 	is_executable_file,
+	managed_binary_path,
 	meets_floor,
 	resolve_scanner,
+	run,
 	run_scanner,
 }
 

package/scripts/security/sonar-file.ts

@@ -1,7 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
 import { init_logic } from '#scripts/init/init-logic'
 import type { SonarIdentifiers } from '#scripts/init/init-logic-sonar'
+import { file_content } from '#scripts/sync/file-content'
+
+// Written through `write_contained` like every other sync write, so a `sonar-project.properties`
+// linked outside the project is refused rather than written through (joshuafolkken/kit#4634).
 
 function write_sonar_file(
 	template_source: string,
@@ -14,8 +17,7 @@ function write_sonar_file(
 		identifiers.organization,
 	)
 
-	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, content)
+	file_content.write_contained(destination_path, content)
 }
 
 function merge_sonar_file(
@@ -36,7 +38,10 @@ function merge_sonar_file(
 	)
 	const existing = readFileSync(destination_path, 'utf8')
 
-	writeFileSync(destination_path, init_logic.merge_sonar_properties(existing, template_content))
+	file_content.write_contained(
+		destination_path,
+		init_logic.merge_sonar_properties(existing, template_content),
+	)
 }
 
 const sonar_file = { write_sonar_file, merge_sonar_file }

package/scripts/self-sync-guard/self-sync-guard-logic.ts

@@ -1,5 +1,6 @@
-import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import { package_manifest } from '#scripts/lib/package-manifest'
+import { z } from 'zod'
 
 // `josh sync` / `josh-app sync` / `josh-game sync` all copy a distribution package's files into a
 // consumer project. Run inside the package's OWN repository the direction reverses: the source of
@@ -12,20 +13,12 @@ import path from 'node:path'
 // The check lives here rather than in each package's sync so the three distributors share one
 // implementation: a second copy would drift, and a distributor that spelled the signal differently
 // would keep exactly the hole this closes.
-const MANIFEST_NAME = 'package.json'
+const named_manifest_schema = z.object({ name: z.string() })
 
+// A missing, unreadable or malformed manifest says nothing about self-sync, and refusing to sync on
+// it would break consumers whose manifest this package is about to create.
 function read_package_name(directory: string): string | undefined {
-	try {
-		const manifest: unknown = JSON.parse(readFileSync(path.join(directory, MANIFEST_NAME), 'utf8'))
-		if (typeof manifest !== 'object' || manifest === null) return undefined
-		const { name } = manifest as { name?: unknown }
-
-		return typeof name === 'string' ? name : undefined
-	} catch {
-		// A missing, unreadable or malformed manifest says nothing about self-sync, and refusing to
-		// sync on it would break consumers whose manifest this package is about to create.
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(directory, named_manifest_schema)?.name
 }
 
 function is_same_directory(first: string, second: string): boolean {

package/scripts/split/split-assess-cli.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { git_command } from '#scripts/git/git-command'
 import { path_decision } from '#scripts/josh/path-decision'
 import { split_assess } from './split-assess'
+import { split_measure } from './split-measure'
 
 // `josh split:assess` — measure a branch's change size, tests excluded, and answer the size question
 // of the split assessment.
@@ -33,7 +33,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	const measurement = split_assess.assess(await git_command.diff_main_numstat())
+	const measurement = await split_measure.read_branch()
 	const reason = split_assess.reason(measurement)
 
 	path_decision.print_decision(JSON_KEY, measurement.verdict, reason, is_json)

package/scripts/split/split-assess.ts

@@ -76,7 +76,8 @@ function non_test_changes(changes: ReadonlyArray<FileChange>): Array<FileChange>
 }
 
 // `split` only when **both** guides are exceeded together — the size condition a split has to clear,
-// per `split-assessment.md`'s conservative default. Either one alone leaves the change one Issue.
+// per `split-assessment.md`'s conservative default. Either one alone leaves the change one Issue. A
+// filing's declared estimate is judged by this same call (`issue/size-estimate.ts`).
 function verdict_for(files: number, lines: number): SplitVerdict {
 	return files > FILE_GUIDE && lines > LINE_GUIDE ? SPLIT_VERDICT : SINGLE_VERDICT
 }
@@ -107,14 +108,37 @@ function reason(measurement: SizeMeasurement): string {
 	return `${counted} (${guide}) — ${tail}`
 }
 
+// The `split-assessment.md` headings the notice and a filing refusal point at; the document-rule test
+// pins the document to both.
+const NOTICE_SECTION = 'Over the guide before the gate'
+const QUESTION_SECTION = 'The question'
+// The line that records why an Issue stays one — read the same in a filed body (`size_estimate`) and
+// in the Issue comment that answers the notice (`split_resolution`).
+const REASON_PREFIX = '- 分割しない理由:'
+const NOTICE_ACTION = `record why it stays one Issue in an Issue comment line \`${REASON_PREFIX} <理由>\`, or carve the rest out with \`pnpm josh issue:file --route split\` — split-assessment.md → "${NOTICE_SECTION}"`
+
+// The pre-gate notice `josh main:merge` prints for a diff over the guide. "Clearly" is the `split`
+// verdict — both guides exceeded — so the one bar this file draws is the one the notice fires on,
+// and a diff under it prints nothing.
+function notice(measurement: SizeMeasurement): string | undefined {
+	if (measurement.verdict !== SPLIT_VERDICT) return undefined
+
+	return `split notice: ${reason(measurement)}. Before the run:cut, ${NOTICE_ACTION}`
+}
+
 const split_assess = {
 	FILE_GUIDE,
 	LINE_GUIDE,
+	NOTICE_SECTION,
+	QUESTION_SECTION,
+	REASON_PREFIX,
 	SPLIT_VERDICT,
 	SINGLE_VERDICT,
 	assess,
+	notice,
 	parse_numstat,
 	reason,
+	verdict_for,
 }
 
 export type { FileChange, SizeMeasurement, SplitVerdict }

package/scripts/split/split-early-notice.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { split_assess, type SizeMeasurement } from './split-assess'
+import { split_measure } from './split-measure'
+
+// **The split notice, shown mid-implementation** (joshuafolkken/kit#4642). `josh main:merge` prints it
+// only before the gate, when the run can no longer carve anything out; a lane that grew to 17 files met
+// it 25 minutes in. The first `josh lint:related` or `josh test:related` after the branch's diff passes
+// the guide prints the same notice — `split_assess.notice`, so the bar and the question are one
+// definition — once per Issue: a marker in the work tree's git directory, created exclusively, records
+// that it was shown. A diff under the guide leaves no marker, so the first crossing still prints.
+// Advisory only: an unmeasurable diff or a branch with no Issue prints nothing.
+
+const MARKER_PREFIX = 'josh-split-notice-'
+const EXISTS_CODE = 'EEXIST'
+
+async function marker_path(issue_number: number): Promise<string | undefined> {
+	const [git_directory] = await git_command.git_directories()
+
+	if (git_directory === undefined) return undefined
+
+	return path.join(git_directory, `${MARKER_PREFIX}${String(issue_number)}`)
+}
+
+// Undefined once shown, so a later run skips the measurement — a diff against main and a read of
+// every untracked file.
+async function unclaimed_marker(issue_number: number): Promise<string | undefined> {
+	const target = await marker_path(issue_number)
+
+	return target === undefined || existsSync(target) ? undefined : target
+}
+
+function is_exists_error(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === EXISTS_CODE
+}
+
+// True only for the call that created the marker — the one that shows the notice.
+async function claim(target: string): Promise<boolean> {
+	try {
+		await writeFile(target, '', { flag: 'wx' })
+
+		return true
+	} catch (error) {
+		if (is_exists_error(error)) return false
+		throw error
+	}
+}
+
+// The claim that shows the notice first also writes it to the lane ledger, so the ledger holds one
+// line per Issue, whichever command showed it (joshuafolkken/kit#4695).
+async function claim_notice(
+	target: string,
+	issue: number,
+	measurement: SizeMeasurement,
+): Promise<boolean> {
+	if (!(await claim(target))) return false
+	await lane_ledger_write.record_split_notice({
+		issue,
+		files: measurement.files,
+		lines: measurement.lines,
+	})
+
+	return true
+}
+
+async function branch_issue(): Promise<number | undefined> {
+	return git_branch.issue_from_branch(await git_command.branch())
+}
+
+async function pending_notice(): Promise<string | undefined> {
+	const issue_number = await branch_issue()
+
+	if (issue_number === undefined) return undefined
+	const target = await unclaimed_marker(issue_number)
+
+	if (target === undefined) return undefined
+	const measurement = await split_measure.read_branch()
+	const notice = split_assess.notice(measurement)
+
+	return notice !== undefined && (await claim_notice(target, issue_number, measurement))
+		? notice
+		: undefined
+}
+
+// `josh main:merge` prints its notice on every merge; this records the first showing, as the scoped
+// checks do, when neither of them showed it before. Advisory, as `surface` is.
+async function record(measurement: SizeMeasurement): Promise<void> {
+	try {
+		const issue_number = await branch_issue()
+		const target = issue_number === undefined ? undefined : await unclaimed_marker(issue_number)
+
+		if (issue_number !== undefined && target !== undefined) {
+			await claim_notice(target, issue_number, measurement)
+		}
+	} catch {
+		// Advisory: the notice was printed; only its record is lost.
+	}
+}
+
+async function surface(): Promise<void> {
+	try {
+		const notice = await pending_notice()
+
+		if (notice !== undefined) console.warn(`\n${notice}`)
+	} catch {
+		// Advisory: `josh main:merge` reports an unmeasurable diff before the gate.
+	}
+}
+
+const split_early_notice = { MARKER_PREFIX, record, surface }
+
+export { split_early_notice }

package/scripts/split/split-measure.ts

@@ -0,0 +1,83 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { change_base } from '#scripts/git/change-base'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_command } from '#scripts/git/git-command'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { split_assess } from './split-assess'
+
+// The branch's size measurement — the one reading every `split_assess` caller takes.
+//
+// joshuafolkken/kit#4302: `git diff` never lists an untracked file, and a run has staged nothing
+// when it measures, so the diff alone counted every new file a branch created as absent. Each
+// untracked file is added as a numstat row of its line count, so a branch made of new modules
+// measures as large as it is. A file holding a NUL byte is binary and counts zero lines, as
+// `git diff --numstat` counts it. An entry with no readable content — a dangling symlink, a nested
+// repository's directory — still counts as a file, of zero lines, so one such entry cannot reject
+// the whole measurement.
+//
+// joshuafolkken/kit#4696: **the tracked half is measured from the tree's base, through a merge in
+// progress** (`change_base.resolved_through_merge`). A merge of the default branch stopped on a
+// conflict has already put the default branch's files in the work tree while `HEAD` is still the
+// commit before it, so measuring from `HEAD`'s merge-base counted everything the merge brought in as
+// this branch's own — 53 files where the branch had 10. A base that cannot be resolved throws, so no
+// caller reads it as under the guide: the notices report the diff as unmeasured and `split:assess`
+// fails outright.
+
+const UNRESOLVED_BASE = 'the change base could not be resolved'
+const NUL_BYTE = 0
+const NO_CONTENT = Buffer.alloc(0)
+const NEWLINE = '\n'
+
+function line_count(content: Buffer): number {
+	if (content.includes(NUL_BYTE)) return 0
+
+	const text = content.toString('utf8')
+	const newlines = text.split(NEWLINE).length - 1
+
+	return text === '' || text.endsWith(NEWLINE) ? newlines : newlines + 1
+}
+
+async function read_content(file_path: string): Promise<Buffer> {
+	try {
+		return await readFile(file_path)
+	} catch {
+		return NO_CONTENT
+	}
+}
+
+async function untracked_row(root: string, file: string): Promise<string> {
+	const lines = line_count(await read_content(path.join(root, file)))
+
+	return `${String(lines)}\t0\t${file}`
+}
+
+async function untracked_numstat(): Promise<string> {
+	const files = changed_paths.to_paths(await git_command.untracked_names())
+
+	if (files.length === 0) return ''
+
+	const toplevel = await git_spawn.read(['rev-parse', '--show-toplevel'])
+	const root = toplevel.trim()
+	const rows = await Promise.all(files.map(async (file) => await untracked_row(root, file)))
+
+	return rows.join(NEWLINE)
+}
+
+async function tracked_numstat(): Promise<string> {
+	const base = await change_base.resolved_through_merge()
+
+	if (base === undefined) throw new Error(UNRESOLVED_BASE)
+
+	return await git_command.diff_numstat_since(base)
+}
+
+async function read_branch(): Promise<ReturnType<typeof split_assess.assess>> {
+	const tracked = await tracked_numstat()
+
+	return split_assess.assess(`${tracked}${NEWLINE}${await untracked_numstat()}`)
+}
+
+const split_measure = { line_count, read_branch }
+
+export { split_measure }