@recombine-ai/bosun 0.16.2 → 0.17.1

package/bin/git-mode.js

@@ -0,0 +1,1139 @@
+// @ts-check
+import { randomUUID } from 'crypto'
+import {
+	existsSync,
+	linkSync,
+	lstatSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	rmSync,
+	unlinkSync,
+	writeFileSync
+} from 'fs'
+import { platform, tmpdir } from 'os'
+import { basename, dirname, join, resolve } from 'path'
+import { spawnSync } from 'child_process'
+
+export const GIT_ACTIVATION_RESTART_EXIT_CODE = 76
+
+const DEFAULT_ACTIVATION_IDLE_MINUTES = 10
+const REPOSITORY_LEASE_VERSION = 3
+const REPOSITORY_LEASE_FILENAME = 'bosun-launcher.lease.json'
+const GIT_MODE_ENV_NAMES = [
+	'BOSUN_GIT_MODE',
+	'BOSUN_CURRENT_BRANCH',
+	'BOSUN_PERSONAL_BRANCH',
+	'BOSUN_GIT_ACTIVATION_IDLE_MINUTES',
+	'BOSUN_GIT_ACTIVATION_IDLE_MS',
+	'BOSUN_GIT_REPOSITORY_ROOT',
+	'BOSUN_GIT_PERSONAL_UPSTREAM',
+	'BOSUN_GIT_PERSONAL_UPSTREAM_REMOTE',
+	'BOSUN_GIT_PERSONAL_UPSTREAM_BRANCH',
+	'BOSUN_GIT_UPSTREAM',
+	'BOSUN_GIT_UPSTREAM_REMOTE',
+	'BOSUN_GIT_UPSTREAM_BRANCH',
+	'BOSUN_GIT_CURRENT_UPSTREAM',
+	'BOSUN_GIT_CURRENT_UPSTREAM_REMOTE',
+	'BOSUN_GIT_CURRENT_UPSTREAM_BRANCH',
+	'BOSUN_GIT_LAUNCH_ID',
+	'BOSUN_GIT_RUNTIME_STATE_PATH',
+	'BOSUN_GIT_COMMAND_STATE_PATH',
+	'BOSUN_GIT_LEASE_ID',
+	'BOSUN_GIT_ACTIVATION_RESTART_EXIT_CODE',
+	'BOSUN_SHUTDOWN_ACK_PATH',
+	'BOSUN_SHUTDOWN_ACK_TOKEN'
+]
+
+// These variables can redirect an otherwise ordinary `git` command away from cwd. Git mode owns
+// the validated repository root, so neither a parent shell nor the project .env may override it.
+const GIT_REPOSITORY_ENV_NAMES = [
+	'GIT_DIR',
+	'GIT_WORK_TREE',
+	'GIT_COMMON_DIR',
+	'GIT_INDEX_FILE',
+	'GIT_OBJECT_DIRECTORY',
+	'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+	'GIT_NAMESPACE',
+	'GIT_CEILING_DIRECTORIES',
+	'GIT_DISCOVERY_ACROSS_FILESYSTEM'
+]
+
+const IN_PROGRESS_MARKERS = [
+	['MERGE_HEAD', 'merge'],
+	['rebase-merge', 'rebase'],
+	['rebase-apply', 'rebase or am operation'],
+	['CHERRY_PICK_HEAD', 'cherry-pick'],
+	['REVERT_HEAD', 'revert'],
+	['BISECT_LOG', 'bisect'],
+	['sequencer', 'sequenced Git operation']
+]
+
+/**
+ * @typedef {{ currentBranch: string, personalBranch: string, activationIdleMs: number }} ProjectGitModeConfig
+ * @typedef {{ status: number | null, stdout: string, stderr: string, error?: Error }} GitResult
+ * @typedef {(args: string[]) => GitResult} GitRunner
+ * @typedef {{
+ *   currentBranch: string,
+ *   personalBranch: string,
+ *   activationIdleMs: number,
+ *   repositoryRoot: string,
+ *   personalUpstream: string,
+ *   personalUpstreamRemote: string,
+ *   personalUpstreamBranch: string,
+ *   currentUpstream: string,
+ *   currentUpstreamRemote: string,
+ *   currentUpstreamBranch: string,
+ *   gitDirectory: string,
+ *   launchId: string,
+ *   runtimeStatePath: string,
+ *   runtimeDirectory: string,
+ *   leasePath: string,
+ *   leaseId: string,
+ *   commandStatePath: string,
+ *   childStatePath: string
+ * }} GitModeRuntime
+ * @typedef {{
+ *   version: typeof REPOSITORY_LEASE_VERSION,
+ *   leaseId: string,
+ *   launchId: string,
+ *   pid: number,
+ *   repositoryRoot: string,
+ *   commandStatePath: string,
+ *   childStatePath?: string,
+ *   createdAt: string
+ * }} RepositoryLease
+ * @typedef {{
+ *   leasePath: string,
+ *   leaseId: string,
+ *   commandStatePath: string,
+ *   childStatePath: string
+ * }} RepositoryLeaseClaim
+ * @typedef {{
+ *   pid: number,
+ *   processGroupId: number,
+ *   executable: string,
+ *   startedAt: string
+ * }} RepositoryCommandProcess
+ * @typedef {{
+ *   version: 1,
+ *   leaseId: string,
+ *   launchId: string,
+ *   repositoryRoot: string,
+ *   processes: RepositoryCommandProcess[]
+ * }} RepositoryCommandState
+ * @typedef {{ pid: number, name: string, startedAt: string }} RepositoryChildProcess
+ * @typedef {{
+ *   version: 1,
+ *   leaseId: string,
+ *   launchId: string,
+ *   processes: RepositoryChildProcess[]
+ * }} RepositoryChildState
+ */
+
+/**
+ * Read the opt-in only from the already-parsed project .env object. In particular, do not pass
+ * process.env here: an inherited shell variable must never enable Git mode.
+ *
+ * @param {Record<string, string | undefined>} projectEnv
+ * @returns {ProjectGitModeConfig | null}
+ */
+export function parseProjectGitMode(projectEnv) {
+	const mode = projectEnv.BOSUN_GIT_MODE?.trim().toLowerCase()
+	if (mode === undefined || mode === '' || mode === 'false') return null
+	if (mode !== 'true') {
+		throw new Error('BOSUN_GIT_MODE in the project .env must be either true or false.')
+	}
+
+	const currentBranch = projectEnv.BOSUN_CURRENT_BRANCH?.trim()
+	if (!currentBranch) {
+		throw new Error('Bosun Git mode requires BOSUN_CURRENT_BRANCH to be set in the project .env.')
+	}
+	const personalBranch = projectEnv.BOSUN_PERSONAL_BRANCH?.trim()
+	if (!personalBranch) {
+		throw new Error('Bosun Git mode requires BOSUN_PERSONAL_BRANCH to be set in the project .env.')
+	}
+	if (personalBranch === currentBranch) {
+		throw new Error('BOSUN_PERSONAL_BRANCH and BOSUN_CURRENT_BRANCH must name different branches.')
+	}
+
+	const idleMinutesValue =
+		projectEnv.BOSUN_GIT_ACTIVATION_IDLE_MINUTES?.trim() || String(DEFAULT_ACTIVATION_IDLE_MINUTES)
+	const idleMinutes = Number(idleMinutesValue)
+	const activationIdleMs = Math.max(1, Math.round(idleMinutes * 60_000))
+	if (
+		!Number.isFinite(idleMinutes) ||
+		idleMinutes <= 0 ||
+		!Number.isSafeInteger(activationIdleMs) ||
+		activationIdleMs <= 0
+	) {
+		throw new Error(
+			'BOSUN_GIT_ACTIVATION_IDLE_MINUTES in the project .env must be a positive number.'
+		)
+	}
+
+	return { currentBranch, personalBranch, activationIdleMs }
+}
+
+/**
+ * Validate the repository before either Bosun child process starts.
+ *
+ * @param {{ cwd: string, config: ProjectGitModeConfig, runGit?: GitRunner }} options
+ */
+export function validateGitModeStartup({ cwd, config, runGit = createGitRunner(cwd) }) {
+	const repositoryRootOutput = requiredGitOutput(
+		runGit,
+		['rev-parse', '--show-toplevel'],
+		'Bosun Git mode must be started from the root of a Git repository.'
+	)
+	const repositoryRoot = realpathSync(repositoryRootOutput)
+	const launchDirectory = realpathSync(cwd)
+	if (repositoryRoot !== launchDirectory) {
+		throw new Error(
+			`Bosun Git mode must be started from the repository root (${repositoryRoot}), not ${launchDirectory}.`
+		)
+	}
+	const gitMarkerPath = join(repositoryRoot, '.git')
+	try {
+		const marker = lstatSync(gitMarkerPath)
+		if (
+			!marker.isDirectory() ||
+			marker.isSymbolicLink() ||
+			realpathSync(gitMarkerPath) !== gitMarkerPath
+		) {
+			throw new Error('.git is not a standalone directory')
+		}
+	} catch (error) {
+		throw new Error(
+			'Bosun Git mode requires a primary checkout with a standalone .git directory. Separate Git directories, a linked Git worktree, and submodule checkouts are not supported.',
+			{ cause: error }
+		)
+	}
+
+	const superprojectRoot = optionalGitOutput(runGit, [
+		'rev-parse',
+		'--show-superproject-working-tree'
+	])
+	if (superprojectRoot) {
+		throw new Error(
+			`Bosun Git mode cannot run from a Git submodule checkout (${repositoryRoot}). Start it from a standalone repository.`
+		)
+	}
+
+	const trackedFiles = requiredGitResult(
+		runGit,
+		['ls-files', '--stage', '-z'],
+		'Bosun could not inspect the repository for tracked submodules.'
+	).stdout
+	if (/(?:^|\0)160000 /.test(trackedFiles)) {
+		throw new Error(
+			'Bosun Git mode cannot run in a repository containing tracked Git submodules. Remove the submodules or disable Git mode.'
+		)
+	}
+
+	const gitDirectory = realpathSync(
+		requiredGitOutput(
+			runGit,
+			['rev-parse', '--absolute-git-dir'],
+			'Bosun could not resolve the repository Git directory.'
+		)
+	)
+	const commonGitDirectory = realpathSync(
+		resolve(
+			cwd,
+			requiredGitOutput(
+				runGit,
+				['rev-parse', '--git-common-dir'],
+				'Bosun could not resolve the repository common Git directory.'
+			)
+		)
+	)
+	if (gitDirectory !== commonGitDirectory) {
+		throw new Error(
+			'Bosun Git mode cannot run from a linked Git worktree. Start Bosun from the primary checkout.'
+		)
+	}
+
+	for (const [marker, operation] of IN_PROGRESS_MARKERS) {
+		const markerPath = resolve(
+			cwd,
+			requiredGitOutput(
+				runGit,
+				['rev-parse', '--git-path', marker],
+				'Bosun could not inspect the current Git operation.'
+			)
+		)
+		if (existsSync(markerPath)) {
+			throw new Error(
+				`Bosun Git mode cannot start while a ${operation} is in progress. Finish or abort it, then restart Bosun.`
+			)
+		}
+	}
+
+	const checkedOutBranch = optionalGitOutput(runGit, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+	if (!checkedOutBranch) {
+		throw new Error(
+			'Bosun Git mode cannot start from a detached HEAD. Switch to the configured personal branch and restart Bosun.'
+		)
+	}
+
+	if (!gitSucceeded(runGit, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'])) {
+		throw new Error(
+			`Bosun Git mode cannot start because branch ${quoteForMessage(checkedOutBranch)} has no commits yet.`
+		)
+	}
+
+	if (!gitSucceeded(runGit, ['check-ref-format', '--branch', config.currentBranch])) {
+		throw new Error(
+			`BOSUN_CURRENT_BRANCH is not a valid Git branch name: ${quoteForMessage(config.currentBranch)}.`
+		)
+	}
+	if (!gitSucceeded(runGit, ['check-ref-format', '--branch', config.personalBranch])) {
+		throw new Error(
+			`BOSUN_PERSONAL_BRANCH is not a valid Git branch name: ${quoteForMessage(config.personalBranch)}.`
+		)
+	}
+
+	if (checkedOutBranch !== config.personalBranch) {
+		throw new Error(
+			`Bosun Git mode requires personal branch ${quoteForMessage(config.personalBranch)}, but the repository is on ${quoteForMessage(checkedOutBranch)}.\n\n` +
+				`Run this command and restart Bosun:\n  git switch ${quoteForShell(config.personalBranch)}`
+		)
+	}
+
+	if (
+		!gitSucceeded(runGit, ['show-ref', '--verify', '--quiet', `refs/heads/${config.currentBranch}`])
+	) {
+		throw new Error(
+			`Configured current branch ${quoteForMessage(config.currentBranch)} does not exist locally. Create and publish it before starting Bosun.`
+		)
+	}
+
+	if (
+		!gitSucceeded(runGit, [
+			'rev-parse',
+			'--verify',
+			'--quiet',
+			`refs/heads/${config.currentBranch}^{commit}`
+		])
+	) {
+		throw new Error(
+			`Configured current branch ${quoteForMessage(config.currentBranch)} does not resolve to a commit.`
+		)
+	}
+	const worktreeState = requiredGitResult(
+		runGit,
+		['worktree', 'list', '--porcelain'],
+		'Bosun could not inspect linked Git worktrees.'
+	).stdout
+	if (worktreeState.split('\n').includes(`branch refs/heads/${config.currentBranch}`)) {
+		throw new Error(
+			`Configured current branch ${quoteForMessage(config.currentBranch)} is checked out in another Git worktree. Remove that worktree or switch it to another branch, then restart Bosun.`
+		)
+	}
+
+	const personalUpstream = validateBranchUpstream(runGit, config.personalBranch)
+	const currentUpstream = validateBranchUpstream(runGit, config.currentBranch)
+	if (personalUpstream.remote !== currentUpstream.remote) {
+		throw new Error(
+			`Personal branch ${quoteForMessage(config.personalBranch)} and current branch ${quoteForMessage(config.currentBranch)} must track the same remote so Bosun can publish a release atomically.`
+		)
+	}
+	validateSingleRemoteDestination(runGit, personalUpstream.remote)
+	if (personalUpstream.branch === currentUpstream.branch) {
+		throw new Error(
+			`Personal branch ${quoteForMessage(config.personalBranch)} and current branch ${quoteForMessage(config.currentBranch)} must track different upstream branches.`
+		)
+	}
+
+	return {
+		repositoryRoot,
+		currentBranch: config.currentBranch,
+		personalBranch: config.personalBranch,
+		personalUpstream: personalUpstream.name,
+		personalUpstreamRemote: personalUpstream.remote,
+		personalUpstreamBranch: personalUpstream.branch,
+		currentUpstream: currentUpstream.name,
+		currentUpstreamRemote: currentUpstream.remote,
+		currentUpstreamBranch: currentUpstream.branch,
+		gitDirectory
+	}
+}
+
+/** @param {GitRunner} runGit @param {string} branch */
+function validateBranchUpstream(runGit, branch) {
+	const upstreamReference = `${branch}@{upstream}`
+	const upstream = requiredGitOutput(
+		runGit,
+		['rev-parse', '--abbrev-ref', '--symbolic-full-name', upstreamReference],
+		`Branch ${quoteForMessage(branch)} has no upstream. Configure its upstream and restart Bosun.`
+	)
+	if (
+		!gitSucceeded(runGit, ['rev-parse', '--verify', '--quiet', `${upstreamReference}^{commit}`])
+	) {
+		throw new Error(
+			`The upstream ${quoteForMessage(upstream)} for branch ${quoteForMessage(branch)} does not resolve to a commit. Fetch or repair it, then restart Bosun.`
+		)
+	}
+
+	const remote = requiredGitOutput(
+		runGit,
+		['config', '--get', `branch.${branch}.remote`],
+		`Bosun could not determine the upstream remote for ${quoteForMessage(branch)}.`
+	)
+	if (remote === '.') {
+		throw new Error(
+			`Branch ${quoteForMessage(branch)} tracks another local branch. Bosun Git mode requires an upstream remote it can pull from and push to.`
+		)
+	}
+	const upstreamMergeRef = requiredGitOutput(
+		runGit,
+		['config', '--get', `branch.${branch}.merge`],
+		`Bosun could not determine the upstream branch for ${quoteForMessage(branch)}.`
+	)
+	const headsPrefix = 'refs/heads/'
+	if (!upstreamMergeRef.startsWith(headsPrefix) || upstreamMergeRef.length === headsPrefix.length) {
+		throw new Error(
+			`Bosun Git mode requires an upstream branch for ${quoteForMessage(branch)}, but found ${quoteForMessage(upstreamMergeRef)}.`
+		)
+	}
+
+	return {
+		name: upstream,
+		remote,
+		branch: upstreamMergeRef.slice(headsPrefix.length)
+	}
+}
+
+/** @param {GitRunner} runGit @param {string} remote */
+function validateSingleRemoteDestination(runGit, remote) {
+	/** @param {string[]} args @param {string} kind */
+	const readUrls = (args, kind) =>
+		requiredGitResult(
+			runGit,
+			args,
+			`The upstream remote ${quoteForMessage(remote)} has no usable ${kind} URL. Repair it and restart Bosun.`
+		)
+			.stdout.split(/\r?\n/)
+			.map((url) => url.trim())
+			.filter(Boolean)
+	const fetchUrls = readUrls(['remote', 'get-url', '--all', remote], 'fetch')
+	const pushUrls = readUrls(['remote', 'get-url', '--push', '--all', remote], 'push')
+	if (fetchUrls.length !== 1 || pushUrls.length !== 1 || fetchUrls[0] !== pushUrls[0]) {
+		throw new Error(
+			`Upstream remote ${quoteForMessage(remote)} must have exactly one fetch URL and one identical push URL so Bosun can publish and recover a release safely.`
+		)
+	}
+}
+
+/**
+ * Create launch-scoped state. The launcher retains this object across managed backend restarts;
+ * a full launcher restart intentionally gets a new ID and state path.
+ *
+ * @param {{ cwd: string, projectEnv: Record<string, string | undefined> }} options
+ * @returns {GitModeRuntime | null}
+ */
+export function prepareGitModeRuntime({ cwd, projectEnv }) {
+	const config = parseProjectGitMode(projectEnv)
+	if (!config) return null
+	if (platform() === 'win32') {
+		throw new Error(
+			'Bosun Git mode is not supported on Windows because Bosun cannot safely own and verify an entire Git or pnpm process tree there. Use macOS, Linux, or WSL, or disable Git mode.'
+		)
+	}
+
+	const repository = validateGitModeStartup({ cwd, config })
+	const launchId = randomUUID()
+	const lease = acquireRepositoryLease({
+		gitDirectory: repository.gitDirectory,
+		repositoryRoot: repository.repositoryRoot,
+		launchId
+	})
+
+	try {
+		initializeRepositoryCommandState(lease.commandStatePath, {
+			version: 1,
+			leaseId: lease.leaseId,
+			launchId,
+			repositoryRoot: repository.repositoryRoot,
+			processes: []
+		})
+		initializeRepositoryChildState(lease.childStatePath, {
+			version: 1,
+			leaseId: lease.leaseId,
+			launchId,
+			processes: []
+		})
+		const runtimeDirectory = mkdtempSync(join(tmpdir(), 'bosun-git-mode-'))
+		return {
+			...config,
+			...repository,
+			...lease,
+			launchId,
+			runtimeDirectory,
+			runtimeStatePath: join(runtimeDirectory, 'runtime-state.json')
+		}
+	} catch (error) {
+		try {
+			unlinkSync(lease.commandStatePath)
+		} catch (cleanupError) {
+			if (!isNodeError(cleanupError, 'ENOENT')) {
+				// Keep the lease when command-state cleanup is uncertain.
+				throw new Error(
+					`Bosun could not safely clean up Git-mode startup state at ${lease.commandStatePath}. The repository lease was retained.`,
+					{ cause: cleanupError }
+				)
+			}
+		}
+		try {
+			unlinkSync(lease.childStatePath)
+		} catch (cleanupError) {
+			if (!isNodeError(cleanupError, 'ENOENT')) {
+				throw new Error(
+					`Bosun could not clean up child-process state at ${lease.childStatePath}. The repository lease was retained.`,
+					{ cause: cleanupError }
+				)
+			}
+		}
+		releaseRepositoryLease(lease.leasePath, lease.leaseId)
+		throw error
+	}
+}
+
+/** @param {GitModeRuntime | null} runtime */
+export function cleanupGitModeRuntime(runtime) {
+	if (!runtime) return
+	const commandState = readRepositoryCommandStateIfPresent(runtime.commandStatePath)
+	if (commandState && commandState.leaseId !== runtime.leaseId) {
+		throw new Error(
+			`Bosun cannot release the repository lease because ${runtime.commandStatePath} belongs to another launch.`
+		)
+	}
+	const liveProcesses = commandState?.processes.filter(isRepositoryCommandProcessAlive) ?? []
+	if (liveProcesses.length > 0) {
+		const processIds = liveProcesses.map((entry) => entry.pid).join(', ')
+		throw new Error(
+			`Bosun retained the repository lease because Git or pnpm is still running (PIDs: ${processIds}).`
+		)
+	}
+	const childState = readRepositoryChildStateIfPresent(runtime.childStatePath)
+	if (childState && childState.leaseId !== runtime.leaseId) {
+		throw new Error(
+			`Bosun cannot release the repository lease because ${runtime.childStatePath} belongs to another launch.`
+		)
+	}
+	const liveChildren = childState?.processes.filter((entry) => isProcessAlive(entry.pid)) ?? []
+	if (liveChildren.length > 0) {
+		throw new Error(
+			`Bosun retained the repository lease because child processes are still running (PIDs: ${liveChildren.map((entry) => entry.pid).join(', ')}).`
+		)
+	}
+	rmSync(runtime.runtimeDirectory, { force: true, recursive: true })
+	try {
+		unlinkSync(runtime.commandStatePath)
+	} catch (error) {
+		if (!isNodeError(error, 'ENOENT')) throw error
+	}
+	try {
+		unlinkSync(runtime.childStatePath)
+	} catch (error) {
+		if (!isNodeError(error, 'ENOENT')) throw error
+	}
+	if (!releaseRepositoryLease(runtime.leasePath, runtime.leaseId)) {
+		throw new Error('Bosun could not confirm ownership while releasing its repository lease.')
+	}
+}
+
+/** @param {GitModeRuntime | null} runtime @param {number | undefined} pid @param {string} name */
+export function registerGitModeChildProcess(runtime, pid, name) {
+	if (!runtime || !Number.isSafeInteger(pid) || Number(pid) <= 0) return
+	const state = readRepositoryChildState(runtime.childStatePath)
+	assertRepositoryChildStateOwner(state, runtime)
+	state.processes = state.processes.filter((entry) => entry.pid !== pid)
+	state.processes.push({ pid: Number(pid), name, startedAt: new Date().toISOString() })
+	writeRepositoryChildState(runtime.childStatePath, state)
+}
+
+/** @param {GitModeRuntime | null} runtime @param {number | undefined} pid */
+export function unregisterGitModeChildProcess(runtime, pid) {
+	if (!runtime || !Number.isSafeInteger(pid) || Number(pid) <= 0) return
+	const state = readRepositoryChildState(runtime.childStatePath)
+	assertRepositoryChildStateOwner(state, runtime)
+	state.processes = state.processes.filter((entry) => entry.pid !== pid)
+	writeRepositoryChildState(runtime.childStatePath, state)
+}
+
+/** @param {RepositoryChildState} state @param {GitModeRuntime} runtime */
+function assertRepositoryChildStateOwner(state, runtime) {
+	if (state.leaseId !== runtime.leaseId || state.launchId !== runtime.launchId) {
+		throw new Error(`Bosun cannot update child-process state at ${runtime.childStatePath}.`)
+	}
+}
+
+/**
+ * Atomically claim the one launcher lease for a primary repository. A dead launcher does not make
+ * the repository unusable: recover its lease automatically unless its durable command ledger
+ * identifies a Git/pnpm process group that is still alive.
+ *
+ * @param {{ gitDirectory: string, repositoryRoot: string, launchId: string }} input
+ * @returns {RepositoryLeaseClaim}
+ */
+export function acquireRepositoryLease(input) {
+	const leasePath = join(input.gitDirectory, REPOSITORY_LEASE_FILENAME)
+	const leaseId = randomUUID()
+	const commandStatePath = join(input.gitDirectory, `bosun-launcher.commands.${leaseId}.json`)
+	const childStatePath = join(input.gitDirectory, `bosun-launcher.children.${leaseId}.json`)
+	/** @type {RepositoryLease & { childStatePath: string }} */
+	const lease = {
+		version: REPOSITORY_LEASE_VERSION,
+		leaseId,
+		launchId: input.launchId,
+		pid: process.pid,
+		repositoryRoot: input.repositoryRoot,
+		commandStatePath,
+		childStatePath,
+		createdAt: new Date().toISOString()
+	}
+
+	assertNoRepositoryRecovery(leasePath, input.repositoryRoot)
+	if (tryCreateLeaseFile(leasePath, lease)) {
+		return { leasePath, leaseId, commandStatePath, childStatePath }
+	}
+
+	const existing = readRepositoryLease(leasePath)
+	if (existing === null) {
+		throw new Error(
+			'Bosun could not acquire its repository launcher lease because it changed during startup. Restart Bosun.'
+		)
+	}
+	assertLeaseMatchesRepository(existing, input.repositoryRoot, leasePath)
+	if (isProcessAlive(existing.pid)) throw activeLauncherError(existing)
+	return recoverDeadRepositoryLease({ leasePath, existing, replacement: lease })
+}
+
+/**
+ * Keep the old lease present while inspecting its command ledger, then replace it by ownership ID.
+ * The short-lived recovery lease serializes simultaneous restart attempts.
+ *
+ * @param {{ leasePath: string, existing: RepositoryLease, replacement: RepositoryLease & { childStatePath: string } }} input
+ * @returns {RepositoryLeaseClaim}
+ */
+function recoverDeadRepositoryLease({ leasePath, existing, replacement }) {
+	assertNoLiveRepositoryCommands(existing)
+	assertNoLiveRepositoryChildren(existing)
+	const recoveryPath = `${leasePath}.recovery`
+	const recoveryId = randomUUID()
+	/** @type {RepositoryLease} */
+	const recovery = {
+		...replacement,
+		leaseId: recoveryId,
+		launchId: `recovery:${replacement.launchId}`
+	}
+	if (!tryCreateLeaseFile(recoveryPath, recovery)) {
+		throw repositoryRecoveryError(recoveryPath)
+	}
+
+	try {
+		const current = readRepositoryLease(leasePath)
+		if (!current || current.leaseId !== existing.leaseId) {
+			if (current) throw activeLauncherError(current)
+			throw new Error('The Bosun repository launcher lease changed during recovery.')
+		}
+		assertNoLiveRepositoryCommands(current)
+		assertNoLiveRepositoryChildren(current)
+
+		try {
+			unlinkSync(existing.commandStatePath)
+		} catch (error) {
+			if (!isNodeError(error, 'ENOENT')) {
+				throw new Error(
+					`Bosun could not remove the stale command ledger at ${existing.commandStatePath}. Restart Bosun and try again.`,
+					{ cause: error }
+				)
+			}
+		}
+		if (existing.childStatePath) {
+			try {
+				unlinkSync(existing.childStatePath)
+			} catch (error) {
+				if (!isNodeError(error, 'ENOENT')) {
+					throw new Error(
+						`Bosun could not remove stale child-process state at ${existing.childStatePath}. Restart Bosun and try again.`,
+						{ cause: error }
+					)
+				}
+			}
+		}
+
+		if (!releaseRepositoryLease(leasePath, existing.leaseId)) {
+			throw new Error('The Bosun repository launcher lease changed while it was being recovered.')
+		}
+		if (!tryCreateLeaseFile(leasePath, replacement)) {
+			const winner = readRepositoryLease(leasePath)
+			if (winner) throw activeLauncherError(winner)
+			throw new Error('Bosun could not claim the repository lease after recovery.')
+		}
+		return {
+			leasePath,
+			leaseId: replacement.leaseId,
+			commandStatePath: replacement.commandStatePath,
+			childStatePath: replacement.childStatePath
+		}
+	} finally {
+		releaseRepositoryLease(recoveryPath, recoveryId)
+	}
+}
+
+/** @param {string} leasePath @param {string} repositoryRoot */
+function assertNoRepositoryRecovery(leasePath, repositoryRoot) {
+	const recoveryPath = `${leasePath}.recovery`
+	const recovery = readRepositoryLease(recoveryPath)
+	if (!recovery) return
+	assertLeaseMatchesRepository(recovery, repositoryRoot, recoveryPath)
+	if (isProcessAlive(recovery.pid)) throw repositoryRecoveryError(recoveryPath, recovery)
+	if (!releaseRepositoryLease(recoveryPath, recovery.leaseId)) {
+		throw new Error(`Bosun could not clear a stale repository recovery marker at ${recoveryPath}.`)
+	}
+}
+
+/** @param {string} recoveryPath @param {RepositoryLease} [recovery] */
+function repositoryRecoveryError(recoveryPath, recovery) {
+	if (recovery && isProcessAlive(recovery.pid)) {
+		return new Error(
+			`Another Bosun launcher (PID ${recovery.pid}) is already recovering this repository. Wait for it to finish, then restart Bosun.`
+		)
+	}
+	return new Error(`Bosun could not recover a stale repository marker at ${recoveryPath}.`)
+}
+
+/**
+ * Write complete contents to a unique same-directory file, then hard-link it into the exclusive
+ * lease name. Readers can therefore never observe a partially written lease.
+ *
+ * @param {string} leasePath
+ * @param {RepositoryLease} lease
+ */
+function tryCreateLeaseFile(leasePath, lease) {
+	const temporaryPath = `${leasePath}.${lease.leaseId}.tmp`
+	try {
+		writeFileSync(temporaryPath, `${JSON.stringify(lease)}\n`, {
+			encoding: 'utf8',
+			flag: 'wx',
+			mode: 0o600
+		})
+		try {
+			linkSync(temporaryPath, leasePath)
+			return true
+		} catch (error) {
+			if (isNodeError(error, 'EEXIST')) return false
+			throw error
+		}
+	} finally {
+		try {
+			unlinkSync(temporaryPath)
+		} catch (error) {
+			if (!isNodeError(error, 'ENOENT')) throw error
+		}
+	}
+}
+
+/** @param {string} leasePath @returns {RepositoryLease | null} */
+function readRepositoryLease(leasePath) {
+	let raw
+	try {
+		raw = readFileSync(leasePath, 'utf8')
+	} catch (error) {
+		if (isNodeError(error, 'ENOENT')) return null
+		throw error
+	}
+
+	let parsed
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		throw unreadableLeaseError(leasePath)
+	}
+	if (!isRepositoryLease(parsed)) throw unreadableLeaseError(leasePath)
+	return parsed
+}
+
+/** @param {unknown} value @returns {value is RepositoryLease} */
+function isRepositoryLease(value) {
+	if (!value || typeof value !== 'object') return false
+	const lease = /** @type {Partial<RepositoryLease>} */ (value)
+	return (
+		lease.version === REPOSITORY_LEASE_VERSION &&
+		typeof lease.leaseId === 'string' &&
+		lease.leaseId.length > 0 &&
+		typeof lease.launchId === 'string' &&
+		Number.isSafeInteger(lease.pid) &&
+		Number(lease.pid) > 0 &&
+		typeof lease.repositoryRoot === 'string' &&
+		typeof lease.commandStatePath === 'string' &&
+		(lease.childStatePath === undefined || typeof lease.childStatePath === 'string') &&
+		typeof lease.createdAt === 'string'
+	)
+}
+
+/** @param {RepositoryLease} lease @param {string} repositoryRoot @param {string} leasePath */
+function assertLeaseMatchesRepository(lease, repositoryRoot, leasePath) {
+	const commandStateFilename = basename(lease.commandStatePath)
+	const childStateFilename = lease.childStatePath ? basename(lease.childStatePath) : null
+	if (
+		lease.repositoryRoot !== repositoryRoot ||
+		dirname(resolve(lease.commandStatePath)) !== dirname(resolve(leasePath)) ||
+		!commandStateFilename.startsWith('bosun-launcher.commands.') ||
+		!commandStateFilename.endsWith('.json') ||
+		(lease.childStatePath !== undefined &&
+			(dirname(resolve(lease.childStatePath)) !== dirname(resolve(leasePath)) ||
+				!childStateFilename?.startsWith('bosun-launcher.children.') ||
+				!childStateFilename.endsWith('.json')))
+	) {
+		throw unreadableLeaseError(leasePath)
+	}
+}
+
+/** @param {number} pid */
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch (error) {
+		return !isNodeError(error, 'ESRCH')
+	}
+}
+
+/**
+ * Remove a lease only while the on-disk ownership ID still matches the caller.
+ *
+ * @param {string} leasePath
+ * @param {string} leaseId
+ */
+function releaseRepositoryLease(leasePath, leaseId) {
+	let current
+	try {
+		current = readRepositoryLease(leasePath)
+	} catch {
+		return false
+	}
+	if (!current || current.leaseId !== leaseId) return false
+	try {
+		unlinkSync(leasePath)
+		return true
+	} catch (error) {
+		if (isNodeError(error, 'ENOENT')) return false
+		return false
+	}
+}
+
+/** @param {RepositoryLease} lease */
+function activeLauncherError(lease) {
+	return new Error(
+		`Bosun Git mode is already running for this repository (launcher PID ${lease.pid}). Close the other Bosun instance, then restart Bosun.`
+	)
+}
+
+/** @param {RepositoryLease} lease */
+function assertNoLiveRepositoryCommands(lease) {
+	const commandState = readRepositoryCommandStateIfPresent(lease.commandStatePath)
+	if (!commandState) return
+	const liveProcesses = commandState.processes.filter(isRepositoryCommandProcessAlive)
+	if (liveProcesses.length === 0) return
+	throw new Error(
+		`A previous Bosun process ended, but Git or pnpm is still running for this repository (PIDs: ${liveProcesses.map((entry) => entry.pid).join(', ')}). Wait for it to finish or stop it, then restart Bosun.`
+	)
+}
+
+/** @param {RepositoryLease} lease */
+function assertNoLiveRepositoryChildren(lease) {
+	if (!lease.childStatePath) return
+	const childState = readRepositoryChildStateIfPresent(lease.childStatePath)
+	if (!childState) return
+	if (childState.leaseId !== lease.leaseId || childState.launchId !== lease.launchId) {
+		throw new Error(`Bosun cannot verify child-process ownership at ${lease.childStatePath}.`)
+	}
+	const liveChildren = childState.processes.filter((entry) => isProcessAlive(entry.pid))
+	if (liveChildren.length === 0) return
+	throw new Error(
+		`A previous Bosun launcher ended, but its ${liveChildren.map((entry) => `${entry.name} process ${entry.pid}`).join(' and ')} is still running. Wait for it to exit or stop it, then restart Bosun.`
+	)
+}
+
+/** @param {RepositoryCommandProcess} commandProcess */
+function isRepositoryCommandProcessAlive(commandProcess) {
+	if (isProcessAlive(commandProcess.pid)) return true
+	if (platform() === 'win32') return false
+	try {
+		process.kill(-commandProcess.processGroupId, 0)
+		return true
+	} catch (error) {
+		return !isNodeError(error, 'ESRCH')
+	}
+}
+
+/** @param {string} leasePath */
+function unreadableLeaseError(leasePath) {
+	return new Error(
+		`Bosun found an unreadable repository launcher lease at ${leasePath}. To avoid overlapping repository operations, confirm that no Bosun, Git, or pnpm process for this repository is still running. Then remove that lease and its associated bosun-launcher.commands.*.json ledger in ${dirname(leasePath)}, and restart Bosun.`
+	)
+}
+
+/** @param {string} commandStatePath @param {RepositoryCommandState} state */
+function initializeRepositoryCommandState(commandStatePath, state) {
+	writeFileSync(commandStatePath, `${JSON.stringify(state)}\n`, {
+		encoding: 'utf8',
+		flag: 'wx',
+		mode: 0o600
+	})
+}
+
+/** @param {string} childStatePath @param {RepositoryChildState} state */
+function initializeRepositoryChildState(childStatePath, state) {
+	writeFileSync(childStatePath, `${JSON.stringify(state)}\n`, {
+		encoding: 'utf8',
+		flag: 'wx',
+		mode: 0o600
+	})
+}
+
+/** @param {string} childStatePath @returns {RepositoryChildState} */
+function readRepositoryChildState(childStatePath) {
+	let parsed
+	try {
+		parsed = JSON.parse(readFileSync(childStatePath, 'utf8'))
+	} catch (error) {
+		throw new Error(`Bosun cannot read child-process state at ${childStatePath}.`, {
+			cause: error
+		})
+	}
+	if (!isRepositoryChildState(parsed)) {
+		throw new Error(`Bosun found invalid child-process state at ${childStatePath}.`)
+	}
+	return parsed
+}
+
+/** @param {string} childStatePath @returns {RepositoryChildState | null} */
+function readRepositoryChildStateIfPresent(childStatePath) {
+	try {
+		return readRepositoryChildState(childStatePath)
+	} catch (error) {
+		if (error instanceof Error && error.cause && isNodeError(error.cause, 'ENOENT')) return null
+		throw error
+	}
+}
+
+/** @param {string} childStatePath @param {RepositoryChildState} state */
+function writeRepositoryChildState(childStatePath, state) {
+	const temporaryPath = `${childStatePath}.${process.pid}.${randomUUID()}.tmp`
+	try {
+		writeFileSync(temporaryPath, `${JSON.stringify(state)}\n`, {
+			encoding: 'utf8',
+			flag: 'wx',
+			mode: 0o600
+		})
+		renameSync(temporaryPath, childStatePath)
+	} finally {
+		try {
+			unlinkSync(temporaryPath)
+		} catch (error) {
+			if (!isNodeError(error, 'ENOENT')) throw error
+		}
+	}
+}
+
+/** @param {unknown} value @returns {value is RepositoryChildState} */
+function isRepositoryChildState(value) {
+	if (!value || typeof value !== 'object') return false
+	const state = /** @type {Partial<RepositoryChildState>} */ (value)
+	return (
+		state.version === 1 &&
+		typeof state.leaseId === 'string' &&
+		typeof state.launchId === 'string' &&
+		Array.isArray(state.processes) &&
+		state.processes.every(
+			(entry) =>
+				entry &&
+				typeof entry === 'object' &&
+				Number.isSafeInteger(entry.pid) &&
+				entry.pid > 0 &&
+				typeof entry.name === 'string' &&
+				typeof entry.startedAt === 'string'
+		)
+	)
+}
+
+/** @param {string} commandStatePath @returns {RepositoryCommandState} */
+function readRepositoryCommandState(commandStatePath) {
+	let parsed
+	try {
+		parsed = JSON.parse(readFileSync(commandStatePath, 'utf8'))
+	} catch (error) {
+		throw new Error(
+			`Bosun cannot verify repository command state at ${commandStatePath}; the repository lease was retained.`,
+			{ cause: error }
+		)
+	}
+	if (!isRepositoryCommandState(parsed)) {
+		throw new Error(
+			`Bosun found invalid repository command state at ${commandStatePath}; the repository lease was retained.`
+		)
+	}
+	return parsed
+}
+
+/** @param {string} commandStatePath @returns {RepositoryCommandState | null} */
+function readRepositoryCommandStateIfPresent(commandStatePath) {
+	try {
+		return readRepositoryCommandState(commandStatePath)
+	} catch (error) {
+		if (error instanceof Error && error.cause && isNodeError(error.cause, 'ENOENT')) return null
+		throw error
+	}
+}
+
+/** @param {unknown} value @returns {value is RepositoryCommandState} */
+function isRepositoryCommandState(value) {
+	if (!value || typeof value !== 'object') return false
+	const state = /** @type {Partial<RepositoryCommandState>} */ (value)
+	return (
+		state.version === 1 &&
+		typeof state.leaseId === 'string' &&
+		typeof state.launchId === 'string' &&
+		typeof state.repositoryRoot === 'string' &&
+		Array.isArray(state.processes) &&
+		state.processes.every(
+			(process) =>
+				process &&
+				typeof process === 'object' &&
+				Number.isSafeInteger(process.pid) &&
+				process.pid > 0 &&
+				Number.isSafeInteger(process.processGroupId) &&
+				process.processGroupId > 0 &&
+				typeof process.executable === 'string' &&
+				typeof process.startedAt === 'string'
+		)
+	)
+}
+
+/** @param {unknown} error @param {string} code */
+function isNodeError(error, code) {
+	return error instanceof Error && 'code' in error && error.code === code
+}
+
+/**
+ * Strip every inherited/raw Git-mode setting, then add only launcher-validated values. The exact
+ * frontend origin is always launcher-owned, whether Git mode is enabled or disabled.
+ *
+ * @param {NodeJS.ProcessEnv} baseEnv
+ * @param {GitModeRuntime | null} runtime
+ * @param {string} allowedOrigin
+ */
+export function createBosunChildEnvironment(baseEnv, runtime, allowedOrigin) {
+	const childEnv = { ...baseEnv }
+	for (const name of GIT_MODE_ENV_NAMES) delete childEnv[name]
+	childEnv.BOSUN_ALLOWED_ORIGIN = allowedOrigin
+
+	if (!runtime) return childEnv
+	for (const name of GIT_REPOSITORY_ENV_NAMES) delete childEnv[name]
+
+	Object.assign(childEnv, {
+		BOSUN_GIT_MODE: 'true',
+		BOSUN_CURRENT_BRANCH: runtime.currentBranch,
+		BOSUN_PERSONAL_BRANCH: runtime.personalBranch,
+		BOSUN_GIT_ACTIVATION_IDLE_MS: String(runtime.activationIdleMs),
+		BOSUN_GIT_REPOSITORY_ROOT: runtime.repositoryRoot,
+		BOSUN_GIT_PERSONAL_UPSTREAM: runtime.personalUpstream,
+		BOSUN_GIT_PERSONAL_UPSTREAM_REMOTE: runtime.personalUpstreamRemote,
+		BOSUN_GIT_PERSONAL_UPSTREAM_BRANCH: runtime.personalUpstreamBranch,
+		BOSUN_GIT_CURRENT_UPSTREAM: runtime.currentUpstream,
+		BOSUN_GIT_CURRENT_UPSTREAM_REMOTE: runtime.currentUpstreamRemote,
+		BOSUN_GIT_CURRENT_UPSTREAM_BRANCH: runtime.currentUpstreamBranch,
+		BOSUN_GIT_LAUNCH_ID: runtime.launchId,
+		BOSUN_GIT_RUNTIME_STATE_PATH: runtime.runtimeStatePath,
+		BOSUN_GIT_COMMAND_STATE_PATH: runtime.commandStatePath,
+		BOSUN_GIT_LEASE_ID: runtime.leaseId,
+		BOSUN_GIT_ACTIVATION_RESTART_EXIT_CODE: String(GIT_ACTIVATION_RESTART_EXIT_CODE)
+	})
+
+	return childEnv
+}
+
+/** @param {string} cwd */
+function createGitRunner(cwd) {
+	/** @type {GitRunner} */
+	return (args) => {
+		/** @type {NodeJS.ProcessEnv} */
+		const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+		for (const name of GIT_REPOSITORY_ENV_NAMES) delete gitEnv[name]
+		const result = spawnSync('git', args, {
+			cwd,
+			encoding: 'utf8',
+			env: gitEnv,
+			stdio: ['ignore', 'pipe', 'pipe']
+		})
+		return {
+			status: result.status,
+			stdout: result.stdout ?? '',
+			stderr: result.stderr ?? '',
+			error: result.error
+		}
+	}
+}
+
+/** @param {GitRunner} runGit @param {string[]} args */
+function gitSucceeded(runGit, args) {
+	const result = runGit(args)
+	if (result.error) throw gitExecutionError(result.error)
+	return result.status === 0
+}
+
+/** @param {GitRunner} runGit @param {string[]} args */
+function optionalGitOutput(runGit, args) {
+	const result = runGit(args)
+	if (result.error) throw gitExecutionError(result.error)
+	return result.status === 0 ? result.stdout.trim() : ''
+}
+
+/** @param {GitRunner} runGit @param {string[]} args @param {string} errorMessage */
+function requiredGitResult(runGit, args, errorMessage) {
+	const result = runGit(args)
+	if (result.error) throw gitExecutionError(result.error)
+	if (result.status !== 0) {
+		const detail = result.stderr.trim()
+		throw new Error(detail ? `${errorMessage}\nGit reported: ${detail}` : errorMessage)
+	}
+	return result
+}
+
+/** @param {GitRunner} runGit @param {string[]} args @param {string} errorMessage */
+function requiredGitOutput(runGit, args, errorMessage) {
+	const result = runGit(args)
+	if (result.error) throw gitExecutionError(result.error)
+	const output = result.stdout.trim()
+	if (result.status !== 0 || !output) {
+		const detail = result.stderr.trim()
+		throw new Error(detail ? `${errorMessage}\nGit reported: ${detail}` : errorMessage)
+	}
+	return output
+}
+
+/** @param {Error} error */
+function gitExecutionError(error) {
+	const isMissingGit = 'code' in error && error.code === 'ENOENT'
+	return new Error(
+		isMissingGit
+			? 'Bosun Git mode requires Git to be installed and available on PATH.'
+			: `Bosun could not run Git: ${error.message}`
+	)
+}
+
+/** @param {string} value */
+function quoteForMessage(value) {
+	return JSON.stringify(value)
+}
+
+/** @param {string} value */
+function quoteForShell(value) {
+	return `'${value.replaceAll("'", `'"'"'`)}'`
+}