@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/run/wake/run-wake-ports.ts

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto'
+import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { lane_close } from '#scripts/lane/lane-close'
+import { poll } from '#scripts/lib/poll'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
+import { run_headless } from '#scripts/run/run-headless'
+import type { WakeContext } from './run-wake-describe'
+import { run_wake_driver } from './run-wake-driver'
+import { run_wake_handoff } from './run-wake-handoff'
+import type { LoopPorts } from './run-wake-loop'
+import { run_wake_session, type LaunchResult } from './run-wake-session'
+
+// The production ports of the supervisor's loop (`run-wake-loop.ts` → `LoopPorts`), and the session
+// launch they wake through.
+
+// **The note covers both ways `wake_argv` answers `undefined`**, because it cannot tell them apart and
+// a message that named only the first would accuse a legitimate invocation of carrying unsafe text.
+// The second is the one a person actually meets: a `queue` whose references carry a `owner/repo#`
+// prefix is a grammar this supervisor does not rebuild, and `queue.md` → "The session boundary" is why
+// such a queue begins no record in the first place.
+const UNSAFE_INVOCATION_NOTE =
+	'the carried invocation is not one this supervisor can continue — it is neither a backlogrun nor a queue it can rebuild, or it carries text that may not be passed to a command line'
+
+function note_to_stderr(note: string): void {
+	console.error(`wake: ${note}`)
+}
+
+// **A session that started is said on the stream.** The driver's `waiting on judgment` is the moment it
+// asked; from here a session is at work on the answer, until the supervisor's next hand-off.
+function say_session_running(context: WakeContext): void {
+	run_event_setup.emit_to(context.event_target, run_event_setup.STAGE.SESSION, new Date())
+}
+
+function wake_session(
+	context: WakeContext,
+	invocation: string,
+	profile: AgentProfile,
+	session: { id: string; material: string },
+): LaunchResult {
+	const built = run_wake_session.wake_argv(invocation, profile, context.worktree, session)
+
+	if (built === undefined) return { kind: 'failed', note: UNSAFE_INVOCATION_NOTE }
+	if (built.kind === 'rejected') return { kind: 'failed', note: built.note }
+
+	// The headless mark is what lets the stop hook hold this session's turn open while its lanes run —
+	// under `claude -p` a turn-end is the process's end (`run-headless.ts`).
+	const environment = run_headless.environment()
+	const target = { cwd: context.worktree, env: environment, log_path: context.log_target }
+	const result = run_wake_session.launch({ argv: built.argv, ...target, profile }, note_to_stderr)
+
+	if (result.kind === 'launched') say_session_running(context)
+
+	return result
+}
+
+// **A record this supervisor owns itself is not a session at work.** A failed driver leaves the record
+// adopted for this process, so reading that owner as live would have every restarted pass wait on
+// itself and never drive again.
+//
+// `is_code_stale` defaults to never: only the supervisor's own `--loop` watches its code
+// (`run-wake-code.ts`).
+function ports_for(
+	context: WakeContext,
+	profile: AgentProfile,
+	is_code_stale: () => Promise<boolean> = async () => false,
+): LoopPorts {
+	return {
+		is_code_stale,
+		read_carry: () => run_carry.read_carry(context.carry_target),
+		is_owner_live: (read) => read.kind === 'carried' && run_carry.is_held_by_another(read.carry),
+		has_work: async () => true,
+		new_session_id: () => randomUUID(),
+		hand_off: () => {
+			run_wake_handoff.hand_off(context.carry_target)
+		},
+		drive: async () => await run_wake_driver.drive(context.carry_target),
+		wake: (invocation, session_id, material) =>
+			wake_session(context, invocation, profile, { id: session_id, material }),
+		sleep: poll.sleep,
+		now: () => new Date(),
+		retry_closes: async () => {
+			await lane_close.retry_closes()
+		},
+	}
+}
+
+const run_wake_ports = { note_to_stderr, ports_for }
+
+export { run_wake_ports }

package/scripts/run/wake/run-wake-takeover.ts

@@ -0,0 +1,66 @@
+import { process_identity } from '#scripts/josh/process-identity'
+import { poll } from '#scripts/lib/poll'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { run_wake } from './run-wake'
+import { run_wake_stop } from './run-wake-stop'
+
+// Whether the successor a reload launched took the run over (joshuafolkken/kit#4509).
+//
+// **A spawn is not a take-over.** A successor that dies at load — a `main:sync` that pulled main but
+// whose reinstall failed — was still `launched`, and reading that as the hand-over would leave the run
+// with nobody watching it and nothing saying so. The successor claims the wake record before anything
+// else (`run-wake-await.ts`), so its pid on that record is the proof; its death, or no claim within the
+// bound, is a reload that failed.
+
+const TAKEOVER_INTERVAL_MS = MS_PER_SECOND
+// A cold `tsx` start claims within seconds; the bound is generous so a loaded machine is not a failure.
+const TAKEOVER_ATTEMPTS = 120
+
+type TakeoverResult = 'taken' | 'died' | 'unclaimed'
+
+interface TakeoverPorts {
+	holder_pid: () => number | undefined
+	is_alive: (pid: number) => boolean
+	stop: (pid: number) => void
+	sleeper?: (duration_ms: number) => Promise<void>
+}
+
+function ports_of(wake_target: string): TakeoverPorts {
+	return {
+		holder_pid: () => run_wake.read_wake(wake_target)?.pid,
+		is_alive: process_identity.is_live_pid,
+		stop: run_wake_stop.signal,
+	}
+}
+
+function result_of(pid: number, ports: TakeoverPorts): TakeoverResult {
+	if (ports.holder_pid() === pid) return 'taken'
+
+	return ports.is_alive(pid) ? 'unclaimed' : 'died'
+}
+
+// **A successor still unclaimed at the bound is stopped**, so the failed reload's warning says what is
+// true: left running, it would claim the run later and supervise one the warning and the board call
+// stranded.
+async function await_takeover(
+	pid: number,
+	ports: TakeoverPorts,
+	attempts: number = TAKEOVER_ATTEMPTS,
+): Promise<TakeoverResult> {
+	await poll.poll_until(async () => result_of(pid, ports) !== 'unclaimed', {
+		attempts,
+		interval_ms: TAKEOVER_INTERVAL_MS,
+		...(ports.sleeper && { sleeper: ports.sleeper }),
+	})
+
+	const result = result_of(pid, ports)
+
+	if (result === 'unclaimed') ports.stop(pid)
+
+	return result
+}
+
+const run_wake_takeover = { await_takeover, ports_of }
+
+export type { TakeoverPorts, TakeoverResult }
+export { run_wake_takeover }

package/scripts/run/wake/run-wake.ts

@@ -53,7 +53,8 @@ interface RunWake {
 	idle_since?: string | undefined
 }
 
-type WakeStopReason = 'ended' | 'unreadable' | 'failed' | 'stopped'
+// `reload`: the supervisor's code changed on disk, so it hands the run to a successor on that code.
+type WakeStopReason = 'ended' | 'unreadable' | 'failed' | 'stopped' | 'reload'
 
 // `superseded`: another supervisor holds the record and this process is the replaced one.
 type WakeTidyResult = 'absent' | 'removed' | 'superseded'

package/scripts/safe-chain/pack-hook.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, rmSync } from 'node:fs'
 import path from 'node:path'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { file_content } from '#scripts/sync/file-content'
 import { z } from 'zod'
@@ -14,7 +15,6 @@ import { z } from 'zod'
 // `pnpmfileChecksum`, which fails a frozen install until the lockfile is refreshed.
 const PACK_HOOK_FILE = '.pnpmfile.mjs'
 const MANAGED_LINE = '// josh-managed-pnpmfile: @joshuafolkken/kit'
-const MANIFEST_FILE = 'package.json'
 // pnpm loads `.pnpmfile.mjs` in preference to `.pnpmfile.cjs`, and neither once a `pnpmfile` setting
 // names another file — so writing ours beside either would silently drop the project's hooks, or
 // report a hook pnpm never runs.
@@ -77,7 +77,7 @@ const MESSAGES: Readonly<Record<PackHookResult, string | undefined>> = {
 }
 
 function sync_pack_hook(project_root: string, package_directory: string): PackHookResult {
-	const manifest_text = file_reader.read_optional(path.join(project_root, MANIFEST_FILE))
+	const manifest_text = file_reader.read_optional(package_manifest.manifest_path(project_root))
 	const is_private = manifest_text === undefined || !is_published(manifest_text)
 	const result = is_private ? 'private' : apply(project_root, package_directory)
 	const message = MESSAGES[result]

package/scripts/safe-chain/preinstall-command.ts

@@ -17,7 +17,8 @@ const INTEGRATION_HINT =
 const LOCAL_INTEGRATION_CHECK_SOURCE = `if(!process.env.CI&&!process.env.GLOBAL_AGENT_HTTP_PROXY)console.warn('${INTEGRATION_HINT}')`
 const SAFE_CHAIN_CMD = `node -e "${LOCAL_INTEGRATION_CHECK_SOURCE}"`
 // Every `preinstall` an earlier kit wrote: `setup-ci` alone, pinned or not, or followed by the
-// `node -e` check of any earlier wording.
+// `node -e` check of any earlier wording. Removable from kit 2.0.0; consumers still carried `setup-ci`
+// at joshuafolkken/kit#4187.
 const LEGACY_PREINSTALL_RE =
 	/^pnpm dlx @aikidosec\/safe-chain(?:@\S+)? setup-ci(?: && node -e "[^"]*")?$/u
 

package/scripts/safe-chain/project-config.ts

@@ -2,16 +2,14 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { file_reader } from '#scripts/lib/read-file'
 import { yaml_document } from '#scripts/lib/yaml-document'
-import { release_age } from '#scripts/version/release-age'
+import { release_window } from '#scripts/version/release-window'
 import { dump } from 'js-yaml'
-import { z } from 'zod'
 
 const WORKSPACE_FILE = 'pnpm-workspace.yaml'
 const PROJECT_CONFIG_FILE = '.aikido'
 const EXCLUSIONS_FIELD = 'minimumPackageAgeExclusions'
 const AGE_FIELD = 'minimumPackageAgeHours'
 const MINUTES_PER_HOUR = 60
-const workspace_schema = z.object({ minimumReleaseAgeExclude: z.array(z.string()).optional() })
 
 function read_mapping(value: unknown, label: string): Record<string, unknown> {
 	if (value === undefined) return {}
@@ -82,7 +80,7 @@ function replace_safe_chain_block(existing: string, safe_chain: Record<string, u
 // undeclared window writes nothing; an explicit `0` opt-out is written as 0 so an earlier
 // synchronized age cannot outlive it.
 function package_age_hours(workspace: string): number | undefined {
-	const minutes = release_age.parse_declared_minimum_release_age(workspace)
+	const { minutes } = release_window.parse_release_window(workspace)
 	if (minutes === undefined) return undefined
 
 	return Math.floor(minutes / MINUTES_PER_HOUR)
@@ -117,12 +115,8 @@ function has_nothing_to_write(
 	)
 }
 
-function read_exclusions(workspace: string): ReadonlyArray<string> {
-	return workspace_schema.parse(yaml_document.parse_yaml(workspace)).minimumReleaseAgeExclude ?? []
-}
-
 function merge_project_config(existing: string, workspace: string): string {
-	const exclusions = read_exclusions(workspace)
+	const { exclusions } = release_window.parse_release_window(workspace)
 	const aikido = yaml_document.parse_yaml(existing)
 	const safe_chain = read_mapping(aikido['safe-chain'], 'safe-chain')
 	const merged = merge_age(merge_exclusions(safe_chain, exclusions), workspace)

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,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+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).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	await security_audit_provision.run(process.argv.slice(ARGV_OFFSET))
+}

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 {
@@ -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,6 +1,4 @@
-#!/usr/bin/env tsx
 import { accessSync, constants, statSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { execaSync } from 'execa'
 import { security_audit_logic } from './security-audit-logic'
@@ -115,27 +113,28 @@ 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,
 	meets_floor,
 	resolve_scanner,
+	run,
 	run_scanner,
 }
 

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

@@ -107,12 +107,27 @@ function reason(measurement: SizeMeasurement): string {
 	return `${counted} (${guide}) — ${tail}`
 }
 
+// The `split-assessment.md` heading the notice points at; the document-rule test pins the document to it.
+const NOTICE_SECTION = 'Over the guide before the gate'
+const NOTICE_ACTION = `record why it stays one Issue, or carve the rest out into a new Issue — 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,
 	SPLIT_VERDICT,
 	SINGLE_VERDICT,
 	assess,
+	notice,
 	parse_numstat,
 	reason,
 }

package/scripts/split/split-measure.ts

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+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.
+
+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 read_branch(): Promise<ReturnType<typeof split_assess.assess>> {
+	const tracked = await git_command.diff_main_numstat()
+
+	return split_assess.assess(`${tracked}${NEWLINE}${await untracked_numstat()}`)
+}
+
+const split_measure = { line_count, read_branch }
+
+export { split_measure }

package/scripts/sync/claude-settings-merge.ts

@@ -1,5 +1,6 @@
 import { json_format } from '#scripts/config-merge/json-format'
 import { hook_command_rewrite } from '#scripts/init/hook-command-rewrite'
+import { json_value } from '#scripts/lib/json-value'
 
 // `josh sync` used to replace a project's `.claude/settings.json` with the distributed file, which
 // deleted every hook and permission the project had added — and `.claude/settings.local.json` is
@@ -29,10 +30,6 @@ const WITHDRAWN_KIT_PERMISSIONS: ReadonlySet<unknown> = new Set([
 	'Bash(git commit --all*)',
 ])
 
-function is_json_object(value: unknown): value is JsonObject {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 function as_array(value: unknown): Array<unknown> {
 	return Array.isArray(value) ? value : []
 }
@@ -46,7 +43,7 @@ function merge_objects(kit: JsonObject, own: JsonObject, merge_entry: EntryMerge
 }
 
 function merge_kit_value(kit: unknown, own: unknown): unknown {
-	if (!is_json_object(kit) || !is_json_object(own)) return kit
+	if (!json_value.is_record(kit) || !json_value.is_record(own)) return kit
 
 	return merge_objects(kit, own, (_key, kit_entry, own_entry) =>
 		merge_kit_value(kit_entry, own_entry),
@@ -68,7 +65,7 @@ function without_withdrawn(value: unknown): unknown {
 // The withdrawn entries are taken out of every list first, so one goes even when kit no longer ships
 // the list it sat in.
 function merge_permissions(kit: unknown, own: unknown): unknown {
-	if (!is_json_object(kit) || !is_json_object(own)) return kit
+	if (!json_value.is_record(kit) || !json_value.is_record(own)) return kit
 	const kept = Object.entries(own).map(([key, value]) => [key, without_withdrawn(value)] as const)
 
 	return merge_objects(kit, Object.fromEntries(kept), (_key, kit_entry, own_entry) =>
@@ -77,7 +74,7 @@ function merge_permissions(kit: unknown, own: unknown): unknown {
 }
 
 function is_kit_handler(handler: unknown): boolean {
-	if (!is_json_object(handler)) return false
+	if (!json_value.is_record(handler)) return false
 	const { command } = handler
 
 	return typeof command === 'string' && hook_command_rewrite.is_kit_hook_command(command)
@@ -85,7 +82,7 @@ function is_kit_handler(handler: unknown): boolean {
 
 // A matcher group left with no handler of the project's own was kit's alone, and goes with them.
 function without_kit_handlers(group: unknown): unknown {
-	if (!is_json_object(group)) return group
+	if (!json_value.is_record(group)) return group
 	const handlers = as_array(group[HOOKS_KEY]).filter((handler) => !is_kit_handler(handler))
 
 	return handlers.length === 0 ? undefined : { ...group, [HOOKS_KEY]: handlers }
@@ -104,7 +101,7 @@ function own_hook_events(own: JsonObject): JsonObject {
 }
 
 function merge_hooks(kit: unknown, own: unknown): unknown {
-	if (!is_json_object(kit) || !is_json_object(own)) return kit
+	if (!json_value.is_record(kit) || !json_value.is_record(own)) return kit
 
 	return merge_objects(kit, own_hook_events(own), (_event, kit_groups, groups) => [
 		...as_array(kit_groups),
@@ -120,13 +117,9 @@ function merge_top_level(key: string, kit: unknown, own: unknown): unknown {
 }
 
 function parse_object(content: string): JsonObject | undefined {
-	try {
-		const parsed: unknown = JSON.parse(content)
+	const parsed = json_value.parse_or_undefined(content)
 
-		return is_json_object(parsed) ? parsed : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.is_record(parsed) ? parsed : undefined
 }
 
 // A file that does not parse as a JSON object has nothing the merge can keep, so it is replaced with