@recombine-ai/bosun 0.16.2 → 0.17.1

package/src/backend/git-mode/service.ts

@@ -0,0 +1,2183 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { watch, type FSWatcher } from 'node:fs'
+import {
+	access,
+	lstat,
+	mkdir,
+	open,
+	readFile,
+	readlink,
+	realpath,
+	rename,
+	rm,
+	unlink,
+	writeFile
+} from 'node:fs/promises'
+import path from 'node:path'
+
+import { CommandError, runCommand, type CommandResult, type CommandRunner } from './command'
+import type {
+	ChangeChoice,
+	GitModeConfig,
+	GitModeFatal,
+	GitModeFatalKind,
+	GitModePreparationStage,
+	GitModeService,
+	GitModeStatus
+} from './types'
+
+const RUNTIME_STATE_VERSION = 1
+// Browser teardown delivery is best-effort (a closed/crashed tab may never unregister). Keep the
+// heartbeat lease shorter than the flush deadline so such a tab expires instead of turning an
+// otherwise safe refresh into a permanent fatal state. Active tabs poll much more frequently.
+const DEFAULT_LIVE_TAB_MS = 15_000
+const DEFAULT_FLUSH_TIMEOUT_MS = 45_000
+const GIT_TIMEOUT_MS = 2 * 60 * 1000
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000
+const CHANGE_CACHE_MS = 500
+const PREPARE_ELIGIBILITY_CACHE_MS = 500
+const CONTENT_REFRESH_JOURNAL_VERSION = 1
+const PREPARE_JOURNAL_VERSION = 1
+const PREPARE_RESULT_REF = 'refs/bosun/prepare-release-result'
+
+const LOCAL_CHANGES_REFUSAL = [
+	/Your local changes to the following files would be overwritten by (?:merge|checkout)/i,
+	/The following untracked working tree files would be overwritten by merge/i,
+	/Please commit your changes or stash them before you merge/i,
+	/Entry .* not uptodate\. Cannot merge\./i,
+	/Cannot pull with rebase: You have unstaged changes/i
+]
+
+const BLOCKING_PHASES = new Set([
+	'flushing',
+	'refreshing',
+	'awaiting-changes',
+	'processing',
+	'restarting',
+	'fatal'
+])
+
+interface PersistedRuntimeState {
+	version: typeof RUNTIME_STATE_VERSION
+	launchId: string
+	firstActivationCompleted: boolean
+	lastCompletedActivationAt: number | null
+	lastRelevantChangeAt: number
+	reloadToken: string | null
+	fatal: GitModeFatal | null
+}
+
+interface ActiveOperation {
+	id: string
+	kind: 'activation' | 'manual' | 'prepare-release'
+	contentBaseline: string | null
+	pendingTabs: Set<string>
+	acknowledgedTabs: Set<string>
+	blockedReasons: Map<string, string>
+	choice: ChangeChoice | null
+	deadline: number
+	flushStarted: boolean
+	stage: GitModePreparationStage
+}
+
+interface ContentRefreshJournal {
+	version: typeof CONTENT_REFRESH_JOURNAL_VERSION
+	baseline: string
+	installedContent: string | null
+	reloadToken: string | null
+}
+
+interface PrepareReleaseJournal {
+	version: typeof PREPARE_JOURNAL_VERSION
+	currentBranch: string
+	personalBranch: string
+	remote: string
+	currentRemoteBranch: string
+	personalRemoteBranch: string
+	remoteUrlDigest: string
+	oldCurrentRemoteHead: string
+	oldPersonalRemoteHead: string
+	oldCurrentLocalHead: string
+	resultHead: string | null
+}
+
+interface GitFeatures {
+	mergeAutostashOption: boolean
+	ortStrategy: boolean
+}
+
+export interface GitModeServiceDependencies {
+	runCommand?: CommandRunner
+	settleWrites?: () => Promise<void>
+	resumeWrites?: () => Promise<void>
+	installProject?: () => Promise<void>
+	scheduleRestart?: (exitCode: number) => boolean | Promise<boolean>
+	now?: () => number
+	randomId?: () => string
+	liveTabMs?: number
+	flushTimeoutMs?: number
+	watchFileChanges?: boolean
+	logError?: (message: string, error?: unknown) => void
+}
+
+class RepositoryValidationError extends Error {
+	constructor(
+		message: string,
+		readonly kind: GitModeFatalKind = 'general',
+		options?: ErrorOptions
+	) {
+		super(message, options)
+		this.name = 'RepositoryValidationError'
+	}
+}
+
+class PrepareMergeConflictError extends Error {
+	constructor() {
+		super('The personal branch conflicts with the release branch.')
+		this.name = 'PrepareMergeConflictError'
+	}
+}
+
+export function createGitModeService(
+	config: GitModeConfig,
+	dependencies: GitModeServiceDependencies = {}
+): GitModeService {
+	return new DefaultGitModeService(config, dependencies)
+}
+
+class DefaultGitModeService implements GitModeService {
+	private readonly command: CommandRunner
+	private readonly settleWrites: () => Promise<void>
+	private readonly resumeWrites: () => Promise<void>
+	private readonly installProject: () => Promise<void>
+	private readonly scheduleRestart: (exitCode: number) => boolean | Promise<boolean>
+	private readonly now: () => number
+	private readonly randomId: () => string
+	private readonly liveTabMs: number
+	private readonly flushTimeoutMs: number
+	private readonly shouldWatchFiles: boolean
+	private readonly logError: (message: string, error?: unknown) => void
+	private readonly hooksDir: string
+	private readonly ready: Promise<void>
+
+	private runtime: PersistedRuntimeState
+	private phase: GitModeStatus['phase']
+	private operationId: string | null = null
+	private operation: ActiveOperation | null = null
+	private deferredReason: string | null = null
+	private hasChanges = false
+	private canPrepareRelease = false
+	private tabs = new Map<string, number>()
+	private watcher: FSWatcher | null = null
+	private watchedPaths = new Set<string>()
+	private watchDebounce: ReturnType<typeof setTimeout> | null = null
+	private flushTimer: ReturnType<typeof setInterval> | null = null
+	private changeRefreshAt = 0
+	private changeRefresh: Promise<void> | null = null
+	private prepareEligibilityRefreshAt = 0
+	private prepareEligibilityRefresh: Promise<void> | null = null
+	private persistQueue: Promise<void> = Promise.resolve()
+	private gitQueue: Promise<void> = Promise.resolve()
+	private gitFeaturesPromise: Promise<GitFeatures> | null = null
+	private operationTask: Promise<void> | null = null
+	private disposed = false
+	private readonly contentRefreshJournalPath: string
+	private readonly prepareJournalPath: string
+	private readonly prepareWorkspacePath: string
+
+	constructor(
+		private readonly config: GitModeConfig,
+		dependencies: GitModeServiceDependencies
+	) {
+		this.command = dependencies.runCommand ?? runCommand
+		this.settleWrites = dependencies.settleWrites ?? (async () => {})
+		this.resumeWrites =
+			dependencies.resumeWrites ??
+			(async () => {
+				if (this.config.enabled) {
+					throw new Error('The repository write gate cannot be released without restarting Bosun.')
+				}
+			})
+		this.installProject =
+			dependencies.installProject ??
+			(async () => {
+				await this.command(
+					'pnpm',
+					['install', '--frozen-lockfile', '--ignore-scripts', '--ignore-pnpmfile'],
+					{
+						cwd: this.config.projectDir,
+						env: this.nonInteractiveEnvironment(),
+						timeoutMs: INSTALL_TIMEOUT_MS
+					}
+				)
+			})
+		this.scheduleRestart =
+			dependencies.scheduleRestart ??
+			((exitCode) => {
+				const timer = setTimeout(() => process.exit(exitCode), 500)
+				timer.unref()
+				return true
+			})
+		this.now = dependencies.now ?? Date.now
+		this.randomId = dependencies.randomId ?? randomUUID
+		this.liveTabMs = dependencies.liveTabMs ?? DEFAULT_LIVE_TAB_MS
+		this.flushTimeoutMs = dependencies.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS
+		this.shouldWatchFiles = dependencies.watchFileChanges ?? true
+		this.logError = dependencies.logError ?? console.error
+		this.hooksDir = path.join(
+			path.dirname(config.runtimeStatePath || config.projectDir),
+			'empty-hooks'
+		)
+		this.contentRefreshJournalPath = path.join(
+			config.projectDir,
+			'.git',
+			'bosun-content-refresh.json'
+		)
+		this.prepareJournalPath = path.join(config.projectDir, '.git', 'bosun-prepare-release.json')
+		this.prepareWorkspacePath = path.join(
+			config.projectDir,
+			'.git',
+			'bosun-prepare-release-workspace'
+		)
+		this.phase = config.enabled ? 'refreshing' : 'idle'
+		this.runtime = this.newRuntimeState()
+		this.ready = this.initialize()
+	}
+
+	isUsageBlocked(): boolean {
+		if (!this.config.enabled) return false
+		return BLOCKING_PHASES.has(this.phase)
+	}
+
+	async status(input: { tabId: string }): Promise<GitModeStatus> {
+		await this.ready
+		this.registerTab(input.tabId)
+		// Status polling stays filesystem-only while the repository lock is active; even read-only
+		// Git commands add needless lock/error races with an in-progress pull, commit, or stash.
+		if (this.phase === 'idle') await this.refreshRepositoryStatus()
+		return this.createStatus(input.tabId)
+	}
+
+	async unregister(input: { tabId: string }): Promise<GitModeStatus> {
+		await this.ready
+		this.tabs.delete(input.tabId)
+		const operation = this.operation
+		if (operation && (this.phase === 'preparing' || this.phase === 'flushing')) {
+			operation.pendingTabs.delete(input.tabId)
+			operation.acknowledgedTabs.delete(input.tabId)
+			operation.blockedReasons.delete(input.tabId)
+			this.evaluateFlush(operation)
+		}
+		return this.createStatus(input.tabId)
+	}
+
+	async activate(input: { tabId: string; reason: 'page-open' | 'focus' }): Promise<GitModeStatus> {
+		await this.ready
+		this.registerTab(input.tabId)
+		if (!this.config.enabled || this.phase === 'fatal') return this.createStatus(input.tabId)
+		if (this.operation || this.phase !== 'idle') return this.createStatus(input.tabId)
+		if (!this.isActivationEligible()) return this.createStatus(input.tabId)
+		if (!(await this.prevalidateStart(input.tabId))) return this.createStatus(input.tabId)
+		if (this.operation || this.phase !== 'idle') return this.createStatus(input.tabId)
+
+		this.startFlush('activation', input.tabId, null)
+		return this.createStatus(input.tabId)
+	}
+
+	async flushAck(input: {
+		tabId: string
+		operationId: string
+		stage: GitModePreparationStage
+		blockedReason?: string
+	}): Promise<GitModeStatus> {
+		await this.ready
+		this.registerTab(input.tabId)
+		const operation = this.operation
+		if (
+			!operation ||
+			operation.id !== input.operationId ||
+			this.phase !== 'preparing' ||
+			operation.stage !== input.stage
+		) {
+			return this.createStatus(input.tabId)
+		}
+
+		if (operation.pendingTabs.delete(input.tabId)) {
+			operation.acknowledgedTabs.add(input.tabId)
+			const reason = input.blockedReason?.trim()
+			if (reason) operation.blockedReasons.set(input.tabId, reason)
+		}
+		this.evaluateFlush(operation)
+		return this.createStatus(input.tabId)
+	}
+
+	async startManual(input: { tabId: string } & ChangeChoice): Promise<GitModeStatus> {
+		await this.ready
+		this.registerTab(input.tabId)
+		if (!this.config.enabled || this.phase === 'fatal') return this.createStatus(input.tabId)
+		this.assertManualOperationAvailable()
+		this.validateChoice(input)
+
+		await this.refreshHasChanges(true)
+		this.assertManualOperationAvailable()
+		if (!this.hasChanges) return this.createStatus(input.tabId)
+		if (!(await this.prevalidateStart(input.tabId, true))) return this.createStatus(input.tabId)
+		this.assertManualOperationAvailable()
+
+		this.startFlush('manual', input.tabId, this.normalizeChoice(input))
+		return this.createStatus(input.tabId)
+	}
+
+	async prepareRelease(input: { tabId: string }): Promise<GitModeStatus> {
+		await this.ready
+		this.registerTab(input.tabId)
+		if (!this.config.enabled || this.phase === 'fatal') return this.createStatus(input.tabId)
+		this.assertManualOperationAvailable()
+
+		await this.refreshRepositoryStatus(true)
+		this.assertManualOperationAvailable()
+		if (!this.canPrepareRelease) return this.createStatus(input.tabId)
+		if (!(await this.prevalidateStart(input.tabId, true))) return this.createStatus(input.tabId)
+		this.assertManualOperationAvailable()
+
+		this.startFlush('prepare-release', input.tabId, null)
+		return this.createStatus(input.tabId)
+	}
+
+	async resolveChanges(
+		input: {
+			tabId: string
+			operationId: string
+		} & ChangeChoice
+	): Promise<GitModeStatus> {
+		await this.ready
+		this.registerTab(input.tabId)
+		const operation = this.operation
+		if (
+			!operation ||
+			operation.id !== input.operationId ||
+			operation.kind !== 'activation' ||
+			this.phase !== 'awaiting-changes'
+		) {
+			throw new Error('This refresh choice was already handled in another Bosun tab.')
+		}
+
+		this.validateChoice(input)
+		operation.choice = this.normalizeChoice(input)
+		this.phase = 'processing'
+		this.startOperation(() => this.continueAfterChanges(operation))
+		return this.createStatus(input.tabId)
+	}
+
+	async dispose(): Promise<void> {
+		this.disposed = true
+		if (this.flushTimer) clearInterval(this.flushTimer)
+		if (this.watchDebounce) clearTimeout(this.watchDebounce)
+		this.watcher?.close()
+		await this.operationTask?.catch(() => {})
+		await this.gitQueue.catch(() => {})
+		await this.persistQueue.catch(() => {})
+	}
+
+	private async initialize(): Promise<void> {
+		if (!this.config.enabled) return
+
+		try {
+			await mkdir(this.hooksDir, { recursive: true })
+			this.runtime = await this.loadRuntimeState()
+			if (await this.prepareJournalExists()) {
+				await this.settleWrites()
+				await this.recoverPrepareRelease()
+			} else if (await this.contentRefreshJournalExists()) {
+				await this.settleWrites()
+				await this.recoverContentRefresh()
+			}
+			if (this.phase !== 'restarting') this.phase = this.runtime.fatal ? 'fatal' : 'idle'
+			await this.queueRuntimePersist()
+			if (this.shouldWatchFiles && this.phase !== 'restarting') this.startFileWatcher()
+		} catch (error) {
+			const validation = error instanceof RepositoryValidationError ? error : null
+			await this.setFatal(
+				validation?.kind ?? 'general',
+				validation?.message ??
+					'Bosun could not initialise Git mode. Resolve the problem and restart Bosun.',
+				null,
+				error
+			)
+		}
+	}
+
+	private newRuntimeState(): PersistedRuntimeState {
+		return {
+			version: RUNTIME_STATE_VERSION,
+			launchId: this.config.launchId,
+			firstActivationCompleted: false,
+			lastCompletedActivationAt: null,
+			lastRelevantChangeAt: this.now(),
+			reloadToken: null,
+			fatal: null
+		}
+	}
+
+	private async loadRuntimeState(): Promise<PersistedRuntimeState> {
+		let raw: string
+		try {
+			raw = await readFile(this.config.runtimeStatePath, 'utf8')
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) return this.newRuntimeState()
+			throw error
+		}
+
+		const parsed: unknown = JSON.parse(raw)
+		if (!isRuntimeState(parsed) || parsed.launchId !== this.config.launchId) {
+			return this.newRuntimeState()
+		}
+		return parsed
+	}
+
+	private queueRuntimePersist(): Promise<void> {
+		if (!this.config.enabled) return Promise.resolve()
+		const snapshot = JSON.stringify(this.runtime)
+		this.persistQueue = this.persistQueue
+			.catch(() => {})
+			.then(async () => {
+				const target = this.config.runtimeStatePath
+				await mkdir(path.dirname(target), { recursive: true })
+				const temporary = `${target}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`
+				try {
+					await writeFile(temporary, `${snapshot}\n`, { encoding: 'utf8', mode: 0o600 })
+					await rename(temporary, target)
+				} finally {
+					await unlink(temporary).catch(() => {})
+				}
+			})
+		return this.persistQueue
+	}
+
+	private startFileWatcher(): void {
+		this.watcher = watch(this.config.projectDir, { recursive: true }, (_eventType, filename) =>
+			this.noteWatchEvent(filename?.toString() ?? null)
+		)
+		this.watcher.on('error', (error) => {
+			if (this.phase === 'fatal') return
+			void this.setFatal(
+				'general',
+				'Bosun can no longer track repository activity safely. Restart Bosun before continuing.',
+				null,
+				error
+			)
+		})
+	}
+
+	private noteWatchEvent(filename: string | null): void {
+		if (this.disposed) return
+		if (filename === null) {
+			this.recordRelevantChange()
+			return
+		}
+
+		const relative = filename.split(path.sep).join('/')
+		if (
+			relative === '.git' ||
+			relative.startsWith('.git/') ||
+			relative === 'node_modules' ||
+			relative.startsWith('node_modules/') ||
+			relative === '.svelte-kit' ||
+			relative.startsWith('.svelte-kit/') ||
+			relative === 'build' ||
+			relative.startsWith('build/') ||
+			path.resolve(this.config.projectDir, filename) === path.resolve(this.config.runtimeStatePath)
+		) {
+			return
+		}
+
+		this.watchedPaths.add(relative)
+		if (this.watchDebounce) clearTimeout(this.watchDebounce)
+		this.watchDebounce = setTimeout(() => {
+			this.watchDebounce = null
+			void this.filterWatchedPaths().catch(() => this.recordRelevantChange())
+		}, 150)
+		this.watchDebounce.unref()
+	}
+
+	private async filterWatchedPaths(): Promise<void> {
+		const candidates = [...this.watchedPaths]
+		this.watchedPaths.clear()
+		if (!candidates.length) return
+		if (this.phase !== 'idle') {
+			// Pull/install changes are relevant for the next idle window, but the watcher must not
+			// launch an ancillary Git read between commands in the refresh transaction.
+			this.recordRelevantChange()
+			return
+		}
+		if (candidates.length > 1_000) {
+			this.recordRelevantChange()
+			return
+		}
+
+		const result = await this.git(['check-ignore', '--stdin', '-z'], {
+			input: `${candidates.join('\0')}\0`,
+			acceptedExitCodes: [0, 1]
+		})
+		const ignored = new Set(result.stdout.split('\0').filter(Boolean))
+		if (candidates.some((candidate) => !ignored.has(candidate))) this.recordRelevantChange()
+	}
+
+	private recordRelevantChange(): void {
+		const changedAt = this.now()
+		if (changedAt <= this.runtime.lastRelevantChangeAt) return
+		this.runtime.lastRelevantChangeAt = changedAt
+		void this.queueRuntimePersist().catch((error) => {
+			this.logError('Bosun could not persist the latest working-tree change time.', error)
+		})
+	}
+
+	private registerTab(tabId: string): void {
+		this.tabs.set(tabId, this.now())
+		const operation = this.operation
+		if (
+			operation &&
+			!operation.flushStarted &&
+			this.phase === 'preparing' &&
+			!operation.acknowledgedTabs.has(tabId)
+		) {
+			operation.pendingTabs.add(tabId)
+		}
+	}
+
+	private createStatus(tabId: string): GitModeStatus {
+		return {
+			enabled: this.config.enabled,
+			phase: this.config.enabled ? this.phase : 'idle',
+			operationId: this.operationId,
+			hasChanges: this.config.enabled ? this.hasChanges : false,
+			canPrepareRelease:
+				this.config.enabled && this.phase === 'idle' ? this.canPrepareRelease : false,
+			fatal: this.runtime.fatal,
+			prUrl: this.runtime.fatal?.prUrl ?? null,
+			reloadToken: this.runtime.reloadToken,
+			deferredReason: this.deferredReason,
+			tabNeedsFlush: this.phase === 'preparing' && Boolean(this.operation?.pendingTabs.has(tabId)),
+			preparationStage: this.phase === 'preparing' ? (this.operation?.stage ?? null) : null
+		}
+	}
+
+	private isActivationEligible(): boolean {
+		if (!this.runtime.firstActivationCompleted) return true
+		const completedAt = this.runtime.lastCompletedActivationAt
+		if (completedAt === null) return true
+		const now = this.now()
+		return (
+			now - completedAt >= this.config.idleMs &&
+			now - this.runtime.lastRelevantChangeAt >= this.config.idleMs
+		)
+	}
+
+	private async refreshHasChanges(force = false): Promise<void> {
+		if (!this.config.enabled || this.phase === 'fatal') return
+		const now = this.now()
+		if (!force && now - this.changeRefreshAt < CHANGE_CACHE_MS) return
+		if (this.changeRefresh) return this.changeRefresh
+
+		this.changeRefresh = (async () => {
+			try {
+				const result = await this.git([
+					'status',
+					'--porcelain=v1',
+					'-z',
+					'--untracked-files=normal',
+					'--ignore-submodules=none'
+				])
+				this.hasChanges = result.stdout.length > 0
+				this.changeRefreshAt = this.now()
+			} catch {
+				// Activation revalidates the repository and turns this into a useful fatal error.
+				this.changeRefreshAt = this.now()
+			}
+		})().finally(() => {
+			this.changeRefresh = null
+		})
+		return this.changeRefresh
+	}
+
+	private async refreshRepositoryStatus(force = false): Promise<void> {
+		await this.refreshHasChanges(force)
+		if (this.hasChanges) {
+			this.canPrepareRelease = false
+			return
+		}
+		await this.refreshPrepareEligibility(force)
+	}
+
+	private async refreshPrepareEligibility(force = false): Promise<void> {
+		if (!this.config.enabled || this.phase !== 'idle') return
+		const now = this.now()
+		if (
+			!force &&
+			this.prepareEligibilityRefreshAt !== 0 &&
+			now - this.prepareEligibilityRefreshAt < PREPARE_ELIGIBILITY_CACHE_MS
+		) {
+			return
+		}
+		if (this.prepareEligibilityRefresh) return this.prepareEligibilityRefresh
+
+		this.prepareEligibilityRefresh = (async () => {
+			try {
+				await this.updatePrepareEligibilityFromFetchedRefs()
+			} catch {
+				// The locked Prepare transaction refreshes and repeats this check. Idle status polling uses
+				// only the last safely fetched tracking ref and keeps the action unavailable if it is invalid.
+				this.canPrepareRelease = false
+			} finally {
+				this.prepareEligibilityRefreshAt = this.now()
+			}
+		})().finally(() => {
+			this.prepareEligibilityRefresh = null
+		})
+		return this.prepareEligibilityRefresh
+	}
+
+	private async updatePrepareEligibilityFromFetchedRefs(
+		currentHead = this.config.currentUpstream
+	): Promise<void> {
+		this.canPrepareRelease =
+			!this.hasChanges && (await this.commitCount(`${currentHead}..HEAD`)) > 0
+		this.prepareEligibilityRefreshAt = this.now()
+	}
+
+	private startFlush(
+		kind: ActiveOperation['kind'],
+		initiatingTabId: string,
+		choice: ChangeChoice | null
+	): void {
+		const now = this.now()
+		const liveTabs = this.snapshotLiveTabs()
+		liveTabs.add(initiatingTabId)
+
+		const operation: ActiveOperation = {
+			id: this.randomId(),
+			kind,
+			contentBaseline: null,
+			pendingTabs: liveTabs,
+			acknowledgedTabs: new Set(),
+			blockedReasons: new Map(),
+			choice,
+			deadline: now + this.flushTimeoutMs,
+			flushStarted: false,
+			stage: 'preflight'
+		}
+		this.operation = operation
+		this.operationId = operation.id
+		this.phase = 'preparing'
+		this.deferredReason = null
+		this.startFlushTimer(operation)
+	}
+
+	private snapshotLiveTabs(): Set<string> {
+		const now = this.now()
+		for (const [tabId, lastSeen] of this.tabs) {
+			if (now - lastSeen > this.liveTabMs) this.tabs.delete(tabId)
+		}
+		return new Set(
+			[...this.tabs.entries()]
+				.filter(([, lastSeen]) => now - lastSeen <= this.liveTabMs)
+				.map(([tabId]) => tabId)
+		)
+	}
+
+	private startFlushTimer(operation: ActiveOperation): void {
+		if (this.flushTimer) clearInterval(this.flushTimer)
+		this.flushTimer = setInterval(() => this.evaluateFlush(operation), 500)
+		this.flushTimer.unref()
+	}
+
+	private evaluateFlush(operation: ActiveOperation): void {
+		if (this.operation !== operation || operation.flushStarted || this.phase !== 'preparing') return
+		const now = this.now()
+		for (const tabId of operation.pendingTabs) {
+			const lastSeen = this.tabs.get(tabId)
+			if (lastSeen === undefined || now - lastSeen > this.liveTabMs)
+				operation.pendingTabs.delete(tabId)
+		}
+
+		if (operation.pendingTabs.size > 0 && now >= operation.deadline) {
+			operation.flushStarted = true
+			this.clearFlushTimer()
+			void this.setFatal(
+				'general',
+				'Bosun could not confirm that every open tab saved its pending edits. Restart Bosun before continuing.'
+			)
+			return
+		}
+		if (operation.pendingTabs.size > 0) return
+
+		this.clearFlushTimer()
+		if (operation.blockedReasons.size > 0) {
+			this.deferredReason = [...new Set(operation.blockedReasons.values())].join('\n')
+			this.phase = 'idle'
+			this.operation = null
+			this.operationId = null
+			return
+		}
+		if (operation.stage === 'preflight') {
+			operation.pendingTabs = this.snapshotLiveTabs()
+			operation.acknowledgedTabs.clear()
+			operation.blockedReasons.clear()
+			operation.deadline = this.now() + this.flushTimeoutMs
+			operation.stage = 'browser-writes'
+			this.startFlushTimer(operation)
+			return
+		}
+
+		operation.flushStarted = true
+		// From this synchronous transition onward, the HTTP and WebSocket admission guards reject
+		// ordinary repository operations. Work admitted before the lock is drained below.
+		this.phase = 'flushing'
+		this.startOperation(() => this.runAfterFlush(operation))
+	}
+
+	private startOperation(operation: () => Promise<void>): void {
+		const task = operation()
+			.catch((error: unknown) => this.failFromError(error))
+			.finally(() => {
+				if (this.operationTask === task) this.operationTask = null
+			})
+		this.operationTask = task
+	}
+
+	private clearFlushTimer(): void {
+		if (!this.flushTimer) return
+		clearInterval(this.flushTimer)
+		this.flushTimer = null
+	}
+
+	private async runAfterFlush(operation: ActiveOperation): Promise<void> {
+		if (this.operation !== operation) return
+		await this.settleWrites()
+		if (this.operation !== operation) return
+		await this.validateRepository()
+		if (this.operation !== operation) return
+		operation.contentBaseline = await this.projectContentDigest()
+		if (this.operation !== operation) return
+		await this.writeContentRefreshJournal({
+			version: CONTENT_REFRESH_JOURNAL_VERSION,
+			baseline: operation.contentBaseline,
+			installedContent: null,
+			reloadToken: null
+		})
+		if (this.operation !== operation) return
+		this.phase = operation.kind === 'activation' ? 'refreshing' : 'processing'
+
+		if (operation.kind === 'prepare-release') {
+			await this.prepareReleaseThenFinish(operation)
+			return
+		}
+
+		if (operation.kind === 'manual') {
+			await this.refreshHasChanges(true)
+			if (this.hasChanges) {
+				if (!operation.choice) throw new Error('The manual Git operation has no selected action.')
+				await this.validateRepository()
+				await this.applyChoice(operation.choice)
+			}
+		}
+
+		await this.pullThenFinish(operation, operation.kind === 'activation')
+	}
+
+	private async continueAfterChanges(operation: ActiveOperation): Promise<void> {
+		if (this.operation !== operation || !operation.choice) return
+		await this.validateRepository()
+		if (this.operation !== operation) return
+		await this.applyChoice(operation.choice)
+		if (this.operation !== operation) return
+		await this.pullThenFinish(operation, false)
+	}
+
+	private async prepareReleaseThenFinish(operation: ActiveOperation): Promise<void> {
+		if (this.operation !== operation) return
+		await this.refreshHasChanges(true)
+		if (this.hasChanges) {
+			throw new Error('Save or discard local changes before preparing a release.')
+		}
+
+		const prePullHead = await this.revParse('HEAD')
+		try {
+			await this.pullOnce()
+		} catch (error) {
+			if (error instanceof CommandError && (await this.hasMergeConflict())) {
+				await this.handlePullMergeConflict(prePullHead)
+				return
+			}
+			throw error
+		}
+		if (this.operation !== operation || this.runtime.fatal) return
+
+		await this.pushAheadBranch()
+		if (this.operation !== operation) return
+		await this.fetchCurrentUpstream()
+		await this.validateRepository()
+
+		const personalHead = await this.revParse('HEAD')
+		const personalRemoteHead = await this.revParse(this.config.personalUpstream)
+		if (personalHead !== personalRemoteHead) {
+			throw new Error('The personal branch was not fully published before release preparation.')
+		}
+
+		const unreleasedCount = await this.commitCount(
+			`${this.config.currentUpstream}..${personalHead}`
+		)
+		if (unreleasedCount === 0) {
+			this.canPrepareRelease = false
+			this.prepareEligibilityRefreshAt = this.now()
+			await this.finishForContentChange(operation)
+			return
+		}
+
+		const currentRemoteHead = await this.revParse(this.config.currentUpstream)
+		const currentLocalRef = `refs/heads/${this.config.currentBranch}`
+		const currentLocalHead = await this.revParse(currentLocalRef)
+		if ((await this.commitCount(`${this.config.currentUpstream}..${currentLocalRef}`)) > 0) {
+			throw new Error(
+				`The local release branch ${this.config.currentBranch} has unpublished commits. Publish or remove them before preparing a release.`
+			)
+		}
+
+		const remoteUrlDigest = await this.validatedRemoteUrlDigest()
+		const remoteHeads = await this.readReleaseRemoteHeads()
+		if (remoteHeads.current !== currentRemoteHead || remoteHeads.personal !== personalRemoteHead) {
+			throw new Error('The release branches changed remotely while Bosun was preparing them.')
+		}
+
+		const journal: PrepareReleaseJournal = {
+			version: PREPARE_JOURNAL_VERSION,
+			currentBranch: this.config.currentBranch,
+			personalBranch: this.config.personalBranch,
+			remote: this.config.currentUpstreamRemote,
+			currentRemoteBranch: this.config.currentUpstreamBranch,
+			personalRemoteBranch: this.config.personalUpstreamBranch,
+			remoteUrlDigest,
+			oldCurrentRemoteHead: currentRemoteHead,
+			oldPersonalRemoteHead: personalRemoteHead,
+			oldCurrentLocalHead: currentLocalHead,
+			resultHead: null
+		}
+		await this.writePrepareJournal(journal)
+
+		let resultHead: string
+		try {
+			resultHead = await this.buildPrepareResult(currentRemoteHead, personalHead)
+		} catch (error) {
+			if (error instanceof PrepareMergeConflictError) {
+				await this.cleanupPrepareArtifacts()
+				await this.publishMergeConflict(personalHead, this.config.currentUpstreamBranch)
+				return
+			}
+			throw error
+		}
+
+		journal.resultHead = resultHead
+		await this.writePrepareJournal(journal)
+		await this.publishPreparedRelease(journal)
+		await this.alignPublishedRelease(journal)
+
+		this.canPrepareRelease = false
+		this.prepareEligibilityRefreshAt = this.now()
+		await this.finishForContentChange(operation, () => this.cleanupPrepareArtifacts())
+	}
+
+	private async finishForContentChange(
+		operation: ActiveOperation,
+		finalize: () => Promise<void> = async () => {}
+	): Promise<void> {
+		if (!operation.contentBaseline) {
+			throw new Error('Bosun did not capture the project content before the Git operation.')
+		}
+		const finalContent = await this.projectContentDigest()
+		if (this.operation !== operation || this.runtime.fatal || this.disposed) return
+		if (finalContent === operation.contentBaseline) {
+			await this.completeWithoutRestart(operation, async () => {
+				await finalize()
+				await this.cleanupContentRefreshJournal()
+			})
+			return
+		}
+		await this.installProject()
+		if (this.operation !== operation) return
+		const reloadToken = this.randomId()
+		await this.writeContentRefreshJournal({
+			version: CONTENT_REFRESH_JOURNAL_VERSION,
+			baseline: operation.contentBaseline,
+			installedContent: await this.projectContentDigest(),
+			reloadToken
+		})
+		if (this.operation !== operation) return
+		await this.completeAndRestart(operation, finalize, reloadToken)
+	}
+
+	private async fetchCurrentUpstream(): Promise<void> {
+		await this.git(['fetch', '--no-tags', this.config.currentUpstreamRemote])
+		await this.revParse('--verify', this.config.currentUpstream)
+	}
+
+	private async buildPrepareResult(currentHead: string, personalHead: string): Promise<string> {
+		const isFastForward =
+			(
+				await this.git(['merge-base', '--is-ancestor', currentHead, personalHead], {
+					acceptedExitCodes: [0, 1]
+				})
+			).exitCode === 0
+		if (isFastForward) {
+			await this.git(['update-ref', PREPARE_RESULT_REF, personalHead])
+			return personalHead
+		}
+
+		try {
+			await access(this.prepareWorkspacePath)
+			throw new Error(
+				`The prepare workspace already exists at ${this.prepareWorkspacePath}. Restart Bosun so it can recover it.`
+			)
+		} catch (error) {
+			if (!isNodeError(error, 'ENOENT')) throw error
+		}
+
+		await this.git([
+			'clone',
+			'--shared',
+			'--no-checkout',
+			'--no-hardlinks',
+			this.config.projectDir,
+			this.prepareWorkspacePath
+		])
+		await this.gitInPrepareWorkspace(['checkout', '--detach', '--quiet', currentHead])
+
+		const features = await this.gitFeatures()
+		try {
+			await this.gitInPrepareWorkspace([
+				'merge',
+				'--no-ff',
+				'--no-commit',
+				'--no-edit',
+				'--no-gpg-sign',
+				'--no-verify-signatures',
+				`--strategy=${features.ortStrategy ? 'ort' : 'recursive'}`,
+				personalHead
+			])
+		} catch (error) {
+			if (error instanceof CommandError) {
+				const unmerged = await this.gitInPrepareWorkspace(['ls-files', '-u'])
+				if (unmerged.stdout.trim()) throw new PrepareMergeConflictError()
+			}
+			throw error
+		}
+
+		const userName = (await this.git(['config', '--get', 'user.name'])).stdout.trim()
+		const userEmail = (await this.git(['config', '--get', 'user.email'])).stdout.trim()
+		if (!userName || !userEmail) {
+			throw new Error('Git user.name and user.email are required to prepare a release.')
+		}
+		await this.gitInPrepareWorkspace([
+			'-c',
+			`user.name=${userName}`,
+			'-c',
+			`user.email=${userEmail}`,
+			'commit',
+			'--no-verify',
+			'--no-gpg-sign',
+			'-m',
+			`[BOSUN] [Merge] Merge ${this.config.personalBranch} into ${this.config.currentBranch}`
+		])
+		const resultHead = (
+			await this.gitInPrepareWorkspace(['rev-parse', '--verify', 'HEAD'])
+		).stdout.trim()
+		await this.git([
+			'fetch',
+			'--no-tags',
+			this.prepareWorkspacePath,
+			`+${resultHead}:${PREPARE_RESULT_REF}`
+		])
+		await rm(this.prepareWorkspacePath, { recursive: true, force: true })
+		return resultHead
+	}
+
+	private gitInPrepareWorkspace(args: readonly string[]): Promise<CommandResult> {
+		return this.git(['-C', this.prepareWorkspacePath, ...args])
+	}
+
+	private async publishPreparedRelease(journal: PrepareReleaseJournal): Promise<void> {
+		if (!journal.resultHead) throw new Error('The prepared release does not have a result commit.')
+		await this.assertReleaseBranchNotCheckedOut()
+		if ((await this.validatedRemoteUrlDigest()) !== journal.remoteUrlDigest) {
+			throw new Error('The shared upstream remote URL changed during release preparation.')
+		}
+		await this.git([
+			'push',
+			'--atomic',
+			'--no-verify',
+			`--force-with-lease=refs/heads/${journal.currentRemoteBranch}:${journal.oldCurrentRemoteHead}`,
+			`--force-with-lease=refs/heads/${journal.personalRemoteBranch}:${journal.oldPersonalRemoteHead}`,
+			journal.remote,
+			`${PREPARE_RESULT_REF}:refs/heads/${journal.currentRemoteBranch}`,
+			`${PREPARE_RESULT_REF}:refs/heads/${journal.personalRemoteBranch}`
+		])
+
+		const remoteHeads = await this.readReleaseRemoteHeads()
+		if (remoteHeads.current !== journal.resultHead || remoteHeads.personal !== journal.resultHead) {
+			throw new Error('The remote did not retain the complete atomic release publication.')
+		}
+	}
+
+	private async alignPublishedRelease(journal: PrepareReleaseJournal): Promise<void> {
+		if (!journal.resultHead) throw new Error('The published release has no result commit.')
+		await this.assertReleaseBranchNotCheckedOut()
+		await this.git(['fetch', '--no-tags', journal.remote])
+		const localPersonalHead = await this.revParse('HEAD')
+		if (
+			localPersonalHead !== journal.oldPersonalRemoteHead &&
+			localPersonalHead !== journal.resultHead
+		) {
+			throw new Error('The local personal branch changed during release publication.')
+		}
+		const localCurrentHead = await this.revParse(`refs/heads/${journal.currentBranch}`)
+		if (
+			localCurrentHead !== journal.oldCurrentLocalHead &&
+			localCurrentHead !== journal.resultHead
+		) {
+			throw new Error('The local release branch changed during release publication.')
+		}
+
+		if (localPersonalHead !== journal.resultHead) {
+			await this.git(['merge', '--ff-only', PREPARE_RESULT_REF])
+		}
+		if (localCurrentHead !== journal.resultHead) {
+			await this.git([
+				'update-ref',
+				`refs/heads/${journal.currentBranch}`,
+				journal.resultHead,
+				localCurrentHead
+			])
+		}
+	}
+
+	private async commitCount(revisionRange: string): Promise<number> {
+		const count = Number((await this.git(['rev-list', '--count', revisionRange])).stdout.trim())
+		if (!Number.isSafeInteger(count) || count < 0) {
+			throw new Error(`Git returned an invalid commit count for ${revisionRange}.`)
+		}
+		return count
+	}
+
+	private async pullThenFinish(
+		operation: ActiveOperation,
+		allowChangesDialog: boolean
+	): Promise<void> {
+		if (this.operation !== operation) return
+		await this.validateRepository()
+		if (this.operation !== operation) return
+		const prePullHead = await this.revParse('HEAD')
+
+		try {
+			await this.pullOnce()
+		} catch (error) {
+			if (error instanceof CommandError) {
+				const output = `${error.result.stdout}\n${error.result.stderr}`
+				if (allowChangesDialog && LOCAL_CHANGES_REFUSAL.some((pattern) => pattern.test(output))) {
+					this.phase = 'awaiting-changes'
+					this.hasChanges = true
+					return
+				}
+				if (await this.hasMergeConflict()) {
+					await this.handlePullMergeConflict(prePullHead)
+					return
+				}
+			}
+			throw error
+		}
+
+		if (this.operation !== operation) return
+		await this.fetchCurrentUpstream()
+		if (this.operation !== operation) return
+		const preCurrentMergeHead = await this.revParse('HEAD')
+		const currentHead = await this.revParse(this.config.currentUpstream)
+		try {
+			await this.mergeCurrentUpstreamOnce(currentHead)
+		} catch (error) {
+			if (error instanceof CommandError) {
+				const output = `${error.result.stdout}\n${error.result.stderr}`
+				if (allowChangesDialog && LOCAL_CHANGES_REFUSAL.some((pattern) => pattern.test(output))) {
+					this.phase = 'awaiting-changes'
+					this.hasChanges = true
+					return
+				}
+				if (await this.hasMergeConflict()) {
+					await this.handleCurrentMergeConflict(preCurrentMergeHead, currentHead)
+					return
+				}
+			}
+			throw error
+		}
+
+		if (this.operation !== operation || this.runtime.fatal) return
+		await this.pushAheadBranch()
+		if (this.operation !== operation) return
+		await this.updatePrepareEligibilityFromFetchedRefs(currentHead)
+		if (this.operation !== operation) return
+		await this.finishForContentChange(operation)
+	}
+
+	private async pullOnce(): Promise<void> {
+		const features = await this.gitFeatures()
+		const pullArguments = [
+			'pull',
+			'--no-rebase',
+			'--ff',
+			'--no-commit',
+			'--no-squash',
+			'--no-edit',
+			'--no-gpg-sign',
+			'--no-verify-signatures',
+			`--strategy=${features.ortStrategy ? 'ort' : 'recursive'}`,
+			this.config.personalUpstreamRemote,
+			this.config.personalUpstreamBranch
+		]
+		if (features.mergeAutostashOption) pullArguments.splice(4, 0, '--no-autostash')
+		await this.git(pullArguments)
+
+		// `--no-commit` makes a divergent pull stop with MERGE_HEAD before creating its commit.
+		// Create that commit once with its final Bosun subject, eliminating an unlabeled-then-amend
+		// crash window. Fast-forwards still complete normally and have no MERGE_HEAD.
+		await this.commitPendingMerge(
+			`[BOSUN] [Merge] Merge ${this.config.personalUpstream} into ${this.config.personalBranch}`
+		)
+	}
+
+	private async mergeCurrentUpstreamOnce(currentHead: string): Promise<void> {
+		const features = await this.gitFeatures()
+		const mergeArguments = [
+			'merge',
+			'--ff',
+			'--no-commit',
+			'--no-squash',
+			'--no-edit',
+			'--no-gpg-sign',
+			'--no-verify-signatures',
+			`--strategy=${features.ortStrategy ? 'ort' : 'recursive'}`,
+			currentHead
+		]
+		if (features.mergeAutostashOption) mergeArguments.splice(4, 0, '--no-autostash')
+		await this.git(mergeArguments)
+		await this.commitPendingMerge(
+			`[BOSUN] [Merge] Merge ${this.config.currentUpstream} into ${this.config.personalBranch}`
+		)
+	}
+
+	private async commitPendingMerge(subject: string): Promise<void> {
+		if (!(await this.gitPathExists('MERGE_HEAD'))) return
+		await this.git(['commit', '--no-verify', '--no-gpg-sign', '-m', subject])
+	}
+
+	private async pushAheadBranch(): Promise<void> {
+		const counts = (
+			await this.git([
+				'rev-list',
+				'--left-right',
+				'--count',
+				`HEAD...${this.config.personalUpstream}`
+			])
+		).stdout
+			.trim()
+			.split(/\s+/)
+			.map(Number)
+		if (counts.length !== 2 || counts.some((count) => !Number.isSafeInteger(count))) {
+			throw new Error('Git returned invalid ahead/behind counts for the configured upstream.')
+		}
+		const [ahead, behind] = counts
+		if (behind > 0) {
+			throw new Error('The configured branch is still behind its upstream after pulling.')
+		}
+		if (ahead === 0) return
+
+		await this.git([
+			'push',
+			'--no-verify',
+			this.config.personalUpstreamRemote,
+			`HEAD:refs/heads/${this.config.personalUpstreamBranch}`
+		])
+	}
+
+	private async applyChoice(choice: ChangeChoice): Promise<void> {
+		if (choice.action === 'discard') {
+			await this.git([
+				'stash',
+				'push',
+				'--include-untracked',
+				'-m',
+				`[BOSUN] Discard before refresh ${new Date(this.now()).toISOString()}`
+			])
+			this.hasChanges = false
+			this.changeRefreshAt = this.now()
+			return
+		}
+
+		const normalized = this.normalizeChoice(choice)
+		if (!normalized.description) throw new Error('A description is required when saving changes.')
+		await this.git(['add', '-A'])
+		const staged = await this.git(['diff', '--cached', '--quiet'], {
+			acceptedExitCodes: [0, 1]
+		})
+		if (staged.exitCode === 0) {
+			throw new Error('There are no changes to save or discard.')
+		}
+
+		await this.git([
+			'commit',
+			'--no-verify',
+			'--no-gpg-sign',
+			'-m',
+			`[BOSUN] ${normalized.description}`
+		])
+		this.hasChanges = false
+		this.changeRefreshAt = this.now()
+	}
+
+	private validateChoice(choice: ChangeChoice): void {
+		if (choice.action !== 'save') return
+		const normalized = this.normalizeChoice(choice)
+		if (!normalized.description) throw new Error('Describe your changes before saving.')
+	}
+
+	private normalizeChoice(choice: ChangeChoice): ChangeChoice {
+		return {
+			action: choice.action,
+			description: choice.description?.trim().replace(/\s+/g, ' ')
+		}
+	}
+
+	private assertManualOperationAvailable(): void {
+		if (!this.operation && this.phase === 'idle') return
+		throw new Error('Another Bosun Git operation is already in progress.')
+	}
+
+	private async hasMergeConflict(): Promise<boolean> {
+		const unmerged = await this.git(['ls-files', '-u'])
+		// A clean `pull --no-commit` intentionally has MERGE_HEAD until Bosun creates its labelled
+		// merge commit. Only unmerged index entries prove a conflict; treating MERGE_HEAD itself as
+		// one would misclassify an unrelated commit failure and publish a bogus conflict branch.
+		return Boolean(unmerged.stdout.trim())
+	}
+
+	private async handlePullMergeConflict(prePullHead: string): Promise<void> {
+		try {
+			await this.git(['merge', '--abort'])
+			const currentHead = await this.revParse('HEAD')
+			if (currentHead !== prePullHead) {
+				throw new Error('Aborting the failed merge did not restore the pre-merge commit.')
+			}
+
+			await this.publishMergeConflict(prePullHead, this.config.personalUpstreamBranch)
+		} catch (error) {
+			if (this.runtime.fatal?.kind === 'merge-conflict') return
+			throw new Error('Bosun could not safely publish the merge-conflict branch.', { cause: error })
+		}
+	}
+
+	private async handleCurrentMergeConflict(
+		preMergeHead: string,
+		currentHead: string
+	): Promise<void> {
+		try {
+			await this.git(['merge', '--abort'])
+			const restoredHead = await this.revParse('HEAD')
+			if (restoredHead !== preMergeHead) {
+				throw new Error('Aborting the failed merge did not restore the pre-merge commit.')
+			}
+
+			await this.pushAheadBranch()
+			await this.publishMergeConflict(currentHead, this.config.personalUpstreamBranch)
+		} catch (error) {
+			if (this.runtime.fatal?.kind === 'merge-conflict') return
+			throw new Error('Bosun could not safely publish the merge-conflict branch.', { cause: error })
+		}
+	}
+
+	private async publishMergeConflict(sourceHead: string, baseBranch: string): Promise<void> {
+		const remoteUrl = (
+			await this.git(['config', '--get', `remote.${this.config.personalUpstreamRemote}.url`])
+		).stdout.trim()
+		const repository = parseGitHubRepository(remoteUrl)
+		if (!repository) {
+			throw new Error(`The upstream remote is not a supported GitHub URL: ${remoteUrl}`)
+		}
+
+		const conflictBranch = this.createConflictBranchName(baseBranch)
+		const prUrl = createPullRequestUrl(repository, baseBranch, conflictBranch)
+		await this.git(['branch', conflictBranch, sourceHead])
+		await this.git([
+			'push',
+			'--no-verify',
+			this.config.personalUpstreamRemote,
+			`${sourceHead}:refs/heads/${conflictBranch}`
+		])
+
+		await this.setFatal(
+			'merge-conflict',
+			'There was a merge conflict during refresh. Please let the dev team know that it needs resolving with the provided pull-request link. Unfortunately, you will not be able to proceed until this is resolved by them. Restart Bosun after the team has confirmed that the conflict has been resolved.',
+			prUrl
+		)
+	}
+
+	private createConflictBranchName(baseBranch: string): string {
+		const timestamp = new Date(this.now()).toISOString().replace(/[-:.]/g, '')
+		const suffix = randomBytes(4).toString('hex')
+		return `bosun-conflict/${baseBranch}/${timestamp}-${suffix}`
+	}
+
+	private async contentRefreshJournalExists(): Promise<boolean> {
+		try {
+			await access(this.contentRefreshJournalPath)
+			return true
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) return false
+			throw error
+		}
+	}
+
+	private async recoverContentRefresh(): Promise<void> {
+		await this.validateRepository()
+		const journal = await this.readContentRefreshJournal()
+		const currentContent = await this.projectContentDigest()
+		if (currentContent === journal.baseline) {
+			await this.validateRepository()
+			await this.cleanupContentRefreshJournal()
+			await this.resumeWrites()
+			return
+		}
+
+		if (journal.installedContent === currentContent && journal.reloadToken) {
+			if (this.runtime.reloadToken !== journal.reloadToken) {
+				this.runtime.reloadToken = journal.reloadToken
+				await this.queueRuntimePersist()
+			}
+			await this.validateRepository()
+			await this.cleanupContentRefreshJournal()
+			await this.resumeWrites()
+			return
+		}
+
+		await this.installProject()
+		const installedContent = await this.projectContentDigest()
+		const reloadToken = this.randomId()
+		await this.writeContentRefreshJournal({
+			version: CONTENT_REFRESH_JOURNAL_VERSION,
+			baseline: journal.baseline,
+			installedContent,
+			reloadToken
+		})
+		await this.validateRepository()
+		this.runtime.reloadToken = reloadToken
+		await this.queueRuntimePersist()
+		const scheduled = await this.scheduleRestart(this.config.restartExitCode)
+		if (!scheduled) throw new Error('The managed Bosun backend restart is not available.')
+		this.phase = 'restarting'
+	}
+
+	private async readContentRefreshJournal(): Promise<ContentRefreshJournal> {
+		let value: unknown
+		try {
+			value = JSON.parse(await readFile(this.contentRefreshJournalPath, 'utf8'))
+		} catch (error) {
+			throw new Error('Bosun could not read the interrupted project refresh safely.', {
+				cause: error
+			})
+		}
+		if (!isContentRefreshJournal(value)) {
+			throw new Error('The interrupted project refresh record is invalid.')
+		}
+		return value
+	}
+
+	private writeContentRefreshJournal(journal: ContentRefreshJournal): Promise<void> {
+		return writeDurableJson(this.contentRefreshJournalPath, journal)
+	}
+
+	private async cleanupContentRefreshJournal(): Promise<void> {
+		await unlink(this.contentRefreshJournalPath).catch((error: unknown) => {
+			if (!isNodeError(error, 'ENOENT')) throw error
+		})
+		await syncDirectory(path.dirname(this.contentRefreshJournalPath))
+	}
+
+	private async prepareJournalExists(): Promise<boolean> {
+		try {
+			await access(this.prepareJournalPath)
+			return true
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) return false
+			throw error
+		}
+	}
+
+	private async recoverPrepareRelease(): Promise<void> {
+		await this.validateRepository()
+		if (!(await this.contentRefreshJournalExists())) {
+			throw new Error('The interrupted release is missing its project-content baseline.')
+		}
+		const journal = await this.readPrepareJournal()
+		this.assertJournalMatchesConfig(journal, await this.validatedRemoteUrlDigest())
+		const remoteHeads = await this.readReleaseRemoteHeads()
+		const remoteIsOld =
+			remoteHeads.current === journal.oldCurrentRemoteHead &&
+			remoteHeads.personal === journal.oldPersonalRemoteHead
+		const remoteIsResult =
+			journal.resultHead !== null &&
+			remoteHeads.current === journal.resultHead &&
+			remoteHeads.personal === journal.resultHead
+
+		if (remoteIsOld) {
+			this.runtime.fatal = null
+			await this.queueRuntimePersist()
+			await this.cleanupPrepareArtifacts()
+			await this.recoverContentRefresh()
+			return
+		}
+		if (!remoteIsResult || !journal.resultHead) {
+			throw new Error(
+				'Bosun found an interrupted release publication, but the two remote branches are not both at their recorded old commits or both at the prepared result. Bosun will not guess which remote state is safe.'
+			)
+		}
+
+		await this.refreshHasChanges(true)
+		if (this.hasChanges) {
+			throw new Error(
+				'Bosun published a release before shutdown, but local changes now prevent safe recovery.'
+			)
+		}
+		this.runtime.fatal = null
+		await this.git(['fetch', '--no-tags', journal.remote])
+		await this.revParse('--verify', journal.resultHead)
+		await this.git(['update-ref', PREPARE_RESULT_REF, journal.resultHead])
+		await this.alignPublishedRelease(journal)
+
+		this.canPrepareRelease = false
+		const completedAt = this.now()
+		this.runtime.firstActivationCompleted = true
+		this.runtime.lastCompletedActivationAt = completedAt
+		this.hasChanges = false
+		this.changeRefreshAt = completedAt
+		await this.queueRuntimePersist()
+		await this.cleanupPrepareArtifacts()
+		await this.recoverContentRefresh()
+	}
+
+	private async readPrepareJournal(): Promise<PrepareReleaseJournal> {
+		let value: unknown
+		try {
+			value = JSON.parse(await readFile(this.prepareJournalPath, 'utf8'))
+		} catch (error) {
+			throw new Error('Bosun could not read the interrupted release journal safely.', {
+				cause: error
+			})
+		}
+		if (!isPrepareReleaseJournal(value)) {
+			throw new Error('The interrupted release journal is invalid.')
+		}
+		return value
+	}
+
+	private assertJournalMatchesConfig(
+		journal: PrepareReleaseJournal,
+		remoteUrlDigest: string
+	): void {
+		if (
+			journal.currentBranch !== this.config.currentBranch ||
+			journal.personalBranch !== this.config.personalBranch ||
+			journal.remote !== this.config.currentUpstreamRemote ||
+			journal.currentRemoteBranch !== this.config.currentUpstreamBranch ||
+			journal.personalRemoteBranch !== this.config.personalUpstreamBranch ||
+			journal.remoteUrlDigest !== remoteUrlDigest
+		) {
+			throw new Error(
+				'The interrupted release journal does not match the configured release and personal branches.'
+			)
+		}
+	}
+
+	private async writePrepareJournal(journal: PrepareReleaseJournal): Promise<void> {
+		await writeDurableJson(this.prepareJournalPath, journal)
+	}
+
+	private async cleanupPrepareArtifacts(): Promise<void> {
+		await rm(this.prepareWorkspacePath, { recursive: true, force: true })
+		await this.git(['update-ref', '-d', PREPARE_RESULT_REF])
+		await unlink(this.prepareJournalPath).catch((error: unknown) => {
+			if (!isNodeError(error, 'ENOENT')) throw error
+		})
+		await syncDirectory(path.dirname(this.prepareJournalPath))
+	}
+
+	private async readReleaseRemoteHeads(): Promise<{
+		current: string
+		personal: string
+	}> {
+		const currentRef = `refs/heads/${this.config.currentUpstreamBranch}`
+		const personalRef = `refs/heads/${this.config.personalUpstreamBranch}`
+		const output = (
+			await this.git([
+				'ls-remote',
+				'--heads',
+				this.config.currentUpstreamRemote,
+				currentRef,
+				personalRef
+			])
+		).stdout
+		const heads = new Map<string, string>()
+		for (const line of output.trim().split('\n')) {
+			if (!line) continue
+			const [objectId, ref, extra] = line.trim().split(/\s+/)
+			if (!objectId || !ref || extra || heads.has(ref)) {
+				throw new Error('Git returned invalid remote branch information.')
+			}
+			heads.set(ref, objectId)
+		}
+		const current = heads.get(currentRef)
+		const personal = heads.get(personalRef)
+		if (!current || !personal) {
+			throw new Error('The configured release or personal branch does not exist remotely.')
+		}
+		return { current, personal }
+	}
+
+	private async completeAndRestart(
+		operation: ActiveOperation,
+		finalize: () => Promise<void> = async () => {},
+		reloadToken = this.randomId()
+	): Promise<void> {
+		if (this.operation !== operation || this.runtime.fatal) return
+		const completedAt = this.now()
+		this.runtime.firstActivationCompleted = true
+		this.runtime.lastCompletedActivationAt = completedAt
+		this.runtime.reloadToken = reloadToken
+		this.hasChanges = false
+		this.canPrepareRelease = false
+		this.changeRefreshAt = completedAt
+		await this.queueRuntimePersist()
+		if (this.operation !== operation || this.runtime.fatal) return
+		await finalize()
+		if (this.operation !== operation || this.runtime.fatal) return
+
+		const scheduled = await this.scheduleRestart(this.config.restartExitCode)
+		if (!scheduled) throw new Error('The managed Bosun backend restart is not available.')
+		if (this.operation !== operation || this.runtime.fatal) return
+		this.phase = 'restarting'
+	}
+
+	private async completeWithoutRestart(
+		operation: ActiveOperation,
+		finalize: () => Promise<void> = async () => {}
+	): Promise<void> {
+		if (this.operation !== operation || this.runtime.fatal || this.disposed) return
+		await this.refreshHasChanges(true)
+		if (this.operation !== operation || this.runtime.fatal || this.disposed) return
+
+		const completedAt = this.now()
+		this.runtime.firstActivationCompleted = true
+		this.runtime.lastCompletedActivationAt = completedAt
+		this.changeRefreshAt = completedAt
+		await this.queueRuntimePersist()
+		if (this.operation !== operation || this.runtime.fatal || this.disposed) return
+		await finalize()
+		if (this.operation !== operation || this.runtime.fatal || this.disposed) return
+
+		// Keep backend admission blocked until the cross-process gate is gone. Once unlock resolves,
+		// finish synchronously so no ordinary request can enter between the two states.
+		await this.resumeWrites()
+		if (this.operation !== operation || this.runtime.fatal || this.disposed) {
+			// Shutdown or a concurrent fatal transition may have won while the filesystem operation was
+			// in flight. Restore the gate before yielding instead of reopening repository writes.
+			await this.settleWrites()
+			return
+		}
+		this.operation = null
+		this.operationId = null
+		this.deferredReason = null
+		this.phase = 'idle'
+	}
+
+	private async validateRepository(): Promise<void> {
+		if (this.config.currentBranch === this.config.personalBranch) {
+			throw new RepositoryValidationError(
+				'BOSUN_CURRENT_BRANCH and BOSUN_PERSONAL_BRANCH must name different branches.'
+			)
+		}
+		if (this.config.currentUpstreamRemote !== this.config.personalUpstreamRemote) {
+			throw new RepositoryValidationError(
+				'The release and personal branches must use the same upstream remote.'
+			)
+		}
+		if (this.config.currentUpstreamBranch === this.config.personalUpstreamBranch) {
+			throw new RepositoryValidationError(
+				'The release and personal branches must track different remote branches.'
+			)
+		}
+		if (
+			this.config.currentUpstream !==
+				`${this.config.currentUpstreamRemote}/${this.config.currentUpstreamBranch}` ||
+			this.config.personalUpstream !==
+				`${this.config.personalUpstreamRemote}/${this.config.personalUpstreamBranch}`
+		) {
+			throw new RepositoryValidationError(
+				'The configured upstream names do not match their remote and branch fields.'
+			)
+		}
+
+		let configuredRoot: string
+		let actualRoot: string
+		try {
+			configuredRoot = await realpath(this.config.projectDir)
+			actualRoot = await realpath((await this.git(['rev-parse', '--show-toplevel'])).stdout.trim())
+		} catch (error) {
+			throw new RepositoryValidationError(
+				'Bosun is not running in a valid Git repository.',
+				'general',
+				{
+					cause: error
+				}
+			)
+		}
+		if (configuredRoot !== actualRoot) {
+			throw new RepositoryValidationError(
+				'Git resolved a different repository than the Bosun project.'
+			)
+		}
+
+		const gitMarker = path.join(configuredRoot, '.git')
+		try {
+			const marker = await lstat(gitMarker)
+			if (!marker.isDirectory() || marker.isSymbolicLink())
+				throw new Error('.git is not a directory')
+			const markerRealPath = await realpath(gitMarker)
+			if (
+				path.dirname(markerRealPath) !== configuredRoot ||
+				path.basename(markerRealPath) !== '.git'
+			) {
+				throw new Error('The .git marker resolves outside the project.')
+			}
+		} catch (error) {
+			throw new RepositoryValidationError(
+				'Linked worktrees and submodule checkouts are not supported by Bosun Git mode.',
+				'general'
+			)
+		}
+
+		const superproject = (
+			await this.git(['rev-parse', '--show-superproject-working-tree'])
+		).stdout.trim()
+		if (superproject) {
+			throw new RepositoryValidationError(
+				'Submodule checkouts are not supported by Bosun Git mode.'
+			)
+		}
+		const trackedSubmodules = await this.git(['ls-files', '--stage'])
+		if (trackedSubmodules.stdout.split('\n').some((line) => line.startsWith('160000 '))) {
+			throw new RepositoryValidationError(
+				'Repositories containing tracked submodules are not supported by Bosun Git mode.'
+			)
+		}
+		await this.revParse('--verify', 'HEAD').catch((error) => {
+			throw new RepositoryValidationError(
+				'The repository does not have a committed HEAD.',
+				'general',
+				{
+					cause: error
+				}
+			)
+		})
+
+		const branchResult = await this.git(['symbolic-ref', '--quiet', '--short', 'HEAD'], {
+			acceptedExitCodes: [0, 1]
+		})
+		const branch = branchResult.exitCode === 0 ? branchResult.stdout.trim() : ''
+		if (!branch) throw new RepositoryValidationError('Bosun cannot run from a detached HEAD.')
+		if (branch !== this.config.personalBranch) {
+			throw new RepositoryValidationError(
+				`Bosun is on branch "${branch}", but Git mode requires the personal branch "${this.config.personalBranch}". Restart Bosun after running: git switch ${this.config.personalBranch}`,
+				'branch-mismatch'
+			)
+		}
+
+		await this.assertReleaseBranchNotCheckedOut()
+		await this.validateRemotePublicationTarget()
+
+		const upstreamResult = await this.git([
+			'rev-parse',
+			'--abbrev-ref',
+			'--symbolic-full-name',
+			'@{upstream}'
+		])
+		if (upstreamResult.stdout.trim() !== this.config.personalUpstream) {
+			throw new RepositoryValidationError(
+				`The personal branch must track ${this.config.personalUpstream}, but it tracks ${upstreamResult.stdout.trim() || 'nothing'}.`
+			)
+		}
+		await this.revParse('--verify', this.config.personalUpstream)
+		await this.revParse('--verify', `refs/heads/${this.config.currentBranch}`)
+		await this.revParse('--verify', this.config.currentUpstream)
+
+		const currentUpstream = (
+			await this.git([
+				'for-each-ref',
+				'--format=%(upstream:short)',
+				`refs/heads/${this.config.currentBranch}`
+			])
+		).stdout.trim()
+		if (currentUpstream !== this.config.currentUpstream) {
+			throw new RepositoryValidationError(
+				`The release branch must track ${this.config.currentUpstream}, but it tracks ${currentUpstream || 'nothing'}.`
+			)
+		}
+
+		for (const gitPath of [
+			'MERGE_HEAD',
+			'rebase-merge',
+			'rebase-apply',
+			'CHERRY_PICK_HEAD',
+			'REVERT_HEAD',
+			'BISECT_START',
+			'BISECT_LOG',
+			'sequencer'
+		]) {
+			if (await this.gitPathExists(gitPath)) {
+				throw new RepositoryValidationError(
+					'A Git merge, rebase, cherry-pick, revert, bisect, or sequenced operation is already in progress. Resolve it and restart Bosun.'
+				)
+			}
+		}
+	}
+
+	private async assertReleaseBranchNotCheckedOut(): Promise<void> {
+		const worktrees = (await this.git(['worktree', 'list', '--porcelain'])).stdout
+		if (
+			!worktrees
+				.split('\n')
+				.some((line) => line.trim() === `branch refs/heads/${this.config.currentBranch}`)
+		) {
+			return
+		}
+		throw new RepositoryValidationError(
+			`The release branch ${this.config.currentBranch} is checked out in another Git worktree. Remove that worktree and restart Bosun.`
+		)
+	}
+
+	private async validateRemotePublicationTarget(): Promise<string> {
+		const fetchUrls = (
+			await this.git(['remote', 'get-url', '--all', this.config.currentUpstreamRemote])
+		).stdout
+			.trim()
+			.split('\n')
+			.filter(Boolean)
+		const pushUrls = (
+			await this.git(['remote', 'get-url', '--push', '--all', this.config.currentUpstreamRemote])
+		).stdout
+			.trim()
+			.split('\n')
+			.filter(Boolean)
+		if (fetchUrls.length !== 1 || pushUrls.length !== 1 || fetchUrls[0] !== pushUrls[0]) {
+			throw new RepositoryValidationError(
+				'The shared upstream remote must have exactly one fetch URL and one matching push URL.'
+			)
+		}
+		return fetchUrls[0]
+	}
+
+	private async validatedRemoteUrlDigest(): Promise<string> {
+		return createHash('sha256')
+			.update(await this.validateRemotePublicationTarget())
+			.digest('hex')
+	}
+
+	private async gitPathExists(name: string): Promise<boolean> {
+		const rawPath = (await this.git(['rev-parse', '--git-path', name])).stdout.trim()
+		if (!rawPath) return false
+		const resolved = path.isAbsolute(rawPath)
+			? rawPath
+			: path.resolve(this.config.projectDir, rawPath)
+		try {
+			await access(resolved)
+			return true
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) return false
+			throw error
+		}
+	}
+
+	private async projectContentDigest(): Promise<string> {
+		// Git refs and the index can change when Save only records content that is already on disk.
+		// Hash the checkout itself so only a user-visible project-file change requires a restart.
+		const listed = await this.git(['ls-files', '--cached', '--others', '--exclude-standard', '-z'])
+		const listedBytes = listed.stdoutBuffer ?? Buffer.from(listed.stdout)
+		const relativePaths = splitNullDelimitedBuffers(listedBytes)
+		const digest = createHash('sha256')
+		const update = (value: string | Buffer) => {
+			const bytes = typeof value === 'string' ? Buffer.from(value) : value
+			const length = Buffer.allocUnsafe(8)
+			length.writeBigUInt64BE(BigInt(bytes.length))
+			digest.update(length)
+			digest.update(bytes)
+		}
+
+		for (const relativePath of relativePaths) {
+			if (!isRepositoryRelativePath(relativePath)) {
+				throw new Error('Git returned a project path outside the repository.')
+			}
+			const absolutePath = Buffer.concat([
+				Buffer.from(`${this.config.projectDir}${path.sep}`),
+				relativePath
+			])
+
+			update(relativePath)
+			let file: Awaited<ReturnType<typeof lstat>>
+			try {
+				file = await lstat(absolutePath)
+			} catch (error) {
+				if (!isNodeError(error, 'ENOENT')) throw error
+				update('missing')
+				continue
+			}
+
+			if (file.isSymbolicLink()) {
+				update('symlink')
+				update(await readlink(absolutePath, { encoding: 'buffer' }))
+				continue
+			}
+			if (file.isFile()) {
+				update(file.mode & 0o111 ? 'file-executable' : 'file')
+				update(await readFile(absolutePath))
+				continue
+			}
+			update(`other-${file.mode}`)
+		}
+
+		return digest.digest('hex')
+	}
+
+	private async revParse(...revisions: string[]): Promise<string> {
+		return (await this.git(['rev-parse', ...revisions])).stdout.trim()
+	}
+
+	private async git(
+		args: readonly string[],
+		options: { input?: string | Buffer; acceptedExitCodes?: readonly number[] } = {}
+	): Promise<CommandResult> {
+		const operation = this.gitQueue.then(() =>
+			this.command(
+				'git',
+				[
+					'-c',
+					`core.hooksPath=${this.hooksDir}`,
+					'-c',
+					'commit.gpgSign=false',
+					'-c',
+					'tag.gpgSign=false',
+					'-c',
+					'push.gpgSign=false',
+					'-c',
+					'merge.autoEdit=no',
+					'-c',
+					'merge.gpgSign=false',
+					'-c',
+					'merge.autostash=false',
+					'-c',
+					'rebase.autostash=false',
+					...args
+				],
+				{
+					cwd: this.config.projectDir,
+					env: this.nonInteractiveEnvironment(),
+					input: options.input,
+					timeoutMs: GIT_TIMEOUT_MS,
+					acceptedExitCodes: options.acceptedExitCodes
+				}
+			)
+		)
+		this.gitQueue = operation.then(
+			() => undefined,
+			() => undefined
+		)
+		return operation
+	}
+
+	private async prevalidateStart(tabId: string, rejectBusy = false): Promise<boolean> {
+		try {
+			await this.validateRepository()
+			return true
+		} catch (error) {
+			// Another tab can win the operation while this read-only validation is running. Its
+			// operation owns the outcome; otherwise make validation failures visible before the
+			// browser is blurred or asked to persist anything.
+			if (!this.operation && this.phase === 'idle') await this.failFromError(error)
+			else if (rejectBusy) throw new Error('Another Bosun Git operation is already in progress.')
+			this.registerTab(tabId)
+			return false
+		}
+	}
+
+	private gitFeatures(): Promise<GitFeatures> {
+		if (this.gitFeaturesPromise) return this.gitFeaturesPromise
+		this.gitFeaturesPromise = this.git(['version']).then((result) => {
+			const match = /git version (\d+)\.(\d+)(?:\.(\d+))?/i.exec(result.stdout)
+			if (!match)
+				throw new Error(`Could not parse the installed Git version: ${result.stdout.trim()}`)
+			const version = [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)] as const
+			return {
+				mergeAutostashOption: versionAtLeast(version, [2, 27, 0]),
+				ortStrategy: versionAtLeast(version, [2, 34, 0])
+			}
+		})
+		return this.gitFeaturesPromise
+	}
+
+	private nonInteractiveEnvironment(): NodeJS.ProcessEnv {
+		const env: NodeJS.ProcessEnv = {
+			...process.env,
+			CI: '1',
+			LC_ALL: 'C',
+			LANG: 'C',
+			GIT_TERMINAL_PROMPT: '0',
+			GIT_ASKPASS: 'true',
+			SSH_ASKPASS: 'true',
+			GCM_INTERACTIVE: 'Never',
+			GIT_EDITOR: 'true',
+			GIT_SEQUENCE_EDITOR: 'true',
+			GIT_MERGE_AUTOEDIT: 'no',
+			EDITOR: 'true',
+			VISUAL: 'true'
+		}
+		for (const name of [
+			'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',
+			'GIT_PREFIX'
+		]) {
+			delete env[name]
+		}
+		return env
+	}
+
+	private async failFromError(error: unknown): Promise<void> {
+		if (this.phase === 'fatal') return
+		const validation = error instanceof RepositoryValidationError ? error : null
+		const kind = validation?.kind ?? 'general'
+		const message = validation
+			? validation.message
+			: 'Bosun could not refresh the repository. Resolve the Git, network, authentication, package-install, push, or restart problem shown in the console, then restart Bosun.'
+		await this.setFatal(kind, message, null, error)
+	}
+
+	private async setFatal(
+		kind: GitModeFatalKind,
+		message: string,
+		prUrl: string | null = null,
+		error?: unknown
+	): Promise<void> {
+		const title =
+			kind === 'merge-conflict'
+				? 'Merge conflict during refresh'
+				: kind === 'branch-mismatch'
+					? 'Bosun is on the wrong branch'
+					: 'Bosun could not refresh'
+		this.runtime.fatal = { kind, title, message, prUrl }
+		this.phase = 'fatal'
+		this.clearFlushTimer()
+		this.operation = null
+		this.operationId = null
+		this.deferredReason = null
+		if (error === undefined) this.logError(`[Bosun Git mode] ${message}`)
+		else this.logError(`[Bosun Git mode] ${message}`, error)
+		try {
+			await this.queueRuntimePersist()
+		} catch (persistError) {
+			this.logError('[Bosun Git mode] Could not persist the fatal state.', persistError)
+		}
+	}
+}
+
+interface GitHubRepository {
+	host: string
+	owner: string
+	repository: string
+}
+
+export function parseGitHubRepository(remoteUrl: string): GitHubRepository | null {
+	let host: string
+	let pathname: string
+	try {
+		if (/^[^/@:]+@[^:]+:.+/.test(remoteUrl)) {
+			const match = /^[^/@:]+@([^:]+):(.+)$/.exec(remoteUrl)
+			if (!match) return null
+			;[, host, pathname] = match
+		} else {
+			const url = new URL(remoteUrl)
+			if (!['https:', 'http:', 'ssh:', 'git:'].includes(url.protocol)) return null
+			host = url.hostname
+			pathname = url.pathname.replace(/^\//, '')
+		}
+	} catch {
+		return null
+	}
+
+	if (host.toLowerCase() !== 'github.com') return null
+	const parts = pathname
+		.replace(/\.git$/, '')
+		.split('/')
+		.filter(Boolean)
+	if (parts.length !== 2) return null
+	return { host: 'github.com', owner: parts[0], repository: parts[1] }
+}
+
+export function createPullRequestUrl(
+	repository: GitHubRepository,
+	baseBranch: string,
+	headBranch: string
+): string {
+	return `https://${repository.host}/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repository)}/compare/${encodeURIComponent(baseBranch)}...${encodeURIComponent(headBranch)}?expand=1`
+}
+
+function isRuntimeState(value: unknown): value is PersistedRuntimeState {
+	if (!value || typeof value !== 'object') return false
+	const state = value as Partial<PersistedRuntimeState>
+	return (
+		state.version === RUNTIME_STATE_VERSION &&
+		typeof state.launchId === 'string' &&
+		typeof state.firstActivationCompleted === 'boolean' &&
+		(state.lastCompletedActivationAt === null ||
+			typeof state.lastCompletedActivationAt === 'number') &&
+		typeof state.lastRelevantChangeAt === 'number' &&
+		(state.reloadToken === null || typeof state.reloadToken === 'string') &&
+		(state.fatal === null || isFatal(state.fatal))
+	)
+}
+
+function isFatal(value: unknown): value is GitModeFatal {
+	if (!value || typeof value !== 'object') return false
+	const fatal = value as Partial<GitModeFatal>
+	return (
+		(fatal.kind === 'general' ||
+			fatal.kind === 'branch-mismatch' ||
+			fatal.kind === 'merge-conflict') &&
+		typeof fatal.title === 'string' &&
+		typeof fatal.message === 'string' &&
+		(fatal.prUrl === null || typeof fatal.prUrl === 'string')
+	)
+}
+
+function isContentRefreshJournal(value: unknown): value is ContentRefreshJournal {
+	if (!value || typeof value !== 'object') return false
+	const journal = value as Partial<ContentRefreshJournal>
+	const isDigest = (digest: unknown): digest is string =>
+		typeof digest === 'string' && /^[0-9a-f]{64}$/.test(digest)
+	const hasInstalledContent = isDigest(journal.installedContent)
+	const hasReloadToken = typeof journal.reloadToken === 'string' && journal.reloadToken.length > 0
+	return (
+		journal.version === CONTENT_REFRESH_JOURNAL_VERSION &&
+		isDigest(journal.baseline) &&
+		((journal.installedContent === null && journal.reloadToken === null) ||
+			(hasInstalledContent && hasReloadToken))
+	)
+}
+
+function splitNullDelimitedBuffers(value: Buffer): Buffer[] {
+	const unique = new Map<string, Buffer>()
+	let start = 0
+	for (let index = 0; index <= value.length; index += 1) {
+		if (index < value.length && value[index] !== 0) continue
+		if (index > start) {
+			const entry = value.subarray(start, index)
+			unique.set(entry.toString('hex'), entry)
+		}
+		start = index + 1
+	}
+	return [...unique.values()].sort((left, right) => Buffer.compare(left, right))
+}
+
+function isRepositoryRelativePath(value: Buffer): boolean {
+	if (value.length === 0 || value[0] === 0x2f) return false
+	return !value
+		.toString('binary')
+		.split('/')
+		.some((component) => component === '' || component === '..')
+}
+
+function isPrepareReleaseJournal(value: unknown): value is PrepareReleaseJournal {
+	if (!value || typeof value !== 'object') return false
+	const journal = value as Partial<PrepareReleaseJournal>
+	const isObjectId = (objectId: unknown): objectId is string =>
+		typeof objectId === 'string' && /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(objectId)
+	return (
+		journal.version === PREPARE_JOURNAL_VERSION &&
+		typeof journal.currentBranch === 'string' &&
+		Boolean(journal.currentBranch) &&
+		typeof journal.personalBranch === 'string' &&
+		Boolean(journal.personalBranch) &&
+		typeof journal.remote === 'string' &&
+		Boolean(journal.remote) &&
+		typeof journal.currentRemoteBranch === 'string' &&
+		Boolean(journal.currentRemoteBranch) &&
+		typeof journal.personalRemoteBranch === 'string' &&
+		Boolean(journal.personalRemoteBranch) &&
+		typeof journal.remoteUrlDigest === 'string' &&
+		/^[0-9a-f]{64}$/.test(journal.remoteUrlDigest) &&
+		isObjectId(journal.oldCurrentRemoteHead) &&
+		isObjectId(journal.oldPersonalRemoteHead) &&
+		isObjectId(journal.oldCurrentLocalHead) &&
+		(journal.resultHead === null || isObjectId(journal.resultHead))
+	)
+}
+
+async function writeDurableJson(filePath: string, value: unknown): Promise<void> {
+	const directoryPath = path.dirname(filePath)
+	await mkdir(directoryPath, { recursive: true })
+	const temporaryPath = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`
+	let file: Awaited<ReturnType<typeof open>> | null = null
+	try {
+		file = await open(temporaryPath, 'wx', 0o600)
+		await file.writeFile(`${JSON.stringify(value)}\n`, 'utf8')
+		await file.sync()
+		await file.close()
+		file = null
+		await rename(temporaryPath, filePath)
+		await syncDirectory(directoryPath)
+	} finally {
+		await file?.close().catch(() => {})
+		await unlink(temporaryPath).catch(() => {})
+	}
+}
+
+async function syncDirectory(directoryPath: string): Promise<void> {
+	const directory = await open(directoryPath, 'r')
+	try {
+		await directory.sync()
+	} finally {
+		await directory.close()
+	}
+}
+
+function isNodeError(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return error instanceof Error && 'code' in error && error.code === code
+}
+
+function versionAtLeast(
+	actual: readonly [number, number, number],
+	required: readonly [number, number, number]
+): boolean {
+	for (let index = 0; index < actual.length; index += 1) {
+		if (actual[index] > required[index]) return true
+		if (actual[index] < required[index]) return false
+	}
+	return true
+}