@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -11,6 +11,11 @@ const DETAILS_TAIL_LENGTH = 2048
 const TRUNCATION_MARK = '... '
 // The prefix `backlog-drive-cli.ts` gives the exception it catches.
 const ERROR_PREFIX = 'error '
+// **The driver is bounded so the supervisor reaches its pass boundary between dispatches**
+// (joshuafolkken/kit#4509): unbounded, `backlog:drive` dispatches, collects and merges lanes in its own
+// loop until a judgment hand-off, and the code check at the pass boundary would wait for that.
+const WINDOW_MINUTES = '5'
+const WINDOW_VERDICT = 'window'
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 	const rebuilt = run_invocation.rebuild(invocation)
@@ -21,6 +26,8 @@ function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 		'backlog:drive',
 		'--owner',
 		String(process.pid),
+		'--window',
+		WINDOW_MINUTES,
 		...rebuilt.split(' ').slice(1 + named_count),
 	]
 }
@@ -141,11 +148,11 @@ function claim_record(target: string, invocation: string): boolean {
 }
 
 // **A verdict with nothing to judge is re-driven here, never handed to a session.** A woken session
-// met with `window`, `merge busy` or `merge retry` could only cut and hand the loop back for the same
-// driver to run again — a model round trip, at a cache write each, that decides nothing. The record
-// is already this process's, so the rerun needs no fresh claim; the limit keeps a driver that never
-// settles from holding the supervisor past its own checks.
-const RERUN_VERDICTS: ReadonlyArray<string> = ['window', 'merge busy', 'merge retry']
+// met with `merge busy` or `merge retry` could only cut and hand the loop back for the same driver to
+// run again — a model round trip, at a cache write each, that decides nothing. The record is already
+// this process's, so the rerun needs no fresh claim; the limit keeps a driver that never settles from
+// holding the supervisor past its own checks.
+const RERUN_VERDICTS: ReadonlyArray<string> = ['merge busy', 'merge retry']
 const RERUN_LIMIT = 10
 const RERUN_PAUSE_MS = 60_000
 
@@ -157,18 +164,21 @@ async function pause(ms: number): Promise<void> {
 	})
 }
 
-function is_mechanical(result: JoshResult): boolean {
+function is_verdict(result: JoshResult, entries: ReadonlyArray<string>): boolean {
 	const verdict = result.out.split('\n', 1)[FIRST_LINE] ?? ''
 
 	return (
 		result.code === SUCCESS &&
-		RERUN_VERDICTS.some((entry) => verdict === entry || verdict.startsWith(`${entry} `))
+		entries.some((entry) => verdict === entry || verdict.startsWith(`${entry} `))
 	)
 }
 
 // A record that was removed during the pause answers `undefined`: its stale verdict must not reach a
 // session, so the supervisor's own next pass re-reads the record and ends the run as `ended` or
 // `stopped`; a rerun would only fail on it and report the run as `failed`.
+//
+// **A spent window answers `undefined` too**, so the supervisor's next pass checks its code before it
+// drives again; the restarted driver adopts the lanes still in flight.
 async function run_driver(
 	target: string,
 	args: ReadonlyArray<string>,
@@ -176,7 +186,8 @@ async function run_driver(
 	remaining: number,
 ): Promise<JoshResult | undefined> {
 	const result = await josh_command.josh_run(args, true)
-	if (remaining === 0 || !is_mechanical(result)) return result
+	if (is_verdict(result, [WINDOW_VERDICT])) return undefined
+	if (remaining === 0 || !is_verdict(result, RERUN_VERDICTS)) return result
 
 	await wait(RERUN_PAUSE_MS)
 	if (run_carry.read_carry(target).kind !== 'carried') return undefined

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

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import type { CarryRead } from '#scripts/run/carry/run-carry'
 import {
 	run_wake,
@@ -22,8 +23,10 @@ import type { LaunchResult } from './run-wake-session'
 
 const STOPPED_REASON: WakeStopReason = 'stopped'
 const FAILED_REASON: WakeStopReason = 'failed'
+const RELOAD_REASON: WakeStopReason = 'reload'
 const NO_ATTEMPTS = 0
 const STOPPED_BY_PERSON: LoopStop = { reason: STOPPED_REASON, note: undefined }
+const CODE_CHANGED: LoopStop = { reason: RELOAD_REASON, note: undefined }
 
 interface LoopPorts {
 	// The carry record, re-read every pass rather than cached: it is written by the parent loop of a
@@ -47,10 +50,15 @@ interface LoopPorts {
 	wake: (invocation: string, session_id: string, material: string) => LaunchResult
 	sleep: (milliseconds: number) => Promise<void>
 	now: () => Date
+	// Closes again a lane a process outlived, once the process is gone (`lane_close.retry_closes`).
+	retry_closes: () => Promise<void>
+	// Whether the code this process loaded differs from the code on disk now (`run-wake-code.ts`).
+	is_code_stale: () => Promise<boolean>
 }
 
-// `released`: the carry record ended while the driver paused, so there is nothing to hand on and the
-// next pass decides from the record how the run ends.
+// `released`: the carry record ended while the driver paused, or the driver's window was spent, so
+// there is nothing to hand on and the next pass decides from the record whether the run ends, reloads
+// or drives on.
 type DriveResult =
 	| { kind: 'finished' }
 	| { kind: 'released' }
@@ -151,15 +159,37 @@ async function decide_pass(wake: RunWake, ports: LoopPorts): Promise<WakeDecisio
 	return run_wake.decide({ ...input, has_work: await ports.has_work(input.read) })
 }
 
+// A lane whose close a process outlived ends once the process is gone (joshuafolkken/kit#4300). A
+// failed retry is the next pass's to try again, never a reason to stop the run.
+async function retry_closes(ports: LoopPorts): Promise<void> {
+	try {
+		await ports.retry_closes()
+	} catch (error) {
+		error_text.trace_swallowed('run_wake_loop.retry_closes', error)
+	}
+}
+
 // The record is re-read at the top of every pass rather than carried in a variable, so a `--stop` that
 // removed it ends the loop at the next interval and a `--list` reads what the loop actually wrote.
 // One pass: decide, act, write the result back. `undefined` means carry on to the next interval.
+//
+// **A pass boundary is where the supervisor reloads its code** (joshuafolkken/kit#4509): no driver
+// is running and no session is being launched, so a successor on the new code takes over without
+// stopping any lane. A record already removed ends the loop before this pass is reached, and a carry
+// record that ended or became unreadable stops the run before the code is checked, so a reload never
+// hands a finished run to a successor.
 async function run_pass(
 	target: string,
 	wake: RunWake,
 	ports: LoopPorts,
 ): Promise<LoopStop | undefined> {
-	const outcome = await step(wake, await decide_pass(wake, ports), ports)
+	const decision = await decide_pass(wake, ports)
+
+	if (decision.kind !== 'stop' && (await ports.is_code_stale())) return CODE_CHANGED
+
+	await retry_closes(ports)
+
+	const outcome = await step(wake, decision, ports)
 
 	if (outcome.kind === 'stop') return outcome.stop
 
@@ -197,6 +227,7 @@ async function run_loop(target: string, ports: LoopPorts, interval_ms: number):
 
 const run_wake_loop = {
 	FAILED_REASON,
+	RELOAD_REASON,
 	run_loop,
 }
 

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

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_wake_cli } from './run-wake-cli'
+
+// The `josh run:wake` entry, and the script `--start` spawns with `--loop`. It is kept apart from
+// `run-wake-cli.ts` because `backlogrun-cli.ts` and `backlogrun-restart.ts` import 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
+
+	process.exitCode = await run_wake_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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,
 }