@recombine-ai/bosun 0.16.2 → 0.17.1

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

@@ -0,0 +1,1653 @@
+import { execFile } from 'node:child_process'
+import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { promisify } from 'node:util'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { CommandError, runCommand, type CommandRunner } from './command'
+import { RepositoryWriteGate } from './repository-write-gate'
+import { createGitModeService } from './service'
+import type { GitModeConfig, GitModeService, GitModeStatus } from './types'
+
+const execFileAsync = promisify(execFile)
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+	await Promise.all(
+		temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true }))
+	)
+})
+
+describe.sequential('Git mode service', () => {
+	it('validates the repository before asking browsers to flush', async () => {
+		const fixture = await createFixture()
+		await git(fixture.project, ['switch', '-c', 'unexpected-branch'])
+		const settleWrites = vi.fn(async () => {})
+		const service = createTestService(fixture, { settleWrites })
+
+		const status = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+
+		expect(status.phase).toBe('fatal')
+		expect(status.operationId).toBeNull()
+		expect(status.tabNeedsFlush).toBe(false)
+		expect(status.fatal?.kind).toBe('branch-mismatch')
+		expect(settleWrites).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('serializes ancillary Git reads ahead of activation validation', async () => {
+		const fixture = await createFixture()
+		let releaseStatus!: () => void
+		let markStatusStarted!: () => void
+		const statusStarted = new Promise<void>((resolve) => (markStatusStarted = resolve))
+		const statusRelease = new Promise<void>((resolve) => (releaseStatus = resolve))
+		let activeCommands = 0
+		let maximumActiveCommands = 0
+		const observedRunner: CommandRunner = async (executable, args, options) => {
+			activeCommands += 1
+			maximumActiveCommands = Math.max(maximumActiveCommands, activeCommands)
+			try {
+				if (executable === 'git' && args.includes('status')) {
+					markStatusStarted()
+					await statusRelease
+				}
+				return await runCommand(executable, args, options)
+			} finally {
+				activeCommands -= 1
+			}
+		}
+		const service = createTestService(fixture, { runCommand: observedRunner })
+
+		const status = service.status({ tabId: 'tab-a' })
+		await statusStarted
+		const activation = service.activate({ tabId: 'tab-b', reason: 'page-open' })
+		await new Promise((resolve) => setTimeout(resolve, 50))
+		expect(maximumActiveCommands).toBe(1)
+		releaseStatus()
+		await status
+		expect((await activation).phase).toBe('preparing')
+		expect(maximumActiveCommands).toBe(1)
+		await service.dispose()
+	})
+
+	it('finishes shutdown cleanly once an in-flight repository operation has settled', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		let markInstallStarted!: () => void
+		let releaseInstall!: () => void
+		const installStarted = new Promise<void>((resolve) => (markInstallStarted = resolve))
+		const installRelease = new Promise<void>((resolve) => (releaseInstall = resolve))
+		const service = createTestService(fixture, {
+			installProject: async () => {
+				markInstallStarted()
+				await installRelease
+			}
+		})
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		await installStarted
+
+		const disposal = service.dispose()
+		releaseInstall()
+		await expect(disposal).resolves.toBeUndefined()
+	})
+
+	it('locks writers, drains admitted backend work, and revalidates before Git mutation', async () => {
+		const fixture = await createFixture()
+		let releaseWrites!: () => void
+		const settleWrites = vi.fn(() => new Promise<void>((resolve) => (releaseWrites = resolve)))
+		const installProject = vi.fn(async () => {})
+		const service = createTestService(fixture, { settleWrites, installProject })
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		await git(fixture.project, ['switch', '-c', 'changed-during-preparation'])
+		const locked = await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'browser-writes'
+		})
+
+		expect(locked.phase).toBe('flushing')
+		expect(service.isUsageBlocked()).toBe(true)
+		expect(settleWrites).toHaveBeenCalledOnce()
+		expect(installProject).not.toHaveBeenCalled()
+
+		releaseWrites()
+		const failed = await waitForPhase(service, 'tab-a', ['fatal'])
+		expect(failed.fatal?.kind).toBe('branch-mismatch')
+		expect(installProject).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('completes an unchanged activation without install, restart, reload, or a closed write gate', async () => {
+		const fixture = await createFixture()
+		const gateConfig = {
+			enabled: true,
+			projectDir: fixture.project,
+			leaseId: 'test-lease',
+			launchId: fixture.config.launchId
+		}
+		const backendGate = new RepositoryWriteGate(gateConfig)
+		const frontendGate = new RepositoryWriteGate(gateConfig)
+		await backendGate.initializeBackend()
+
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(() => backendGate.unlock())
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			settleWrites: () => backendGate.lockAndDrain(),
+			resumeWrites,
+			now: () => 1_000
+		})
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForOperationEnd(service, 'tab-a')
+
+		expect(finished.phase).toBe('idle')
+		expect(finished.operationId).toBeNull()
+		expect(finished.fatal).toBeNull()
+		expect(finished.reloadToken).toBeNull()
+		expect(finished.hasChanges).toBe(false)
+		expect(service.isUsageBlocked()).toBe(false)
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		await expect(frontendGate.withWriteAdmission(async () => 'written')).resolves.toBe('written')
+
+		const persisted = JSON.parse(await readFile(fixture.config.runtimeStatePath, 'utf8'))
+		expect(persisted.firstActivationCompleted).toBe(true)
+		expect(persisted.lastCompletedActivationAt).toBe(1_000)
+		expect((await service.activate({ tabId: 'tab-a', reason: 'focus' })).operationId).toBeNull()
+		await service.dispose()
+	})
+
+	it('preserves dirty status when an unchanged activation can pull without saving', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'local-draft.txt'), 'draft\n')
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+
+		expect((await service.status({ tabId: 'tab-a' })).hasChanges).toBe(true)
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForOperationEnd(service, 'tab-a')
+
+		expect(finished.phase).toBe('idle')
+		expect(finished.hasChanges).toBe(true)
+		expect(finished.reloadToken).toBeNull()
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('keeps writes blocked if an unchanged activation cannot release its gate', async () => {
+		const fixture = await createFixture()
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites: async () => {
+				throw new Error('unlock failed')
+			}
+		})
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['fatal'])
+
+		expect(finished.fatal?.kind).toBe('general')
+		expect(service.isUsageBlocked()).toBe(true)
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('relocks writes when shutdown begins during no-op gate release', async () => {
+		const fixture = await createFixture()
+		let markResumeStarted!: () => void
+		let releaseResume!: () => void
+		const resumeStarted = new Promise<void>((resolve) => (markResumeStarted = resolve))
+		const resumeRelease = new Promise<void>((resolve) => (releaseResume = resolve))
+		const settleWrites = vi.fn(async () => {})
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			settleWrites,
+			resumeWrites: async () => {
+				markResumeStarted()
+				await resumeRelease
+			}
+		})
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		await resumeStarted
+		const disposal = service.dispose()
+		releaseResume()
+		await disposal
+
+		expect(settleWrites).toHaveBeenCalledTimes(2)
+		expect(service.isUsageBlocked()).toBe(true)
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+	})
+
+	it('installs, restarts, and reloads after a fast-forward pull changes project files', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.phase).toBe('restarting')
+		expect(finished.reloadToken).not.toBeNull()
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledWith(76)
+		expect(resumeWrites).not.toHaveBeenCalled()
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(
+			await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])
+		)
+		await service.dispose()
+	})
+
+	it('merges a release update into personal and pushes it without moving the local release ref', async () => {
+		const fixture = await createFixture()
+		const localCurrentHead = await gitText(fixture.project, ['rev-parse', 'next-release'])
+		await switchCollaboratorToCurrent(fixture)
+		await writeFile(path.join(fixture.collaborator, 'release.txt'), 'release\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'release work'])
+		await git(fixture.collaborator, ['push'])
+		const currentHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, { installProject, scheduleRestart })
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.fatal).toBeNull()
+		expect(finished.phase).toBe('restarting')
+		expect(await readFile(path.join(fixture.project, 'release.txt'), 'utf8')).toBe('release\n')
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(currentHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'origin/next-release'])).toBe(currentHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).toBe(localCurrentHead)
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(currentHead)
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(currentHead)
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledWith(76)
+		await service.dispose()
+	})
+
+	it('does not restart when a release update changes history but not project files', async () => {
+		const fixture = await createFixture()
+		await switchCollaboratorToCurrent(fixture)
+		await git(fixture.collaborator, ['commit', '--allow-empty', '-m', 'metadata only'])
+		await git(fixture.collaborator, ['push'])
+		const currentHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForOperationEnd(service, 'tab-a')
+
+		expect(finished.phase).toBe('idle')
+		expect(finished.reloadToken).toBeNull()
+		expect(finished.canPrepareRelease).toBe(false)
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(currentHead)
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(currentHead)
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('recovers an interrupted content-changing pull before reopening Bosun', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		let interruptPull = true
+		const runner: CommandRunner = async (executable, args, options) => {
+			const result = await runCommand(executable, args, options)
+			if (interruptPull && executable === 'git' && args.includes('pull')) {
+				interruptPull = false
+				throw new Error('simulated shutdown after pull')
+			}
+			return result
+		}
+		const interrupted = createTestService(fixture, { runCommand: runner })
+		const started = await interrupted.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		expect((await waitForPhase(interrupted, 'tab-a', ['fatal'])).fatal?.kind).toBe('general')
+		expect(await readFile(path.join(fixture.project, 'remote.txt'), 'utf8')).toBe('remote\n')
+		await interrupted.dispose()
+
+		fixture.config.launchId = 'recovery-launch'
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+		const recovering = await recovered.status({ tabId: 'tab-b' })
+
+		expect(recovering.phase).toBe('restarting')
+		expect(recovering.reloadToken).not.toBeNull()
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledWith(76)
+		expect(resumeWrites).not.toHaveBeenCalled()
+		await recovered.dispose()
+
+		const managedRestartInstall = vi.fn(async () => {})
+		const managedRestartResume = vi.fn(async () => {})
+		const managedRestart = createTestService(fixture, {
+			installProject: managedRestartInstall,
+			resumeWrites: managedRestartResume
+		})
+		const ready = await managedRestart.status({ tabId: 'tab-c' })
+
+		expect(ready.phase).toBe('idle')
+		expect(ready.reloadToken).toBe(recovering.reloadToken)
+		expect(managedRestartInstall).not.toHaveBeenCalled()
+		expect(managedRestartResume).toHaveBeenCalledOnce()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-content-refresh.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await managedRestart.dispose()
+	}, 15_000)
+
+	it('clears an interrupted pull record when project files stayed identical', async () => {
+		const fixture = await createFixture()
+		await git(fixture.collaborator, ['commit', '--allow-empty', '-m', 'metadata only'])
+		await git(fixture.collaborator, ['push'])
+		let interruptPull = true
+		const runner: CommandRunner = async (executable, args, options) => {
+			const result = await runCommand(executable, args, options)
+			if (interruptPull && executable === 'git' && args.includes('pull')) {
+				interruptPull = false
+				throw new Error('simulated shutdown after pull')
+			}
+			return result
+		}
+		const interrupted = createTestService(fixture, { runCommand: runner })
+		const started = await interrupted.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		expect((await waitForPhase(interrupted, 'tab-a', ['fatal'])).fatal?.kind).toBe('general')
+		await interrupted.dispose()
+
+		fixture.config.launchId = 'unchanged-recovery-launch'
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+		const ready = await recovered.status({ tabId: 'tab-b' })
+
+		expect(ready.phase).toBe('idle')
+		expect(ready.reloadToken).toBeNull()
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-content-refresh.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await recovered.dispose()
+	})
+
+	it('installs dependencies without running package scripts', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		const installCommands: string[][] = []
+		const observedRunner: CommandRunner = async (executable, args, options) => {
+			if (executable === 'pnpm') {
+				installCommands.push([...args])
+				return { stdout: '', stderr: '', exitCode: 0 }
+			}
+			return runCommand(executable, args, options)
+		}
+		const service = createGitModeService(fixture.config, {
+			runCommand: observedRunner,
+			scheduleRestart: () => true,
+			watchFileChanges: false,
+			logError: () => {}
+		})
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.phase).toBe('restarting')
+		expect(installCommands).toEqual([
+			['install', '--frozen-lockfile', '--ignore-scripts', '--ignore-pnpmfile']
+		])
+		await service.dispose()
+	})
+
+	it('rejects repositories containing tracked submodules before browser preparation', async () => {
+		const fixture = await createFixture()
+		const head = await gitText(fixture.project, ['rev-parse', 'HEAD'])
+		await git(fixture.project, [
+			'update-index',
+			'--add',
+			'--cacheinfo',
+			`160000,${head},vendor/example`
+		])
+		const service = createTestService(fixture)
+
+		const status = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+
+		expect(status.phase).toBe('fatal')
+		expect(status.fatal?.message).toContain('tracked submodules')
+		expect(status.tabNeedsFlush).toBe(false)
+		await service.dispose()
+	})
+
+	it('uses explicit merge semantics, labels the merge, bypasses hooks, and pushes once', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'local.txt'), 'local\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'local work'])
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		await setHostilePullConfiguration(fixture.project)
+		await installFailingHooks(fixture.project)
+
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, { installProject, scheduleRestart })
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		expect(started.phase).toBe('preparing')
+		expect(started.tabNeedsFlush).toBe(true)
+		expect(service.isUsageBlocked()).toBe(false)
+		const flushing = await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		expect(flushing.phase).toBe('preparing')
+		expect(flushing.preparationStage).toBe('browser-writes')
+		expect(flushing.tabNeedsFlush).toBe(true)
+		expect(service.isUsageBlocked()).toBe(false)
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'browser-writes'
+		})
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.fatal).toBeNull()
+		expect(finished.phase).toBe('restarting')
+		expect(service.isUsageBlocked()).toBe(true)
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledWith(76)
+		expect(await gitText(fixture.project, ['log', '-1', '--pretty=%s'])).toBe(
+			'[BOSUN] [Merge] Merge origin/sb/bosun into sb/bosun'
+		)
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(
+			await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])
+		)
+		await service.dispose()
+	})
+
+	it('merges divergent release work into personal with one labelled push', async () => {
+		const fixture = await createFixture()
+		const previousCurrentHead = await gitText(fixture.project, ['rev-parse', 'origin/next-release'])
+		await writeFile(path.join(fixture.project, 'personal.txt'), 'personal\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal work'])
+		const personalHead = await gitText(fixture.project, ['rev-parse', 'HEAD'])
+
+		await switchCollaboratorToCurrent(fixture)
+		await writeFile(path.join(fixture.collaborator, 'release.txt'), 'release\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'release work'])
+		await git(fixture.collaborator, ['push'])
+		const currentHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		await setHostilePullConfiguration(fixture.project)
+		await installFailingHooks(fixture.project)
+
+		const pushes: string[][] = []
+		let movedCurrentTrackingRef = false
+		const observedRunner: CommandRunner = async (executable, args, options) => {
+			if (executable === 'git' && args.includes('push')) pushes.push([...args])
+			if (executable === 'git' && args.includes('merge') && !movedCurrentTrackingRef) {
+				movedCurrentTrackingRef = true
+				await git(fixture.project, [
+					'update-ref',
+					'refs/remotes/origin/next-release',
+					previousCurrentHead
+				])
+			}
+			return runCommand(executable, args, options)
+		}
+		const service = createTestService(fixture, { runCommand: observedRunner })
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.fatal).toBeNull()
+		expect(finished.phase).toBe('restarting')
+		expect(await gitText(fixture.project, ['log', '-1', '--pretty=%s'])).toBe(
+			'[BOSUN] [Merge] Merge origin/next-release into sb/bosun'
+		)
+		expect((await gitText(fixture.project, ['log', '-1', '--pretty=%P'])).split(' ')).toEqual([
+			personalHead,
+			currentHead
+		])
+		expect(movedCurrentTrackingRef).toBe(true)
+		expect(pushes).toHaveLength(1)
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(
+			await gitText(fixture.project, ['rev-parse', 'HEAD'])
+		)
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(currentHead)
+		await service.dispose()
+	}, 15_000)
+
+	it('does not mistake a clean pending merge for a conflict when its labelled commit fails', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'local.txt'), 'local\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'local work'])
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+
+		const rejectMergeCommit: CommandRunner = (executable, args, options) => {
+			if (executable === 'git' && args.includes('commit')) {
+				return Promise.reject(
+					new CommandError(executable, args, {
+						stdout: '',
+						stderr: 'simulated commit failure',
+						exitCode: 1
+					})
+				)
+			}
+			return runCommand(executable, args, options)
+		}
+		const service = createTestService(fixture, { runCommand: rejectMergeCommit })
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const failed = await waitForPhase(service, 'tab-a', ['fatal'])
+
+		expect(failed.fatal?.kind).toBe('general')
+		expect(await gitText(fixture.project, ['ls-files', '-u'])).toBe('')
+		expect(await gitText(fixture.project, ['rev-parse', '--verify', 'MERGE_HEAD'])).not.toBe('')
+		await service.dispose()
+	})
+
+	it('waits for every live tab and defers without blocking while a browser draft exists', async () => {
+		const fixture = await createFixture()
+		const installProject = vi.fn(async () => {})
+		const service = createTestService(fixture, { installProject })
+		await service.status({ tabId: 'tab-b' })
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		expect((await service.status({ tabId: 'tab-a' })).phase).toBe('preparing')
+		await service.flushAck({
+			tabId: 'tab-b',
+			operationId: started.operationId!,
+			stage: 'preflight',
+			blockedReason: 'Save or close the open schema draft.'
+		})
+
+		const deferred = await service.status({ tabId: 'tab-a' })
+		expect(deferred.phase).toBe('idle')
+		expect(deferred.deferredReason).toBe('Save or close the open schema draft.')
+		expect(service.isUsageBlocked()).toBe(false)
+		expect(installProject).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('takes a fresh all-tab snapshot for the locked flush barrier', async () => {
+		const fixture = await createFixture()
+		const service = createTestService(fixture)
+		await service.status({ tabId: 'tab-b' })
+
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		const flushing = await service.flushAck({
+			tabId: 'tab-b',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		expect(flushing.phase).toBe('preparing')
+		expect(flushing.preparationStage).toBe('browser-writes')
+		expect((await service.status({ tabId: 'tab-a' })).tabNeedsFlush).toBe(true)
+		expect((await service.status({ tabId: 'tab-b' })).tabNeedsFlush).toBe(true)
+
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'browser-writes'
+		})
+		expect((await service.status({ tabId: 'tab-a' })).phase).toBe('preparing')
+		await service.flushAck({
+			tabId: 'tab-b',
+			operationId: started.operationId!,
+			stage: 'browser-writes',
+			blockedReason: 'A pending edit could not be flushed.'
+		})
+		const deferred = await service.status({ tabId: 'tab-a' })
+		expect(deferred.phase).toBe('idle')
+		expect(deferred.deferredReason).toBe('A pending edit could not be flushed.')
+		await service.dispose()
+	})
+
+	it('adds a tab that appears during browser-write preparation and rejects a stale-stage ACK', async () => {
+		const fixture = await createFixture()
+		const service = createTestService(fixture)
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+
+		const joined = await service.status({ tabId: 'tab-b' })
+		expect(joined.phase).toBe('preparing')
+		expect(joined.preparationStage).toBe('browser-writes')
+		expect(joined.tabNeedsFlush).toBe(true)
+		const staleAck = await service.flushAck({
+			tabId: 'tab-b',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		expect(staleAck.tabNeedsFlush).toBe(true)
+
+		await service.flushAck({
+			tabId: 'tab-a',
+			operationId: started.operationId!,
+			stage: 'browser-writes'
+		})
+		expect((await service.status({ tabId: 'tab-a' })).phase).toBe('preparing')
+		await service.flushAck({
+			tabId: 'tab-b',
+			operationId: started.operationId!,
+			stage: 'browser-writes'
+		})
+		expect((await waitForOperationEnd(service, 'tab-a')).phase).toBe('idle')
+		await service.dispose()
+	})
+
+	it('expires a disappeared tab before the browser barrier deadline', async () => {
+		const fixture = await createFixture()
+		let now = 1_000
+		const service = createTestService(fixture, {
+			now: () => now,
+			liveTabMs: 5,
+			flushTimeoutMs: 2_000
+		})
+		await service.status({ tabId: 'closed-tab' })
+
+		const started = await service.activate({ tabId: 'active-tab', reason: 'page-open' })
+		await service.flushAck({
+			tabId: 'active-tab',
+			operationId: started.operationId!,
+			stage: 'preflight'
+		})
+		now += 6
+		await service.status({ tabId: 'active-tab' })
+		await new Promise((resolve) => setTimeout(resolve, 550))
+
+		const flushing = await service.status({ tabId: 'active-tab' })
+		expect(flushing.phase).toBe('preparing')
+		expect(flushing.preparationStage).toBe('browser-writes')
+		expect(flushing.tabNeedsFlush).toBe(true)
+		await service.flushAck({
+			tabId: 'active-tab',
+			operationId: started.operationId!,
+			stage: 'browser-writes'
+		})
+		expect((await waitForOperationEnd(service, 'active-tab')).phase).toBe('idle')
+		await service.dispose()
+	})
+
+	it('saves and publishes files without restarting when their content stays the same', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'manual.txt'), 'ready\n')
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const service = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+
+		expect((await service.status({ tabId: 'tab-a' })).hasChanges).toBe(true)
+		const started = await service.startManual({
+			tabId: 'tab-a',
+			action: 'save',
+			description: 'manual release'
+		})
+		expect(started.phase).toBe('preparing')
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForOperationEnd(service, 'tab-a')
+
+		expect(finished.fatal).toBeNull()
+		expect(finished.phase).toBe('idle')
+		expect(finished.reloadToken).toBeNull()
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		expect(await gitText(fixture.project, ['log', '-1', '--pretty=%s'])).toBe(
+			'[BOSUN] manual release'
+		)
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(
+			await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])
+		)
+		await service.dispose()
+	}, 15_000)
+
+	it('restarts after manual Discard changes the checked-out project files', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'app.txt'), 'discard me\n')
+		await writeFile(path.join(fixture.project, 'untracked.txt'), 'discard me too\n')
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, { installProject, scheduleRestart })
+
+		const started = await service.startManual({ tabId: 'tab-a', action: 'discard' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.fatal).toBeNull()
+		expect(finished.phase).toBe('restarting')
+		expect(finished.reloadToken).not.toBeNull()
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledWith(76)
+		expect(await readFile(path.join(fixture.project, 'app.txt'), 'utf8')).toBe('base\n')
+		await expect(
+			readFile(path.join(fixture.project, 'untracked.txt'), 'utf8')
+		).rejects.toMatchObject({
+			code: 'ENOENT'
+		})
+		await service.dispose()
+	})
+
+	it('saves refused local changes with a Bosun prefix, merges, and publishes both commits', async () => {
+		const fixture = await createFixture('one\ntwo\nthree\nfour\n')
+		await writeFile(path.join(fixture.project, 'app.txt'), 'one\ntwo\nthree\nlocal four\n')
+		await writeFile(path.join(fixture.collaborator, 'app.txt'), 'remote one\ntwo\nthree\nfour\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote line'])
+		await git(fixture.collaborator, ['push'])
+		await installFailingHooks(fixture.project)
+
+		const service = createTestService(fixture)
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const awaiting = await waitForPhase(service, 'tab-a', ['awaiting-changes', 'fatal'])
+		expect(awaiting.phase).toBe('awaiting-changes')
+
+		await service.resolveChanges({
+			tabId: 'tab-a',
+			operationId: awaiting.operationId!,
+			action: 'save',
+			description: '  keep   both lines  '
+		})
+		await expect(
+			service.resolveChanges({
+				tabId: 'tab-b',
+				operationId: awaiting.operationId!,
+				action: 'discard'
+			})
+		).rejects.toThrow('This refresh choice was already handled in another Bosun tab.')
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+		expect(finished.fatal).toBeNull()
+		const subjects = (await gitText(fixture.project, ['log', '-2', '--pretty=%s'])).split('\n')
+		expect(subjects).toEqual([
+			'[BOSUN] [Merge] Merge origin/sb/bosun into sb/bosun',
+			'[BOSUN] keep both lines'
+		])
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(
+			await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])
+		)
+		await service.dispose()
+	}, 15_000)
+
+	it('stashes refused tracked and untracked changes before pulling', async () => {
+		const fixture = await createFixture('base\n')
+		await writeFile(path.join(fixture.project, 'app.txt'), 'local dirty\n')
+		await writeFile(path.join(fixture.project, 'untracked.txt'), 'recover me\n')
+		await switchCollaboratorToCurrent(fixture)
+		await writeFile(path.join(fixture.collaborator, 'app.txt'), 'remote update\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote update'])
+		await git(fixture.collaborator, ['push'])
+
+		const service = createTestService(fixture)
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const awaiting = await waitForPhase(service, 'tab-a', ['awaiting-changes', 'fatal'])
+		expect(awaiting.phase).toBe('awaiting-changes')
+		await service.resolveChanges({
+			tabId: 'tab-a',
+			operationId: awaiting.operationId!,
+			action: 'discard'
+		})
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.fatal).toBeNull()
+		expect(await readFile(path.join(fixture.project, 'app.txt'), 'utf8')).toBe('remote update\n')
+		expect(await gitText(fixture.project, ['stash', 'list'])).toContain(
+			'[BOSUN] Discard before refresh'
+		)
+		expect(
+			await gitText(fixture.project, ['ls-tree', '-r', '--name-only', 'stash@{0}^3'])
+		).toContain('untracked.txt')
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(
+			await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		)
+		await service.dispose()
+	}, 15_000)
+
+	it('aborts a conflict, publishes a unique conflict branch, and keeps the current branch intact', async () => {
+		const fixture = await createFixture('base\n')
+		await writeFile(path.join(fixture.project, 'app.txt'), 'local commit\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'local conflicting work'])
+		const localHead = await gitText(fixture.project, ['rev-parse', 'HEAD'])
+		await writeFile(path.join(fixture.collaborator, 'app.txt'), 'remote commit\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote conflicting work'])
+		await git(fixture.collaborator, ['push'])
+
+		const githubUrl = 'https://github.com/recombine-ai/example.git'
+		await git(fixture.project, ['remote', 'set-url', 'origin', githubUrl])
+		await git(fixture.project, [
+			'config',
+			`url.${pathToFileURL(fixture.remote).href}.insteadOf`,
+			githubUrl
+		])
+
+		const installProject = vi.fn(async () => {})
+		const service = createTestService(fixture, { installProject })
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const failed = await waitForPhase(service, 'tab-a', ['fatal'])
+
+		expect(failed.fatal?.kind).toBe('merge-conflict')
+		expect(failed.prUrl).toMatch(
+			/^https:\/\/github\.com\/recombine-ai\/example\/compare\/sb%2Fbosun\.\.\.bosun-conflict%2Fsb%2Fbosun%2F/
+		)
+		expect(installProject).not.toHaveBeenCalled()
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(localHead)
+		expect(await gitText(fixture.project, ['ls-files', '-u'])).toBe('')
+		const conflictRefs = (
+			await gitText(fixture.remote, [
+				'for-each-ref',
+				'--format=%(refname:short) %(objectname)',
+				'refs/heads/bosun-conflict/'
+			])
+		)
+			.split('\n')
+			.filter(Boolean)
+		expect(conflictRefs).toHaveLength(1)
+		expect(conflictRefs[0]).toContain(localHead)
+		expect(service.isUsageBlocked()).toBe(true)
+		await service.dispose()
+	})
+
+	it('publishes a release snapshot into personal when the release merge conflicts', async () => {
+		const fixture = await createFixture('base\n')
+		await writeFile(path.join(fixture.project, 'app.txt'), 'personal commit\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal conflicting work'])
+		const personalHead = await gitText(fixture.project, ['rev-parse', 'HEAD'])
+
+		await switchCollaboratorToCurrent(fixture)
+		await writeFile(path.join(fixture.collaborator, 'app.txt'), 'release commit\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'release conflicting work'])
+		await git(fixture.collaborator, ['push'])
+		const currentHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+
+		const githubUrl = 'https://github.com/recombine-ai/example.git'
+		await git(fixture.project, ['remote', 'set-url', 'origin', githubUrl])
+		await git(fixture.project, [
+			'config',
+			`url.${pathToFileURL(fixture.remote).href}.insteadOf`,
+			githubUrl
+		])
+
+		const installProject = vi.fn(async () => {})
+		const service = createTestService(fixture, { installProject })
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const failed = await waitForPhase(service, 'tab-a', ['fatal'])
+
+		expect(failed.fatal?.kind).toBe('merge-conflict')
+		expect(failed.prUrl).toMatch(
+			/^https:\/\/github\.com\/recombine-ai\/example\/compare\/sb%2Fbosun\.\.\.bosun-conflict%2Fsb%2Fbosun%2F/
+		)
+		expect(installProject).not.toHaveBeenCalled()
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(personalHead)
+		expect(await gitText(fixture.project, ['ls-files', '-u'])).toBe('')
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(personalHead)
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(currentHead)
+		const conflictRefs = (
+			await gitText(fixture.remote, [
+				'for-each-ref',
+				'--format=%(refname:short) %(objectname)',
+				'refs/heads/bosun-conflict/'
+			])
+		)
+			.split('\n')
+			.filter(Boolean)
+		expect(conflictRefs).toHaveLength(1)
+		expect(conflictRefs[0]?.split(' ')[1]).toBe(currentHead)
+		expect(service.isUsageBlocked()).toBe(true)
+		await service.dispose()
+	}, 15_000)
+
+	it('publishes a clean personal branch to the current branch without leaving personal', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'release.txt'), 'ready\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, { installProject, scheduleRestart })
+
+		const available = await service.status({ tabId: 'tab-a' })
+		expect(available.hasChanges).toBe(false)
+		expect(available.canPrepareRelease).toBe(true)
+		const started = await service.prepareRelease({ tabId: 'tab-a' })
+		expect(started.phase).toBe('preparing')
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForOperationEnd(service, 'tab-a')
+
+		expect(finished.phase).toBe('idle')
+		expect(finished.canPrepareRelease).toBe(false)
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		const personalRemoteHead = await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(personalRemoteHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).toBe(personalRemoteHead)
+		expect(installProject).not.toHaveBeenCalled()
+		expect(scheduleRestart).not.toHaveBeenCalled()
+		await service.dispose()
+	})
+
+	it('builds a divergent release outside the primary checkout and atomically publishes both branches', async () => {
+		const fixture = await createFixture()
+		await git(fixture.collaborator, ['branch', '--track', 'next-release', 'origin/next-release'])
+		await git(fixture.collaborator, ['switch', 'next-release'])
+		await writeFile(path.join(fixture.collaborator, 'current.txt'), 'current work\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'current work'])
+		await git(fixture.collaborator, ['push'])
+
+		await writeFile(path.join(fixture.project, 'personal.txt'), 'personal work\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal work'])
+		await git(fixture.project, ['push'])
+		await installFailingHooks(fixture.project)
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const service = createTestService(fixture, { installProject, scheduleRestart })
+
+		expect((await service.status({ tabId: 'tab-a' })).canPrepareRelease).toBe(true)
+		const started = await service.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const finished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+
+		expect(finished.fatal).toBeNull()
+		expect(finished.phase).toBe('restarting')
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		const resultHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(resultHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(resultHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).toBe(resultHead)
+		expect(await gitText(fixture.project, ['log', '-1', '--pretty=%s'])).toBe(
+			'[BOSUN] [Merge] Merge sb/bosun into next-release'
+		)
+		expect(await readFile(path.join(fixture.project, 'current.txt'), 'utf8')).toBe('current work\n')
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledOnce()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await service.dispose()
+	}, 15_000)
+
+	it('publishes a conflict branch for a Prepare conflict without changing either release branch', async () => {
+		const fixture = await createFixture('base\n')
+		await git(fixture.collaborator, ['branch', '--track', 'next-release', 'origin/next-release'])
+		await git(fixture.collaborator, ['switch', 'next-release'])
+		await writeFile(path.join(fixture.collaborator, 'app.txt'), 'current change\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'current conflict'])
+		await git(fixture.collaborator, ['push'])
+		const currentHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+
+		await writeFile(path.join(fixture.project, 'app.txt'), 'personal change\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal conflict'])
+		await git(fixture.project, ['push'])
+		const personalHead = await gitText(fixture.project, ['rev-parse', 'HEAD'])
+		const githubUrl = 'https://github.com/recombine-ai/example.git'
+		await git(fixture.project, ['remote', 'set-url', 'origin', githubUrl])
+		await git(fixture.project, [
+			'config',
+			`url.${pathToFileURL(fixture.remote).href}.insteadOf`,
+			githubUrl
+		])
+		const installProject = vi.fn(async () => {})
+		const service = createTestService(fixture, { installProject })
+
+		const started = await service.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const failed = await waitForPhase(service, 'tab-a', ['fatal'])
+
+		expect(failed.fatal?.kind).toBe('merge-conflict')
+		expect(failed.prUrl).toMatch(
+			/^https:\/\/github\.com\/recombine-ai\/example\/compare\/next-release\.\.\.bosun-conflict%2Fnext-release%2F/
+		)
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(currentHead)
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(personalHead)
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(personalHead)
+		expect(installProject).not.toHaveBeenCalled()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release-workspace', 'HEAD'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await service.dispose()
+	}, 15_000)
+
+	it('refuses to overwrite unpublished commits on the local current branch', async () => {
+		const fixture = await createFixture()
+		await git(fixture.project, ['switch', 'next-release'])
+		await writeFile(path.join(fixture.project, 'local-current.txt'), 'local only\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'unpublished current work'])
+		const localCurrentHead = await gitText(fixture.project, ['rev-parse', 'HEAD'])
+		await git(fixture.project, ['switch', 'sb/bosun'])
+		await writeFile(path.join(fixture.project, 'personal.txt'), 'release me\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		const oldRemoteCurrent = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		const service = createTestService(fixture)
+
+		const started = await service.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const failed = await waitForPhase(service, 'tab-a', ['fatal'])
+
+		expect(failed.fatal?.kind).toBe('general')
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(oldRemoteCurrent)
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).toBe(localCurrentHead)
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		await service.dispose()
+	})
+
+	it('blocks Prepare if the release branch is checked out in a worktree added after launch', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'personal.txt'), 'release me\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		const service = createTestService(fixture)
+		expect((await service.status({ tabId: 'tab-a' })).canPrepareRelease).toBe(true)
+
+		const releaseWorktree = path.join(fixture.root, 'release-worktree')
+		await git(fixture.project, ['worktree', 'add', releaseWorktree, 'next-release'])
+		const status = await service.prepareRelease({ tabId: 'tab-a' })
+
+		expect(status.phase).toBe('fatal')
+		expect(status.operationId).toBeNull()
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(releaseWorktree, ['branch', '--show-current'])).toBe('next-release')
+		await service.dispose()
+	})
+
+	it('blocks activation if the shared remote gains a different push URL after launch', async () => {
+		const fixture = await createFixture()
+		const service = createTestService(fixture)
+		await service.status({ tabId: 'tab-a' })
+		await git(fixture.project, ['remote', 'set-url', '--push', 'origin', `${fixture.remote}-other`])
+
+		const status = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+
+		expect(status.phase).toBe('fatal')
+		expect(status.operationId).toBeNull()
+		expect(status.fatal?.message).toContain('matching push URL')
+		await service.dispose()
+	})
+
+	it('rejects explicit Save and Prepare starts while another operation owns Git mode', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'local.txt'), 'local draft\n')
+		const service = createTestService(fixture)
+		const activation = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		expect(activation.phase).toBe('preparing')
+
+		await expect(
+			service.startManual({
+				tabId: 'tab-b',
+				action: 'save',
+				description: 'must not attach to activation'
+			})
+		).rejects.toThrow('already in progress')
+		await expect(service.prepareRelease({ tabId: 'tab-b' })).rejects.toThrow('already in progress')
+		await service.dispose()
+	})
+
+	it('recovers a fully published release after shutdown before local alignment', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'release.txt'), 'published\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		let lostAtomicPushResponse = false
+		const runner: CommandRunner = async (executable, args, options) => {
+			const result = await runCommand(executable, args, options)
+			if (!lostAtomicPushResponse && executable === 'git' && args.includes('--atomic')) {
+				lostAtomicPushResponse = true
+				throw new Error('simulated shutdown after atomic publication')
+			}
+			return result
+		}
+		const interrupted = createTestService(fixture, { runCommand: runner })
+		const started = await interrupted.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		expect((await waitForPhase(interrupted, 'tab-a', ['fatal'])).fatal?.kind).toBe('general')
+		await interrupted.dispose()
+
+		const publishedHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(publishedHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).not.toBe(publishedHead)
+		fixture.config.launchId = 'recovery-launch'
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, { resumeWrites })
+		const status = await recovered.status({ tabId: 'tab-b' })
+
+		expect(status.phase).toBe('idle')
+		expect(status.fatal).toBeNull()
+		expect(status.canPrepareRelease).toBe(false)
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).toBe(publishedHead)
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await recovered.dispose()
+	}, 15_000)
+
+	it('installs and restarts when divergent release recovery changes the personal tree', async () => {
+		const fixture = await createFixture()
+		await git(fixture.collaborator, ['branch', '--track', 'next-release', 'origin/next-release'])
+		await git(fixture.collaborator, ['switch', 'next-release'])
+		await writeFile(path.join(fixture.collaborator, 'current.txt'), 'current work\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'current work'])
+		await git(fixture.collaborator, ['push'])
+		await writeFile(path.join(fixture.project, 'personal.txt'), 'personal work\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal work'])
+		await git(fixture.project, ['push'])
+
+		let lostAtomicPushResponse = false
+		const runner: CommandRunner = async (executable, args, options) => {
+			const result = await runCommand(executable, args, options)
+			if (!lostAtomicPushResponse && executable === 'git' && args.includes('--atomic')) {
+				lostAtomicPushResponse = true
+				throw new Error('simulated shutdown after divergent atomic publication')
+			}
+			return result
+		}
+		const interrupted = createTestService(fixture, { runCommand: runner })
+		const started = await interrupted.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		await waitForPhase(interrupted, 'tab-a', ['fatal'])
+		await interrupted.dispose()
+
+		const resultHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		expect(await gitText(fixture.remote, ['rev-parse', 'sb/bosun'])).toBe(resultHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).not.toBe(resultHead)
+		fixture.config.launchId = 'divergent-recovery-launch'
+		const installProject = vi.fn(async () => {})
+		const scheduleRestart = vi.fn(() => true)
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, {
+			installProject,
+			scheduleRestart,
+			resumeWrites
+		})
+		const status = await recovered.status({ tabId: 'tab-b' })
+
+		expect(status.phase).toBe('restarting')
+		expect(status.reloadToken).not.toBeNull()
+		expect(await gitText(fixture.project, ['branch', '--show-current'])).toBe('sb/bosun')
+		expect(await gitText(fixture.project, ['rev-parse', 'HEAD'])).toBe(resultHead)
+		expect(await gitText(fixture.project, ['rev-parse', 'next-release'])).toBe(resultHead)
+		expect(await readFile(path.join(fixture.project, 'current.txt'), 'utf8')).toBe('current work\n')
+		expect(installProject).toHaveBeenCalledOnce()
+		expect(scheduleRestart).toHaveBeenCalledWith(76)
+		expect(resumeWrites).not.toHaveBeenCalled()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await recovered.dispose()
+	}, 20_000)
+
+	it('cleans an interrupted Prepare attempt when neither remote branch was published', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'release.txt'), 'not published\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		const rejectAtomicPush: CommandRunner = (executable, args, options) => {
+			if (executable === 'git' && args.includes('--atomic')) {
+				return Promise.reject(new Error('simulated shutdown before atomic publication'))
+			}
+			return runCommand(executable, args, options)
+		}
+		const interrupted = createTestService(fixture, { runCommand: rejectAtomicPush })
+		const started = await interrupted.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		await waitForPhase(interrupted, 'tab-a', ['fatal'])
+		await interrupted.dispose()
+
+		const oldCurrentHead = await gitText(fixture.remote, ['rev-parse', 'next-release'])
+		fixture.config.launchId = 'unpublished-recovery-launch'
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, { resumeWrites })
+		const status = await recovered.status({ tabId: 'tab-b' })
+
+		expect(status.phase).toBe('idle')
+		expect(status.canPrepareRelease).toBe(true)
+		expect(await gitText(fixture.remote, ['rev-parse', 'next-release'])).toBe(oldCurrentHead)
+		expect(resumeWrites).toHaveBeenCalledOnce()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		await recovered.dispose()
+	}, 15_000)
+
+	it('blocks recovery when the interrupted release refs have a foreign split state', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'release.txt'), 'not published\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		const rejectAtomicPush: CommandRunner = (executable, args, options) => {
+			if (executable === 'git' && args.includes('--atomic')) {
+				return Promise.reject(new Error('simulated shutdown before atomic publication'))
+			}
+			return runCommand(executable, args, options)
+		}
+		const interrupted = createTestService(fixture, { runCommand: rejectAtomicPush })
+		const started = await interrupted.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		await waitForPhase(interrupted, 'tab-a', ['fatal'])
+		await interrupted.dispose()
+
+		await git(fixture.collaborator, ['branch', '--track', 'next-release', 'origin/next-release'])
+		await git(fixture.collaborator, ['switch', 'next-release'])
+		await writeFile(path.join(fixture.collaborator, 'foreign.txt'), 'foreign update\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'foreign current update'])
+		await git(fixture.collaborator, ['push'])
+
+		fixture.config.launchId = 'foreign-recovery-launch'
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, { resumeWrites })
+		const status = await recovered.status({ tabId: 'tab-b' })
+
+		expect(status.phase).toBe('fatal')
+		expect(status.fatal?.kind).toBe('general')
+		expect(resumeWrites).not.toHaveBeenCalled()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'), 'utf8')
+		).resolves.toContain('oldCurrentRemoteHead')
+		await recovered.dispose()
+	}, 15_000)
+
+	it('blocks interrupted Prepare recovery if the effective remote URL changed', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.project, 'release.txt'), 'not published\n')
+		await git(fixture.project, ['add', '-A'])
+		await git(fixture.project, ['commit', '-m', 'personal release'])
+		await git(fixture.project, ['push'])
+		const rejectAtomicPush: CommandRunner = (executable, args, options) => {
+			if (executable === 'git' && args.includes('--atomic')) {
+				return Promise.reject(new Error('simulated shutdown before atomic publication'))
+			}
+			return runCommand(executable, args, options)
+		}
+		const interrupted = createTestService(fixture, { runCommand: rejectAtomicPush })
+		const started = await interrupted.prepareRelease({ tabId: 'tab-a' })
+		await acknowledgePreparationAndFlush(interrupted, 'tab-a', started.operationId!)
+		await waitForPhase(interrupted, 'tab-a', ['fatal'])
+		await interrupted.dispose()
+
+		await git(fixture.project, [
+			'remote',
+			'set-url',
+			'origin',
+			path.join(fixture.root, 'different-remote.git')
+		])
+		fixture.config.launchId = 'changed-url-recovery-launch'
+		const resumeWrites = vi.fn(async () => {})
+		const recovered = createTestService(fixture, { resumeWrites })
+		const status = await recovered.status({ tabId: 'tab-b' })
+
+		expect(status.phase).toBe('fatal')
+		expect(resumeWrites).not.toHaveBeenCalled()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-prepare-release.json'), 'utf8')
+		).resolves.toContain('remoteUrlDigest')
+		await recovered.dispose()
+	}, 15_000)
+
+	it('persists completion so a managed backend restart cannot reactivate immediately', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		let now = 1_000
+		const service = createTestService(fixture, { now: () => now })
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		const firstFinished = await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])
+		expect(firstFinished.phase).toBe('restarting')
+		const reloadToken = firstFinished.reloadToken
+		await service.dispose()
+		const persisted = JSON.parse(await readFile(fixture.config.runtimeStatePath, 'utf8'))
+		persisted.lastRelevantChangeAt = 1_500
+		await writeFile(fixture.config.runtimeStatePath, `${JSON.stringify(persisted)}\n`)
+
+		const restarted = createTestService(fixture, { now: () => now })
+		const initial = await restarted.status({ tabId: 'tab-b' })
+		expect(initial.phase).toBe('idle')
+		expect(initial.reloadToken).toBe(reloadToken)
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-content-refresh.json'))
+		).rejects.toMatchObject({ code: 'ENOENT' })
+		expect(
+			(await restarted.activate({ tabId: 'tab-b', reason: 'page-open' })).operationId
+		).toBeNull()
+
+		now += fixture.config.idleMs
+		expect((await restarted.activate({ tabId: 'tab-b', reason: 'focus' })).operationId).toBeNull()
+		now = 1_500 + fixture.config.idleMs
+		const eligible = await restarted.activate({ tabId: 'tab-b', reason: 'focus' })
+		expect(eligible.phase).toBe('preparing')
+		await restarted.dispose()
+	}, 15_000)
+
+	it('keeps recovery blocked if the checkout leaves the personal branch before restart', async () => {
+		const fixture = await createFixture()
+		await writeFile(path.join(fixture.collaborator, 'remote.txt'), 'remote\n')
+		await git(fixture.collaborator, ['add', '-A'])
+		await git(fixture.collaborator, ['commit', '-m', 'remote work'])
+		await git(fixture.collaborator, ['push'])
+		const service = createTestService(fixture)
+		const started = await service.activate({ tabId: 'tab-a', reason: 'page-open' })
+		await acknowledgePreparationAndFlush(service, 'tab-a', started.operationId!)
+		expect((await waitForPhase(service, 'tab-a', ['restarting', 'fatal'])).phase).toBe('restarting')
+		await service.dispose()
+
+		await git(fixture.project, ['switch', 'next-release'])
+		const installProject = vi.fn(async () => {})
+		const resumeWrites = vi.fn(async () => {})
+		const restarted = createTestService(fixture, { installProject, resumeWrites })
+		const blocked = await restarted.status({ tabId: 'tab-b' })
+
+		expect(blocked.phase).toBe('fatal')
+		expect(blocked.fatal?.kind).toBe('branch-mismatch')
+		expect(installProject).not.toHaveBeenCalled()
+		expect(resumeWrites).not.toHaveBeenCalled()
+		await expect(
+			readFile(path.join(fixture.project, '.git', 'bosun-content-refresh.json'), 'utf8')
+		).resolves.toContain('installedContent')
+		await restarted.dispose()
+	})
+})
+
+interface Fixture {
+	root: string
+	remote: string
+	project: string
+	collaborator: string
+	config: GitModeConfig
+}
+
+async function createFixture(appContents = 'base\n'): Promise<Fixture> {
+	const root = await mkdtemp(path.join(tmpdir(), 'bosun-git-mode-'))
+	temporaryDirectories.push(root)
+	const remote = path.join(root, 'remote.git')
+	const seed = path.join(root, 'seed')
+	const project = path.join(root, 'project')
+	const collaborator = path.join(root, 'collaborator')
+	await git(root, ['init', '--bare', remote])
+	await mkdir(seed)
+	await git(seed, ['init'])
+	await configureUser(seed)
+	await git(seed, ['checkout', '-b', 'next-release'])
+	await writeFile(path.join(seed, 'app.txt'), appContents)
+	await writeFile(path.join(seed, 'package.json'), '{"name":"fixture","private":true}\n')
+	await git(seed, ['add', '-A'])
+	await git(seed, ['commit', '-m', 'initial'])
+	await git(seed, ['remote', 'add', 'origin', remote])
+	await git(seed, ['push', '-u', 'origin', 'next-release'])
+	await git(seed, ['switch', '-c', 'sb/bosun'])
+	await git(seed, ['push', '-u', 'origin', 'sb/bosun'])
+	await git(root, ['clone', '--branch', 'sb/bosun', remote, project])
+	await git(root, ['clone', '--branch', 'sb/bosun', remote, collaborator])
+	await git(project, ['branch', '--track', 'next-release', 'origin/next-release'])
+	await configureUser(project)
+	await configureUser(collaborator)
+
+	return {
+		root,
+		remote,
+		project,
+		collaborator,
+		config: {
+			enabled: true,
+			projectDir: project,
+			currentBranch: 'next-release',
+			personalBranch: 'sb/bosun',
+			idleMs: 60_000,
+			currentUpstream: 'origin/next-release',
+			currentUpstreamRemote: 'origin',
+			currentUpstreamBranch: 'next-release',
+			personalUpstream: 'origin/sb/bosun',
+			personalUpstreamRemote: 'origin',
+			personalUpstreamBranch: 'sb/bosun',
+			launchId: 'test-launch',
+			runtimeStatePath: path.join(root, 'runtime', 'git-mode.json'),
+			restartExitCode: 76
+		}
+	}
+}
+
+function createTestService(
+	fixture: Fixture,
+	overrides: {
+		installProject?: () => Promise<void>
+		settleWrites?: () => Promise<void>
+		resumeWrites?: () => Promise<void>
+		scheduleRestart?: (exitCode: number) => boolean
+		runCommand?: CommandRunner
+		now?: () => number
+		liveTabMs?: number
+		flushTimeoutMs?: number
+	} = {}
+): GitModeService {
+	return createGitModeService(fixture.config, {
+		runCommand: overrides.runCommand,
+		installProject: overrides.installProject ?? (async () => {}),
+		settleWrites: overrides.settleWrites,
+		resumeWrites: overrides.resumeWrites ?? (async () => {}),
+		scheduleRestart: overrides.scheduleRestart ?? (() => true),
+		now: overrides.now,
+		liveTabMs: overrides.liveTabMs,
+		flushTimeoutMs: overrides.flushTimeoutMs,
+		watchFileChanges: false,
+		logError: () => {}
+	})
+}
+
+async function acknowledgePreparationAndFlush(
+	service: GitModeService,
+	tabId: string,
+	operationId: string
+): Promise<void> {
+	const flushing = await service.flushAck({ tabId, operationId, stage: 'preflight' })
+	expect(flushing.phase).toBe('preparing')
+	expect(flushing.preparationStage).toBe('browser-writes')
+	expect(flushing.tabNeedsFlush).toBe(true)
+	await service.flushAck({ tabId, operationId, stage: 'browser-writes' })
+}
+
+async function waitForPhase(
+	service: GitModeService,
+	tabId: string,
+	phases: GitModeStatus['phase'][]
+): Promise<GitModeStatus> {
+	const deadline = Date.now() + 10_000
+	while (Date.now() < deadline) {
+		const status = await service.status({ tabId })
+		if (phases.includes(status.phase)) return status
+		await new Promise((resolve) => setTimeout(resolve, 10))
+	}
+	throw new Error(`Timed out waiting for Git mode phase: ${phases.join(', ')}`)
+}
+
+async function waitForOperationEnd(service: GitModeService, tabId: string): Promise<GitModeStatus> {
+	const deadline = Date.now() + 10_000
+	while (Date.now() < deadline) {
+		const status = await service.status({ tabId })
+		if (
+			status.phase === 'fatal' ||
+			status.phase === 'restarting' ||
+			(status.phase === 'idle' && status.operationId === null)
+		) {
+			return status
+		}
+		await new Promise((resolve) => setTimeout(resolve, 10))
+	}
+	throw new Error('Timed out waiting for the Git mode operation to finish')
+}
+
+async function configureUser(repository: string): Promise<void> {
+	await git(repository, ['config', 'user.name', 'Bosun Test'])
+	await git(repository, ['config', 'user.email', 'bosun@example.test'])
+}
+
+async function switchCollaboratorToCurrent(fixture: Fixture): Promise<void> {
+	await git(fixture.collaborator, ['branch', '--track', 'next-release', 'origin/next-release'])
+	await git(fixture.collaborator, ['switch', 'next-release'])
+}
+
+async function setHostilePullConfiguration(repository: string): Promise<void> {
+	await git(repository, ['config', 'pull.rebase', 'true'])
+	await git(repository, ['config', 'pull.ff', 'only'])
+	await git(repository, ['config', 'pull.squash', 'true'])
+	await git(repository, ['config', 'merge.autostash', 'true'])
+	await git(repository, ['config', 'commit.gpgSign', 'true'])
+	await git(repository, ['config', 'merge.gpgSign', 'true'])
+	await git(repository, ['config', 'push.gpgSign', 'true'])
+	await git(repository, ['config', 'merge.verifySignatures', 'true'])
+	await git(repository, ['config', 'branch.sb/bosun.mergeOptions', '--no-commit'])
+}
+
+async function installFailingHooks(repository: string): Promise<void> {
+	const hooks = path.join(repository, '.git', 'hooks')
+	for (const name of ['pre-commit', 'pre-push']) {
+		const hook = path.join(hooks, name)
+		await writeFile(hook, '#!/bin/sh\nexit 91\n')
+		await chmod(hook, 0o755)
+	}
+}
+
+async function git(cwd: string, args: string[]): Promise<void> {
+	await execFileAsync('git', args, { cwd, env: { ...process.env, LC_ALL: 'C' } })
+}
+
+async function gitText(cwd: string, args: string[]): Promise<string> {
+	const result = await execFileAsync('git', args, {
+		cwd,
+		env: { ...process.env, LC_ALL: 'C' },
+		encoding: 'utf8'
+	})
+	return result.stdout.trim()
+}