Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

56.5 KB
Raw Blame
import { execFile } from 'node:child_process'
import { mkdir, mkdtemp, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { promisify } from 'node:util'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { encryptDownFrame, encryptRpcResult } from './e2ee/applicationFrames.js'
import { placeholderBranch, sessionBranchNames, worktreeFolderName } from './agentNames.js'
import { nameBranchAfterSession } from './branchNaming.js'
import { fetchStartBase, harnessMadeWorktree, prepareGitProject, readGitProject, validGitPath } from './gitProject.js'
import { cloneRepository, parseProjectFolder, prepareProjectFolder } from './projectFolder.js'
import { engineSessionTitle, namingTitle } from './sessionTitle.js'

const exec = promisify(execFile)
// Real Git, several worktrees a test: slower than the default 5s under a full, parallel run.
describe('launch Git preparation', { timeout: 30_000 }, () => {
  let root: string, repo: string
  const git = async (...args: string[]) => (await exec('git', ['-C', repo, ...args])).stdout.trim()
  /** The fixture builds its repos in the temp directory, outside the browsable home, so each read
   *  names that root — exactly as the daemon names the workspaces its agents are running in. */
  const read = (path: string, options: { refresh?: boolean } = {}) =>
    readGitProject(path, { ...options, knownRoots: [root] })
  beforeEach(async () => {
    root = await mkdtemp(join(tmpdir(), 'harness-git-test-'))
    repo = join(root, 'project with spaces')
    await mkdir(repo)
    await git('init', '-b', 'main')
    await git('config', 'user.name', 'Test')
    await git('config', 'user.email', '[email protected]')
    await git('config', 'commit.gpgsign', 'false')
    await git('config', 'core.hooksPath', '/dev/null')
    await mkdir(join(repo, 'src'))
    await writeFile(join(repo, 'src', 'value'), 'main')
    await git('add', '.')
    await git('commit', '-m', 'initial')
    await git('switch', '-c', 'feature')
    await writeFile(join(repo, 'src', 'value'), 'feature')
    await git('commit', '-am', 'feature')
    await git('update-ref', 'refs/remotes/origin/feature', 'HEAD')
    await git('symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/feature')
    await git('switch', 'main')
  })
  afterEach(async () => { vi.unstubAllEnvs(); await rm(root, { recursive: true, force: true }) })
  const options = () => ({ root: join(root, 'harnesses'), label: 'Codex', now: () => new Date(2026, 8, 21, 12, 0) })
  const prepare = (source: 'worktree' | 'branch', branchRef = 'refs/heads/feature', path = repo, extra: Record<string, unknown> = {}) =>
    prepareProjectFolder(parseProjectFolder({ projectSource: source, gitSource: path, branchRef, ...extra })!, options())
  const worktrees = () => join(root, 'harnesses', 'worktrees', 'project with spaces')
  const current = async (path: string) => (await exec('git', ['-C', path, 'branch', '--show-current'])).stdout.trim()

  // 2026-10-30: the desktop's New Swarm makes its PM's worktree itself; the daemon trusts it for Claude Code only on this.
  it('knows a worktree Harness made from the person\'s own checkout and worktrees', async () => {
    const harnesses = join(root, 'harnesses')
    const made = await prepareGitProject(repo, { root: harnesses, worktree: true, branchName: 'tidy-badger' })
    expect(await harnessMadeWorktree(made, harnesses)).toBe(true)
    const own = join(harnesses, 'worktrees', 'own')
    await git('worktree', 'add', '-b', 'mine', own)
    expect(await harnessMadeWorktree(own, harnesses)).toBe(false)
    expect(await harnessMadeWorktree(repo, harnesses)).toBe(false)
    expect(await harnessMadeWorktree(join(harnesses, 'worktrees'), harnesses)).toBe(false)
    expect(await harnessMadeWorktree(join(root, 'missing'), harnesses)).toBe(false)
  })

  it('encrypts Git metadata requests and replies', () => {
    expect(encryptDownFrame('git_project_info')).toBe(true)
    expect(encryptRpcResult('git_project_info_result')).toBe(true)
  })

  it('never runs a program the repository names as its fsmonitor', async () => {
    const marker = join(root, 'fsmonitor-ran')
    const hook = join(root, 'fsmonitor.sh')
    await writeFile(hook, `#!/bin/sh\ntouch '${marker}'\n`, { mode: 0o755 })
    await git('config', 'core.fsmonitor', hook)
    await read(repo)
    await prepare('branch', 'refs/heads/feature')
    await expect(readFile(marker)).rejects.toThrow()
  })

  it('reads local and remote branches without switching or creating anything', async () => {
    expect(await read(repo)).toMatchObject({ isGit: true, branch: 'main', branches: [
      { ref: 'refs/heads/feature', name: 'feature', remote: false },
      { ref: 'refs/heads/main', name: 'main', remote: false },
      { ref: 'refs/remotes/origin/feature', name: 'origin/feature', remote: true },
    ] })
    expect(await git('branch', '--show-current')).toBe('main')
    expect(await git('worktree', 'list', '--porcelain')).not.toContain('harness/')
    expect(await read(root)).toMatchObject({ isGit: false })
    expect(await read('relative/path')).toEqual({ error: 'INVALID_PATH' })
  })

  it('runs git only inside the browsable home and the workspaces it was given', async () => {
    // No known roots: the fixture's repo is in the temp directory, outside the home folder.
    expect(await readGitProject(repo)).toEqual({ error: 'FORBIDDEN' })
    expect(await readGitProject(repo, { knownRoots: [root] })).toMatchObject({ isGit: true })
    // Named inside an allowed root, pointing outside it: the real path is what decides.
    const outside = await mkdtemp(join(tmpdir(), 'harness-git-outside-'))
    const allowed = await mkdtemp(join(tmpdir(), 'harness-git-allowed-'))
    try {
      await symlink(repo, join(allowed, 'link'))
      expect(await readGitProject(join(allowed, 'link'), { knownRoots: [allowed] })).toEqual({ error: 'FORBIDDEN' })
      // Gone, not refused: a deleted folder answers the way running git in it always did.
      expect(await readGitProject(join(outside, 'gone'), { knownRoots: [outside] })).toEqual({ isGit: false, branches: [] })
    } finally {
      await rm(outside, { recursive: true, force: true })
      await rm(allowed, { recursive: true, force: true })
    }
  })

  it('discovers a newly pushed branch without fetching objects, then fetches only on Start', async () => {
    const remote = join(root, 'remote.git')
    const clone = join(root, 'other computer')
    await git('clone', '--bare', repo, remote)
    await git('clone', '--no-local', '--single-branch', '--branch', 'main', remote, clone)
    const there = async (...args: string[]) => (await exec('git', ['-C', clone, ...args])).stdout.trim()
    await git('remote', 'add', 'origin', remote)
    await git('switch', '-c', 'feat/toolbar-onboarding')
    await writeFile(join(repo, 'src', 'value'), 'new remote work')
    await git('commit', '-am', 'new work')
    await git('push', 'origin', 'feat/toolbar-onboarding')
    await writeFile(join(clone, 'src', 'value'), 'unsaved local work')
    const refs = await there('show-ref')
    expect((await read(clone) as any).branches.map((b: any) => b.name)).not.toContain('origin/feat/toolbar-onboarding')
    const info = await read(clone, { refresh: true })
    expect(info).toMatchObject({ refreshed: true, branch: 'main', branches: expect.arrayContaining([
      { ref: 'refs/remotes/origin/feat/toolbar-onboarding', name: 'origin/feat/toolbar-onboarding', remote: true },
    ]) })
    expect(await there('show-ref')).toBe(refs)
    expect(await readFile(join(clone, 'src', 'value'), 'utf8')).toBe('unsaved local work')
    const path = await prepare('worktree', 'refs/remotes/origin/feat/toolbar-onboarding', clone,
      { branchName: 'feat/toolbar-onboarding' })
    expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('new remote work')
    expect(await there('branch', '--show-current')).toBe('main')
  })

  it('keeps saved branches from unreachable remotes and refreshes the others', async () => {
    const remote = join(root, 'remote.git')
    await git('clone', '--bare', repo, remote)
    await git('remote', 'add', 'origin', join(root, 'missing.git'))
    await git('remote', 'add', 'upstream', remote)
    const info = await read(repo, { refresh: true })
    expect(info).toMatchObject({ refreshed: false, branches: expect.arrayContaining([
      { ref: 'refs/remotes/origin/feature', name: 'origin/feature', remote: true },
      { ref: 'refs/remotes/upstream/main', name: 'upstream/main', remote: true },
    ]) })
    expect(await git('branch', '--show-current')).toBe('main')
  })

  it('removes deleted remote choices after a successful lookup without changing saved refs', async () => {
    const remote = join(root, 'remote.git')
    await git('clone', '--bare', repo, remote)
    await git('remote', 'add', 'origin', remote)
    await exec('git', ['-C', remote, 'branch', '-D', 'feature'])
    const info = await read(repo, { refresh: true }) as { branches: Array<{ name: string }> }
    expect(info.branches.map(b => b.name)).toContain('feature')
    expect(info.branches.map(b => b.name)).not.toContain('origin/feature')
    expect(await git('show-ref', '--verify', 'refs/remotes/origin/feature')).toBeTruthy()
  })

  it('starts concurrent worktrees on distinct branches from the chosen ref and preserves dirty source files', async () => {
    await writeFile(join(repo, 'src', 'value'), 'my uncommitted work')
    const paths = await Promise.all([prepare('worktree'), prepare('worktree', 'refs/remotes/origin/feature')])
    expect(new Set(paths).size).toBe(2)
    const branches = []
    for (const path of paths) {
      expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('feature')
      const branch = (await exec('git', ['-C', path, 'branch', '--show-current'])).stdout.trim()
      expect(branch).toMatch(/^[a-z]+-[a-z]+(-\d+)?$/)
      branches.push(branch)
    }
    expect(new Set(branches).size).toBe(2)
    expect(await readFile(join(repo, 'src', 'value'), 'utf8')).toBe('my uncommitted work')
    expect(await git('branch', '--show-current')).toBe('main')
  })

  it('makes up a two-word branch no branch uses, in a folder named for it, grouped by repository', async () => {
    expect(placeholderBranch([], () => 0)).toBe('amber-badger')
    expect(placeholderBranch(['refs/heads/amber-badger', 'amber-badger-2'], () => 0)).toBe('amber-badger-3')
    expect(worktreeFolderName('deehw/brave-otter')).toBe('brave-otter')
    expect(worktreeFolderName('fix/login page')).toBe('loginpage')
    // Two words when both carry the meaning.
    expect(sessionBranchNames('Worktree and branches organization')).toEqual(['worktree-branches', 'worktree-branches-organization'])
    expect(sessionBranchNames('Fix the harness list order')).toEqual(['harness-list', 'harness-list-order'])
    expect(sessionBranchNames('Add dark mode to settings')).toEqual(['dark-mode', 'dark-mode-settings'])
    expect(sessionBranchNames('Review and fix flaky tests')).toEqual(['flaky-tests'])
    expect(sessionBranchNames('Portable harnesses, launch models')).toEqual(['portable-harnesses', 'portable-harnesses-launch'])
    expect(sessionBranchNames('Release 0.3.1 notes')).toEqual(['release-notes'])
    expect(sessionBranchNames('Café résumé')).toEqual(['cafe-resume'])
    // One word when the second is generic, the two-word name kept for a clash.
    expect(sessionBranchNames('✳ Fix: the login page — redirects twice?')).toEqual(['login', 'login-page', 'login-page-redirects'])
    expect(sessionBranchNames('Onboarding experience')).toEqual(['onboarding', 'onboarding-experience'])
    expect(sessionBranchNames('UI polish')).toEqual(['ui', 'ui-polish'])
    // One word when that is all the title has.
    expect(sessionBranchNames('Onboarding')).toEqual(['onboarding'])
    expect(sessionBranchNames('Fix')).toEqual(['fix'])
    expect(sessionBranchNames('0.3.1')).toEqual(['0-3', '0-3-1'])
    expect(sessionBranchNames('a'.repeat(30) + ' ' + 'b'.repeat(30))).toEqual(['a'.repeat(24) + '-' + 'b'.repeat(24)])
    // Real session titles from Claude Code, Codex and this repository's PRs (2026-09-25).
    for (const [title, name] of [
      ['Catch up on autonomous-grid', 'autonomous-grid'],
      ['ok catch up on this landing page. we', 'landing'],
      ['Look at my Chrome. Open the file, au', 'chrome'],
      ['What time is it', 'time'],
      ['Build simple Pacman game', 'pacman-game'],
      ['Respond to greeting', 'greeting'],
      ['Define GPU Pod concept', 'gpu-pod'],
      ['Research roleplay app names', 'roleplay-app'],
      ['Device stuck issue', 'device-stuck'],
      ['Harness landing page redesign', 'harness-landing'],
      ['Review inventory protection', 'inventory-protection'],
      ['Remove Grid desktop app', 'grid-desktop'],
      ['feat(cli): add a Requesty preset to saved APIs', 'requesty-preset'],
      ['perf(desktop): redraw only terminal lines that changed', 'redraw-terminal'],
      ['fix(cli): unlink a linked dsh on remove instead of rmSync', 'unlink-linked'],
      ['feat(harnesses): add eight interactive experiences', 'interactive-experiences'],
      ['feat(login): record whether a sign-in came from the terminal', 'sign-in'],
      ['Study autonomous-code repo', 'autonomous-code'],
      ['8-bit CPU Fibonacci on iCEBreaker', '8-bit'],
      ['Restore split-right and split-down pane controls', 'split-right'],
      ['App auto-opening extra tabs', 'app-auto'],
      ['Explore print-in-place uses', 'print-place'],
      ['desktop: an on-screen banner for the same two moments', 'desktop'],
      ['Harness on-off switch', 'harness-switch'],
      ['Simplify Cmd-P with single-line results', 'cmd-p'],
      ['Give Harness Monitor its stacked-terminal identity', 'harness-monitor'],
      ['ci: CI and release workflows', 'ci-release'],
      ['catch up', 'catch'],
    ] as const) expect(sessionBranchNames(title)[0], title).toBe(name)
    expect(sessionBranchNames('The and of')).toEqual([])
    expect(sessionBranchNames('✳ ✳')).toEqual([])
    expect(sessionBranchNames(null)).toEqual([])
    const made = [await prepare('worktree'), await prepare('worktree')]
    expect(new Set(made).size).toBe(2)
    for (const path of made) {
      const branch = await current(path)
      expect(branch).toMatch(/^[a-z]+-[a-z]+(-\d+)?$/)
      expect(path).toBe(join(worktrees(), worktreeFolderName(branch)))
      expect(await git('config', '--get', `branch.${branch}.harness`)).toBe('placeholder')
    }
  })

  it('creates a named branch once, and refuses names Git would not take', async () => {
    const named = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'fix/login' })
    expect(named).toBe(join(worktrees(), 'login'))
    expect(await current(named)).toBe('fix/login')
    expect(await git('config', '--get', 'branch.fix/login.harness')).toBe('created')
    const made = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
    expect(await current(made)).toBe('quiet-owl')
    expect(await git('config', '--get', 'branch.quiet-owl.harness')).toBe('placeholder')
    const info = await read(repo) as { branches: Array<{ name: string; harness?: true }> }
    expect(info.branches.filter(b => b.harness).map(b => b.name).sort()).toEqual(['fix/login', 'quiet-owl'])
    await expect(prepare('worktree', 'refs/heads/feature', repo, { branchName: 'fix/login' })).rejects.toMatchObject({ code: 'BRANCH_EXISTS' })
    await expect(prepare('worktree', 'refs/heads/feature', repo, { branchName: 'bad..name' })).rejects.toMatchObject({ code: 'INVALID_BRANCH' })
    for (const extra of [{ branchName: '-x' }, { branchName: 'a b' }, { branchName: 'ok', branchMode: 'other' }]) {
      expect(() => parseProjectFolder({ projectSource: 'worktree', gitSource: repo, ...extra })).toThrow()
    }
  })

  // Desktop makes the name up before the start and keeps it; the person never chose it, so taken is no refusal.
  it('gives a made-up worktree branch name that is already taken the next free number', async () => {
    await git('branch', 'quiet-owl')
    await git('branch', 'quiet-owl-2')
    const made = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
    expect(await current(made)).toBe('quiet-owl-3')
    expect(await git('config', '--get', 'branch.quiet-owl-3.harness')).toBe('placeholder')
  })

  it('makes a new branch for the folder itself, keeping its uncommitted work, and refuses one that exists', async () => {
    await writeFile(join(repo, 'src', 'value'), 'in progress')
    expect(await prepare('branch', 'refs/heads/login-fix', repo, { branchName: 'login-fix' })).toBe(repo)
    expect(await git('branch', '--show-current')).toBe('login-fix')
    expect(await readFile(join(repo, 'src', 'value'), 'utf8')).toBe('in progress')
    await expect(prepare('branch', 'refs/heads/feature', repo, { branchName: 'feature' })).rejects.toMatchObject({ code: 'BRANCH_EXISTS' })
    expect(() => parseProjectFolder({ projectSource: 'branch', gitSource: repo, branchRef: 'refs/heads/other', branchName: 'login-fix' })).toThrow()
  })

  it('names a made-up worktree branch after its session once, and never a pushed or chosen one', async () => {
    const path = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
    expect(await nameBranchAfterSession(path, null)).toBeNull()
    expect(await nameBranchAfterSession(path, 'Worktree and branches organization')).toBe('worktree-branches')
    expect(await current(path)).toBe('worktree-branches')
    expect(await git('config', '--get', 'branch.worktree-branches.harness')).toBe('created')
    expect(await nameBranchAfterSession(path, 'A later name')).toBeNull()
    expect(await current(path)).toBe('worktree-branches')
    // Taken, with no third word to add: a number.
    const second = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'calm-fox', branchMode: 'placeholder' })
    expect(await nameBranchAfterSession(second, 'Fix the worktree branches')).toBe('worktree-branches-2')
    // A clash takes the fuller name, then a third word, then numbers the shortest.
    const named = async (title: string, placeholders: string[]) => {
      const out = []
      for (const branchName of placeholders) {
        const at = await prepare('worktree', 'refs/heads/feature', repo, { branchName, branchMode: 'placeholder' })
        out.push(await nameBranchAfterSession(at, title))
      }
      return out
    }
    expect(await named('Fix the login page', ['keen-lynx', 'tidy-heron', 'rosy-finch']))
      .toEqual(['login', 'login-page', 'login-2'])
    expect(await named('Harness monitor DDOS requests', ['warm-ibis', 'glad-crane', 'bold-lark']))
      .toEqual(['harness-monitor', 'harness-monitor-ddos', 'harness-monitor-2'])
    // A repository's own names are never taken, whatever the title says.
    // This repository has no `master`: only the reserved list keeps a session from taking it.
    expect(await git('branch', '--list', 'master')).toBe('')
    expect(await named('Master', ['sunny-moose'])).toEqual(['master-2'])
    // Case does not tell names apart: on macOS `Deploy` and `deploy` are one ref file.
    await git('update-ref', 'refs/remotes/origin/Deploy', 'main')
    expect(await named('Deploy', ['noble-reef'])).toEqual(['deploy-2'])
    // A name a remote has is taken too.
    const third = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-fox', branchMode: 'placeholder' })
    await git('update-ref', 'refs/remotes/origin/onboarding', 'main')
    expect(await nameBranchAfterSession(third, 'Onboarding experience')).toBe('onboarding-experience')
    const chosen = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'fix/mine' })
    expect(await nameBranchAfterSession(chosen, 'Anything')).toBeNull()
    const pushed = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'sunny-owl', branchMode: 'placeholder' })
    await git('config', 'branch.sunny-owl.remote', 'origin')
    expect(await nameBranchAfterSession(pushed, 'Anything')).toBeNull()
    expect(await current(pushed)).toBe('sunny-owl')
  })

  it('waits through Codex rename statuses before naming the worktree after its conversation', async () => {
    const path = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
    const session = { engine: 'codex', sessionId: 'naming-test', codexHome: join(root, 'codex'), cwd: path }
    await writeFile(join(path, 'src', 'value'), 'work in progress')
    for (const status of ['Starting | quiet-owl', 'renaming... ⠹', 'renaming… ⠴']) {
      const title = namingTitle(engineSessionTitle(session, status), session)
      expect(await nameBranchAfterSession(path, title)).toBeNull()
      expect(await current(path)).toBe('quiet-owl')
      expect(await git('config', '--get', 'branch.quiet-owl.harness')).toBe('placeholder')
    }

    await mkdir(session.codexHome)
    await writeFile(join(session.codexHome, 'session_index.jsonl'), JSON.stringify({
      id: session.sessionId, thread_name: 'Discuss configurable harness agents',
    }) + '\n')
    const title = namingTitle(engineSessionTitle(session, 'renaming... ⠴'), session)
    expect(await nameBranchAfterSession(path, title)).toBe('configurable-harness')
    expect(await current(path)).toBe('configurable-harness')
    expect(await git('config', '--get', 'branch.configurable-harness.harness')).toBe('created')
    expect(await git('rev-parse', 'configurable-harness')).toBe(await git('rev-parse', 'feature'))
    expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('work in progress')
    expect(await nameBranchAfterSession(path, 'A later conversation title')).toBeNull()
    expect(await current(path)).toBe('configurable-harness')
  })

  it('checks out an existing branch as it is in a new worktree, once', async () => {
    await git('branch', 'topic', 'main')
    const path = await prepare('worktree', 'refs/heads/topic', repo, { branchName: 'topic', branchMode: 'existing' })
    expect(path).toBe(join(worktrees(), 'topic'))
    expect(await current(path)).toBe('topic')
    expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
    await expect(prepare('worktree', 'refs/heads/topic', repo, { branchName: 'topic', branchMode: 'existing' }))
      .rejects.toMatchObject({ code: 'BRANCH_IN_USE' })
  })

  it('fetches a remote base first, reports the default, and tracks a remote branch under its own name', async () => {
    const origin = join(root, 'origin.git'), upstream = join(root, 'upstream')
    await exec('git', ['clone', '--quiet', '--bare', repo, origin])
    await git('remote', 'add', 'origin', origin)
    await git('fetch', '--quiet', 'origin')
    await git('remote', 'set-head', 'origin', 'main')
    expect(await read(repo)).toMatchObject({ defaultRef: 'refs/remotes/origin/main' })
    await exec('git', ['clone', '--quiet', origin, upstream])
    const up = (...args: string[]) => exec('git', ['-C', upstream, '-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=/dev/null', ...args])
    await writeFile(join(upstream, 'src', 'value'), 'pushed')
    await up('commit', '-qam', 'pushed')
    await up('push', '--quiet', 'origin', 'main', 'main:fix/typo')
    await git('fetch', '--quiet', 'origin', 'fix/typo:refs/remotes/origin/fix/typo')
    const fresh = await prepare('worktree', 'refs/remotes/origin/main', repo, { branchName: 'harness/fresh' })
    expect(await readFile(join(fresh, 'src', 'value'), 'utf8')).toBe('pushed')
    await expect(exec('git', ['-C', fresh, 'rev-parse', '--abbrev-ref', '@{upstream}'])).rejects.toThrow()
    // A local branch starts from the newer of itself and its upstream.
    await git('branch', '--set-upstream-to=origin/main', 'main')
    await git('update-ref', 'refs/remotes/origin/main', 'main')
    const behind = await prepare('worktree', 'refs/heads/main', repo, { branchName: 'from-behind' })
    expect(await readFile(join(behind, 'src', 'value'), 'utf8')).toBe('pushed')
    await writeFile(join(repo, 'src', 'value'), 'local')
    await git('-c', 'user.name=Test', '-c', '[email protected]', 'commit', '-qam', 'local')
    const ahead = await prepare('worktree', 'refs/heads/main', repo, { branchName: 'from-ahead' })
    expect(await readFile(join(ahead, 'src', 'value'), 'utf8')).toBe('local')
    const tracking = await prepare('worktree', 'refs/remotes/origin/fix/typo', repo, { branchName: 'fix/typo' })
    expect((await exec('git', ['-C', tracking, 'rev-parse', '--abbrev-ref', '@{upstream}'])).stdout.trim()).toBe('origin/fix/typo')
  })

  describe('a Swarm start that names no branch', () => {
    // A Swarm host clones a project once and reuses that checkout for every Builder, so its HEAD falls behind the
    // remote. `branchBase: 'default'` is what a Swarm start without `branchRef` asks for.
    let origin: string, managed: string
    const identity = ['-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=/dev/null']
    const inClone = (...args: string[]) => exec('git', ['-C', managed, ...args]).then(out => out.stdout.trim())
    /** What the worktree a Swarm start made shows of `src/value`. */
    const swarmStart = async (extra: Record<string, unknown> = {}, path = managed) =>
      readFile(join(await prepareProjectFolder(parseProjectFolder({ projectSource: 'worktree', gitSource: path, branchName: 'super-tab/start-1',
        branchBase: 'default', ...extra })!, options()), 'src', 'value'), 'utf8')
    beforeEach(async () => {
      origin = join(root, 'origin.git'); managed = join(root, 'managed')
      await exec('git', ['clone', '--quiet', '--bare', repo, origin])
      await exec('git', ['clone', '--quiet', origin, managed])
    })
    /** Someone pushes to the remote's default branch after the managed clone was made. */
    const pushToOrigin = async (value: string) => {
      const pusher = join(root, 'pusher')
      await exec('git', ['clone', '--quiet', origin, pusher])
      await writeFile(join(pusher, 'src', 'value'), value)
      await exec('git', ['-C', pusher, ...identity, 'commit', '-qam', value])
      await exec('git', ['-C', pusher, 'push', '--quiet', 'origin', 'main'])
    }

    it('starts from the remote default branch, fetched first, and leaves the checkout\'s own branch where it was', async () => {
      const before = await inClone('rev-parse', 'HEAD')
      await pushToOrigin('pushed')
      expect(await swarmStart()).toBe('pushed')
      expect(await inClone('rev-parse', 'HEAD')).toBe(before)
      expect(await inClone('rev-parse', 'refs/remotes/origin/main')).not.toBe(before)
    })

    it('starts from what the checkout has when the fetch fails', async () => {
      await pushToOrigin('pushed')
      await inClone('remote', 'set-url', 'origin', join(root, 'gone.git'))
      expect(await swarmStart()).toBe('main')
    })

    it('starts from HEAD in a repository with no remote default branch', async () => {
      const local = join(root, 'local-only')
      await mkdir(local)
      await exec('git', ['-C', local, 'init', '-q', '-b', 'trunk'])
      await mkdir(join(local, 'src'))
      await writeFile(join(local, 'src', 'value'), 'trunk')
      await exec('git', ['-C', local, 'add', '.'])
      await exec('git', ['-C', local, ...identity, 'commit', '-qm', 'initial'])
      expect(await swarmStart({}, local)).toBe('trunk')
    })

    it('names the default branch when the remote has no origin/HEAD but has main', async () => {
      await pushToOrigin('pushed')
      await inClone('remote', 'set-head', 'origin', '--delete')
      expect(await swarmStart()).toBe('pushed')
    })

    it('fetches nothing for another person\'s Swarm start: its host fetched with the app\'s token, and the worktree starts from that', async () => {
      const before = await inClone('rev-parse', 'refs/remotes/origin/main')
      await pushToOrigin('pushed')
      // The daemon's own git setup is never asked: offline, the worktree starts from what the checkout has.
      const offline = await prepareProjectFolder({ source: 'worktree', gitSource: managed, branchName: 'super-tab/start-1', fromDefaultBranch: true, offline: true }, options())
      expect(await readFile(join(offline, 'src', 'value'), 'utf8')).toBe('main')
      expect(await inClone('rev-parse', 'refs/remotes/origin/main')).toBe(before)
      // Only the daemon sets it: a client cannot ask for it.
      expect(parseProjectFolder({ projectSource: 'worktree', gitSource: managed, branchBase: 'default', offline: true })).not.toHaveProperty('offline')
      // The host's fetch, with the environment it is given in place of the daemon's.
      const env = { ...process.env, GIT_CONFIG_PARAMETERS: `'harness.fixture'='yes'` }
      expect(await fetchStartBase(managed, env)).toBe(true)
      expect(await inClone('rev-parse', 'refs/remotes/origin/main')).not.toBe(before)
      const folder = await prepareProjectFolder({ source: 'worktree', gitSource: managed, branchName: 'super-tab/start-2', fromDefaultBranch: true, offline: true }, options())
      expect(await readFile(join(folder, 'src', 'value'), 'utf8')).toBe('pushed')
    })

    it('a host\'s fetch does nothing outside a checkout or without a default branch, and says when it could not fetch', async () => {
      expect(await fetchStartBase('relative/path', process.env)).toBe(false)
      expect(await fetchStartBase(join(root, 'nowhere'), process.env)).toBe(false)
      const local = join(root, 'no-remote')
      await mkdir(local)
      await exec('git', ['-C', local, 'init', '-q', '-b', 'trunk'])
      await exec('git', ['-C', local, ...identity, 'commit', '-q', '--allow-empty', '-m', 'initial'])
      expect(await fetchStartBase(local, process.env)).toBe(false)
      await inClone('remote', 'set-url', 'origin', join(root, 'gone.git'))
      expect(await fetchStartBase(managed, process.env)).toBe(false)
    })

    it('starts from the branch it is given, not the default one', async () => {
      await pushToOrigin('pushed')
      expect(await swarmStart({ branchBase: undefined, branchRef: 'refs/remotes/origin/feature' })).toBe('feature')
    })

    it('is not what a start from Desktop or the CLI does: without the flag the checkout\'s HEAD is used and nothing is fetched', async () => {
      const before = await inClone('rev-parse', 'refs/remotes/origin/main')
      await pushToOrigin('pushed')
      expect(await swarmStart({ branchBase: undefined })).toBe('main')
      expect(await inClone('rev-parse', 'refs/remotes/origin/main')).toBe(before)
    })

    it('is accepted only for a worktree that names no branch', () => {
      const parse = (extra: Record<string, unknown>) => () => parseProjectFolder({ projectSource: 'worktree', gitSource: managed,
        branchName: 'super-tab/start-1', ...extra })
      expect(parse({ branchBase: 'default' })()).toMatchObject({ source: 'worktree', fromDefaultBranch: true })
      expect(parseProjectFolder({ projectSource: 'worktree', gitSource: managed, branchBase: 'default' })).toMatchObject({ fromDefaultBranch: true })
      expect(parse({})()).not.toHaveProperty('fromDefaultBranch')
      expect(parse({ branchBase: 'default', branchRef: 'refs/remotes/origin/main' })).toThrow()
      expect(parse({ branchBase: 'main' })).toThrow()
      expect(parse({ branchBase: true })).toThrow()
      expect(() => parseProjectFolder({ projectSource: 'branch', gitSource: managed, branchRef: 'refs/heads/main', branchBase: 'default' })).toThrow()
    })

    it('does not change a direct prepareGitProject call', async () => {
      await pushToOrigin('pushed')
      const path = await prepareGitProject(managed, { root: join(root, 'harnesses'), worktree: true, branchName: 'plain' })
      expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
      const asked = await prepareGitProject(managed, { root: join(root, 'harnesses'), worktree: true, branchName: 'asked', fromDefaultBranch: true })
      expect(await readFile(join(asked, 'src', 'value'), 'utf8')).toBe('pushed')
    })
  })

  describe('a Swarm start for another person\'s work in a blob-less, single-branch clone', () => {
    // The project clone fetches only the default branch, and file contents as they are needed (projectFolder.ts). A start
    // for another person's work is offline: its host fetches with the app's token first, and the owner's login is never
    // used, so nothing may be fetched lazily while its worktree is made.
    let origin: string, managed: string, contacts: string
    const identity = ['-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=/dev/null']
    const inClone = (...args: string[]) => exec('git', ['-C', managed, ...args]).then(out => out.stdout.trim())
    const offlineStart = (name: string, extra: Partial<{ branchRef: string }> = {}) => prepareProjectFolder({ source: 'worktree', gitSource: managed,
      branchName: name, offline: true, ...(extra.branchRef ? { branchRef: extra.branchRef } : { fromDefaultBranch: true }) }, options())
    /** Someone pushes [value] to [branch] after the managed clone was made. */
    const pushToOrigin = async (branch: string, value: string) => {
      const pusher = join(root, `pusher-${branch}`)
      await exec('git', ['clone', '--quiet', '--branch', branch, origin, pusher])
      await writeFile(join(pusher, 'src', 'value'), value)
      await exec('git', ['-C', pusher, ...identity, 'commit', '-qam', value])
      await exec('git', ['-C', pusher, 'push', '--quiet', 'origin', branch])
    }
    beforeEach(async () => {
      origin = join(root, 'origin.git'); managed = join(root, 'managed'); contacts = join(root, 'contacts.log')
      await exec('git', ['clone', '--quiet', '--bare', repo, origin])
      for (const key of ['uploadpack.allowFilter', 'uploadpack.allowAnySHA1InWant']) await exec('git', ['-C', origin, 'config', key, 'true'])
      await cloneRepository(`file://${origin}`, managed)
      // Every time this clone asks the origin for anything, it says so.
      const uploadPack = join(root, 'upload-pack')
      await writeFile(uploadPack, `#!/bin/sh\necho contact >> '${contacts}'\nexec git-upload-pack "$@"\n`, { mode: 0o755 })
      await inClone('config', 'remote.origin.uploadpack', uploadPack)
    })

    it('fetches the start\'s own base branch and its files with the token, so its offline worktree needs nothing else', async () => {
      await pushToOrigin('feature', 'feature, later')
      expect(await fetchStartBase(managed, process.env, 'refs/remotes/origin/feature')).toBe(true)
      await rm(origin, { recursive: true })
      const folder = await offlineStart('super-tab/start-1', { branchRef: 'refs/remotes/origin/feature' })
      expect(await readFile(join(folder, 'src', 'value'), 'utf8')).toBe('feature, later')
    })

    it('fetches the default branch and its files when the start names no branch', async () => {
      await pushToOrigin('main', 'main, later')
      expect(await fetchStartBase(managed, process.env)).toBe(true)
      await rm(origin, { recursive: true })
      expect(await readFile(join(await offlineStart('super-tab/start-1'), 'src', 'value'), 'utf8')).toBe('main, later')
    })

    it('never fetches missing files while making an offline worktree', async () => {
      await pushToOrigin('main', 'main, later')
      // The branch, without its files: what a fetch with no file contents leaves.
      await inClone('fetch', '--quiet', '--no-tags', 'origin', '+refs/heads/main:refs/remotes/origin/main')
      await rm(contacts, { force: true })
      // The start says what is wrong: the branch's files are not here, not Git or folder permissions.
      await expect(offlineStart('super-tab/start-1')).rejects.toThrow("This branch's files could not be fetched for the start. Check the connection, then retry.")
      expect(await readFile(contacts, 'utf8').catch(() => '')).toBe('')
    })

    it('says so when the files of a start\'s branch could not be fetched', async () => {
      await pushToOrigin('main', 'main, later')
      // The branch comes; the request for its files fails.
      const flaky = join(root, 'flaky-upload-pack'), served = join(root, 'served')
      await writeFile(flaky, `#!/bin/sh\n[ -e '${served}' ] && exit 1\ntouch '${served}'\nexec git-upload-pack "$@"\n`, { mode: 0o755 })
      await inClone('config', 'remote.origin.uploadpack', flaky)
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
      try {
        expect(await fetchStartBase(managed, process.env)).toBe(true)
        expect(warn).toHaveBeenCalledWith(expect.stringContaining('could not fetch the files of refs/remotes/origin/main'))
      } finally { warn.mockRestore() }
    })

    // GIT_NO_LAZY_FETCH is read only by git 2.44 and later (Ubuntu 22.04 ships 2.34, Debian 12 2.39): review 1 of #2770.
    it('never fetches missing files offline even with a git that ignores GIT_NO_LAZY_FETCH', async () => {
      await pushToOrigin('main', 'main, later')
      await inClone('fetch', '--quiet', '--no-tags', 'origin', '+refs/heads/main:refs/remotes/origin/main')
      await rm(contacts, { force: true })
      const realGit = (await exec('sh', ['-c', 'command -v git'])).stdout.trim()
      const olderGit = join(root, 'older-git')
      await mkdir(olderGit)
      await writeFile(join(olderGit, 'git'), `#!/bin/sh\nunset GIT_NO_LAZY_FETCH\nexec '${realGit}' "$@"\n`, { mode: 0o755 })
      vi.stubEnv('PATH', `${olderGit}:${process.env.PATH}`)
      await expect(offlineStart('super-tab/start-1')).rejects.toThrow()
      expect(await readFile(contacts, 'utf8').catch(() => '')).toBe('')
    })
  })

  describe('a worktree whose git is slow or fails', () => {
    const harnesses = () => join(root, 'harnesses')
    const listed = () => git('worktree', 'list', '--porcelain')
    /** A file checked out through the `name` filter, whose smudge command is [smudge]. Set after the
     *  commit: `git add` needs no filter. */
    const filtered = async (name: string, smudge: string) => {
      await writeFile(join(repo, '.gitattributes'), `filtered filter=${name}\n`)
      await writeFile(join(repo, 'filtered'), 'content\n')
      await git('add', '.')
      await git('commit', '-m', 'filtered file')
      await git('config', `filter.${name}.smudge`, smudge)
      await git('config', `filter.${name}.required`, 'true')
    }
    afterEach(() => { vi.restoreAllMocks() })

    it('uses a checkout that finished although git was still running at the timeout, and stops what git left running', async () => {
      // git checked everything out and is in its post-checkout hook when the time runs out.
      const hooks = join(root, 'hooks')
      await mkdir(hooks)
      const pidFile = join(root, 'hook.pid')
      await writeFile(join(hooks, 'post-checkout'), `#!/bin/sh\necho $$ > '${pidFile}'\nexec sleep 60\n`, { mode: 0o755 })
      await git('config', 'core.hooksPath', hooks)
      const path = await prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'slow', worktreeTimeout: 1_500 })
      expect(path).toBe(join(worktrees(), 'slow'))
      expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
      expect(await current(path)).toBe('slow')
      expect(await git('config', '--get', 'branch.slow.harness')).toBe('created')
      // Unlocked: git marks a worktree locked while it is being made.
      const real = await realpath(path)
      const entry = (await listed()).split(/\n\s*\n/).find(block => block.includes(`worktree ${real}`))
      expect(entry).toBeDefined()
      expect(entry).not.toContain('locked')
      const hookPid = Number((await readFile(pidFile, 'utf8')).trim())
      expect(() => process.kill(hookPid, 0)).toThrow()
    }, 20_000)

    it('removes the partial folder and its new branch when the checkout is cut off at the timeout', async () => {
      await filtered('slow', 'sleep 60; cat')
      await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'cut', worktreeTimeout: 1_500 }))
        .rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
      await expect(readFile(join(worktrees(), 'cut', 'src', 'value'))).rejects.toThrow()
      await expect(realpath(join(worktrees(), 'cut'))).rejects.toThrow()
      expect(await git('branch', '--list', 'cut')).toBe('')
      expect(await listed()).not.toContain('cut')
    }, 20_000)

    it('says why git failed, without credentials, and leaves no partial folder or new branch', async () => {
      const said = vi.spyOn(console, 'error').mockImplementation(() => {})
      await filtered('broken', "echo 'cannot reach https://robot:[email protected]/lfs' >&2; exit 1")
      await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'broken' }))
        .rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
      const lines = said.mock.calls.map(call => call.join(' ')).filter(line => line.startsWith('[worktree]'))
      expect(lines).toHaveLength(1)
      expect(lines[0]).toContain('exit 128')
      expect(lines[0]).toContain('cannot reach https://')
      expect(lines[0]).not.toContain('s3cret-token')
      await expect(realpath(join(worktrees(), 'broken'))).rejects.toThrow()
      expect(await git('branch', '--list', 'broken')).toBe('')
      expect(await listed()).not.toContain('broken')
      // The next start finds the name free.
      await git('config', '--unset', 'filter.broken.required')
      await git('config', 'filter.broken.smudge', 'cat')
      expect(await prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'broken' })).toBe(join(worktrees(), 'broken'))
    })

    it('leaves a registration that existed before the failed start, even one for the same folder', async () => {
      vi.spyOn(console, 'error').mockImplementation(() => {})
      // An earlier worktree at the folder this start picks, whose folder was deleted without `git worktree remove`.
      await git('worktree', 'add', '-b', 'earlier', '--', join(worktrees(), 'again'), 'main')
      await rm(join(worktrees(), 'again'), { recursive: true, force: true })
      await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'again' }))
        .rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
      expect(await listed()).toContain('branch refs/heads/earlier')
      expect(await git('branch', '--list', 'again')).toBe('')
    })

    it('never deletes a branch a person made at their own commit after the first check and before the add', async () => {
      vi.spyOn(console, 'error').mockImplementation(() => {})
      // git, as the daemon runs it, with the person's own `git branch mine feature` landing just after the name was checked.
      const realGit = (await exec('sh', ['-c', 'command -v git'])).stdout.trim()
      const bin = join(root, 'bin'), made = join(root, 'person-made-it')
      await mkdir(bin)
      await writeFile(join(bin, 'git'), `#!/bin/sh\nfor arg in "$@"; do if [ "$arg" = check-ref-format ] && [ ! -e '${made}' ]; then\n`
        + `  : > '${made}'; '${realGit}' -C '${repo}' branch mine feature\nfi; done\nexec '${realGit}' "$@"\n`, { mode: 0o755 })
      vi.stubEnv('PATH', `${bin}:${process.env.PATH}`)
      await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'mine' })).rejects.toMatchObject({ code: 'BRANCH_EXISTS' })
      expect(await git('rev-parse', 'mine')).toBe(await git('rev-parse', 'feature'))
      await expect(realpath(join(worktrees(), 'mine'))).rejects.toThrow()
      expect(await listed()).not.toContain('worktrees/project with spaces/mine')
    })

    it('logs none of a stateless GitHub token git printed', async () => {
      const said = vi.spyOn(console, 'error').mockImplementation(() => {})
      const payload = 'eyJpc3MiOiIxMjM0NTYifQ', signature = `${'s'.repeat(470)}-x_y`
      await filtered('leaky', `echo 'remote refused (token "ghs_123456_eyJhbGciOiJSUzI1NiJ9.${payload}.${signature}"), retry.' >&2; exit 1`)
      await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'leaky' })).rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
      const line = said.mock.calls.map(call => call.join(' ')).find(text => text.startsWith('[worktree]'))!
      expect(line).toContain('remote refused (token "')
      expect(line).not.toContain('ghs_123456_')
      expect(line).not.toContain(payload)
      expect(line).not.toContain('ssssssss')
      expect(line).not.toContain('-x_y')
    })

    describe('on Windows, where taskkill cannot stop what git started', () => {
      const platform = process.platform
      beforeEach(async () => {
        Object.defineProperty(process, 'platform', { value: 'win32', configurable: true })
        const bin = join(root, 'bin')
        await mkdir(bin)
        await writeFile(join(bin, 'taskkill'), '#!/bin/sh\necho \'ERROR: The process with PID 1 could not be terminated.\' >&2\nexit 1\n', { mode: 0o755 })
        vi.stubEnv('PATH', `${bin}:${process.env.PATH}`)
      })
      afterEach(() => { Object.defineProperty(process, 'platform', { value: platform, configurable: true }) })
      /** git checks out and exits; its post-checkout hook leaves a process behind, holding git's stderr, that ends after
       *  [seconds] by touching `ended`. */
      const leftBehind = async (seconds: number) => {
        const hooks = join(root, 'hooks')
        await mkdir(hooks)
        await writeFile(join(hooks, 'post-checkout'), `#!/bin/sh\n(sleep ${seconds}; : > '${join(root, 'ended')}') &\nexit 0\n`, { mode: 0o755 })
        await git('config', 'core.hooksPath', hooks)
      }

      it('waits for what git left running to end before it looks at the checkout, and says taskkill failed', async () => {
        const said = vi.spyOn(console, 'error').mockImplementation(() => {})
        await leftBehind(2)
        const path = await prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'outlived', worktreeTimeout: 1_500 })
        expect(await readFile(join(root, 'ended'), 'utf8')).toBe('')
        expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
        expect(said.mock.calls.map(call => call.join(' ')).join('\n')).toMatch(/\[worktree\] could not stop git.*could not be terminated/)
      }, 20_000)

      it('removes nothing while something git started may still be writing', async () => {
        const said = vi.spyOn(console, 'error').mockImplementation(() => {})
        await leftBehind(8)
        await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'still-running', worktreeTimeout: 1_500 }))
          .rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
        await expect(readFile(join(root, 'ended'))).rejects.toThrow()
        expect(await readFile(join(worktrees(), 'still-running', 'src', 'value'), 'utf8')).toBe('main')
        expect(said.mock.calls.map(call => call.join(' ')).join('\n')).toMatch(/\[worktree\] .*still running.*left as it is/)
      }, 20_000)
    })

    it('never deletes a branch that existed before the failed start', async () => {
      vi.spyOn(console, 'error').mockImplementation(() => {})
      await filtered('broken', 'exit 1')
      await git('branch', 'topic', 'main')
      const before = await git('rev-parse', 'topic')
      await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'topic', existingBranch: true }))
        .rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
      expect(await git('rev-parse', 'topic')).toBe(before)
      await expect(realpath(join(worktrees(), 'topic'))).rejects.toThrow()
      expect(await listed()).not.toContain('topic')
    })
  })

  it('copies ignored files named in .worktreeinclude into new worktrees', async () => {
    await writeFile(join(repo, '.gitignore'), '.env\n*.log\nlocal/\n')
    await writeFile(join(repo, '.worktreeinclude'), '.env\nlocal/\n')
    await writeFile(join(repo, '.env'), 'SECRET=1')
    await writeFile(join(repo, 'debug.log'), 'noise')
    await mkdir(join(repo, 'local'))
    await writeFile(join(repo, 'local', 'settings.json'), '{}')
    const path = await prepare('worktree')
    expect(await readFile(join(path, '.env'), 'utf8')).toBe('SECRET=1')
    expect(await readFile(join(path, 'local', 'settings.json'), 'utf8')).toBe('{}')
    await expect(readFile(join(path, 'debug.log'))).rejects.toThrow()
  })

  it('reads a linked worktree as its repository, and a worktree started from one joins the same repository', async () => {
    const linked = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'harness/linked' })
    const info = await read(join(linked, 'src'))
    expect(info).toMatchObject({ isGit: true, branch: 'harness/linked', mainBranch: 'main' })
    expect(await realpath((info as { mainFolder: string }).mainFolder)).toBe(await realpath(join(repo, 'src')))
    const branches = (info as { branches: Array<{ name: string; worktree?: string }> }).branches
    expect(await realpath(branches.find(branch => branch.name === 'harness/linked')!.worktree!)).toBe(await realpath(linked))
    expect(await realpath(branches.find(branch => branch.name === 'main')!.worktree!)).toBe(await realpath(repo))
    expect(await read(repo)).not.toHaveProperty('mainFolder')
    expect(await prepare('worktree', 'refs/heads/main', linked, { branchName: 'harness/second' })).toBe(join(worktrees(), 'second'))
  })

  it('keeps the selected subfolder in its new worktree', async () => {
    const path = await prepare('worktree', 'refs/heads/feature', join(repo, 'src'))
    expect(await readFile(join(path, 'value'), 'utf8')).toBe('feature')
    expect(path.endsWith('/src/')).toBe(false)
  })

  it('switches the shared folder only when requested, without forcing conflicting changes', async () => {
    expect(await prepare('branch')).toBe(repo)
    expect(await git('branch', '--show-current')).toBe('feature')
    await writeFile(join(repo, 'src', 'value'), 'keep this')
    await expect(prepare('branch', 'refs/heads/main')).rejects.toMatchObject({ code: 'BRANCH_SWITCH_FAILED' })
    expect(await git('branch', '--show-current')).toBe('feature')
    expect(await readFile(join(repo, 'src', 'value'), 'utf8')).toBe('keep this')
    expect(await git('stash', 'list')).toBe('')
    // Selecting the current branch is a no-op even with dirty files.
    expect(await prepare('branch')).toBe(repo)
    await git('checkout', '--', '.')
    await writeFile(join(repo, 'notes.txt'), 'untracked')
    await expect(prepare('branch', 'refs/heads/main')).rejects.toMatchObject({ code: 'BRANCH_SWITCH_FAILED' })
    expect(await git('branch', '--show-current')).toBe('feature')
  })

  it('opens a branch checked out elsewhere in its worktree, and refuses missing refs, revision expressions, and untracked subfolders', async () => {
    await git('worktree', 'add', join(root, 'other'), 'feature')
    expect(await realpath(await prepare('branch'))).toBe(await realpath(join(root, 'other')))
    expect(await realpath(await prepare('branch', 'refs/heads/feature', join(repo, 'src')))).toBe(await realpath(join(root, 'other', 'src')))
    expect(await git('branch', '--show-current')).toBe('main')
    for (const ref of ['refs/heads/missing', 'refs/heads/main~0', 'refs/heads/main^{commit}']) {
      await expect(prepare('worktree', ref)).rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
    }
    await mkdir(join(repo, 'untracked'))
    await expect(prepare('worktree', 'refs/heads/main', join(repo, 'untracked'))).rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
    expect(() => parseProjectFolder({ projectSource: 'branch', gitSource: repo, branchRef: 'refs/remotes/origin/feature' })).toThrow()
  })

  it('detects an empty repository but refuses a worktree until its first commit', async () => {
    const empty = join(root, 'empty')
    await mkdir(empty)
    await exec('git', ['-C', empty, 'init', '-b', 'main'])
    expect(await read(empty)).toMatchObject({ isGit: true, branch: 'main', branches: [] })
    await expect(prepareProjectFolder({ source: 'worktree', gitSource: empty }, options()))
      .rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
  })

  it('validates source paths and requires an exact local branch when isolation is disabled', async () => {
    for (const path of [null, 7, '', 'relative', '/bad\npath', '/bad\0path', `/${'x'.repeat(4096)}`]) {
      expect(validGitPath(path)).toBe(false)
      expect(() => parseProjectFolder({ projectSource: 'worktree', gitSource: path })).toThrow()
    }
    await expect(prepareGitProject('relative', { ...options(), worktree: true }))
      .rejects.toMatchObject({ code: 'INVALID_PROJECT_SOURCE' })
    await expect(prepareGitProject(repo, { ...options(), worktree: true, ref: '--help' }))
      .rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
    for (const ref of [undefined, 'refs/remotes/origin/feature']) {
      await expect(prepareGitProject(repo, { ...options(), worktree: false, ref }))
        .rejects.toMatchObject({ code: 'INVALID_BRANCH' })
    }
    for (const payload of [
      { branchRef: 7 }, { branchRef: 'refs/heads/bad name' },
      { branchRef: `refs/heads/${'x'.repeat(1024)}` }, { repositoryUrl: 'https://github.com/a/b' },
    ]) {
      expect(() => parseProjectFolder({ projectSource: 'worktree', gitSource: repo, ...payload })).toThrow()
    }
  })

  it('supports detached HEAD, default worktree names, and switching back to a local branch', async () => {
    await git('checkout', '--detach', 'HEAD')
    expect(await read(repo)).toMatchObject({ isGit: true, branch: null })
    const path = await prepareGitProject(repo, { root, worktree: true })
    expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
    expect(path).toMatch(/\/worktrees\/project with spaces\/[a-z]+-[a-z]+(-\d+)?$/)
    expect(await prepare('branch')).toBe(repo)
    expect(await git('branch', '--show-current')).toBe('feature')
  })

  it('distinguishes an unavailable Git executable from a non-Git folder', async () => {
    vi.stubEnv('PATH', join(root, 'missing-binaries'))
    expect(await read(repo)).toEqual({ error: 'GIT_UNAVAILABLE' })
  })

  // A fresh Mac's /usr/bin/git is Apple's Command Line Tools installer stub, which exits 1. A folder
  // that is not a checkout must still read as one without git, or no harness can start in it.
  it('reads a non-Git folder without running git, so the macOS installer stub cannot fail it', async () => {
    const stubs = join(root, 'stub-bin')
    await mkdir(stubs)
    await writeFile(join(stubs, 'git'), '#!/bin/sh\necho "xcode-select: note: No developer tools were found, requesting install." >&2\nexit 1\n', { mode: 0o755 })
    vi.stubEnv('PATH', stubs)
    const plain = join(root, 'plain project')
    await mkdir(plain)
    expect(await read(plain)).toEqual({ isGit: false, branches: [] })
    expect(await read(repo)).toEqual({ error: 'GIT_UNAVAILABLE' })
  })

  it('reports unreadable refs instead of silently treating the repository as non-Git', async () => {
    await writeFile(join(repo, '.git', 'packed-refs'), 'invalid packed refs\n')
    expect(await read(repo)).toEqual({ error: 'GIT_UNAVAILABLE' })
  })

  it('rejects a subfolder that became a file on the selected branch', async () => {
    await git('switch', 'feature')
    await git('rm', '-r', 'src')
    await writeFile(join(repo, 'src'), 'a file now')
    await git('add', 'src')
    await git('commit', '-m', 'replace folder with file')
    await git('switch', 'main')
    await expect(prepare('worktree', 'refs/heads/feature', join(repo, 'src')))
      .rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
  })

  it('removes a worktree whose checkout hook fails, so a retry starts clean, and logs what the hook said', async () => {
    const said = vi.spyOn(console, 'error').mockImplementation(() => {})
    const hooks = join(root, 'hooks')
    await mkdir(hooks)
    await writeFile(join(hooks, 'post-checkout'), '#!/bin/sh\necho "hook refused" >&2\nexit 1\n', { mode: 0o755 })
    await git('config', 'core.hooksPath', hooks)
    const before = await git('for-each-ref', '--format=%(refname)', 'refs/heads')
    await expect(prepare('worktree')).rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
    expect(await git('worktree', 'list', '--porcelain')).not.toContain('/worktrees/')
    expect(await git('for-each-ref', '--format=%(refname)', 'refs/heads')).toBe(before)
    expect(said.mock.calls.map(call => call.join(' ')).join('\n')).toMatch(/\[worktree\] git worktree add failed \(exit 1\).*hook refused/)
    expect(await git('branch', '--show-current')).toBe('main')
    said.mockRestore()
  })

  it.each(['No space left on device', 'Disk quota exceeded'])('explains worktree disk exhaustion: %s', async (message) => {
    const said = vi.spyOn(console, 'error').mockImplementation(() => {})
    const hooks = join(root, 'hooks')
    await mkdir(hooks)
    await writeFile(join(hooks, 'post-checkout'), `#!/bin/sh\necho 'private-file: ${message}' >&2\nexit 1\n`, { mode: 0o755 })
    await git('config', 'core.hooksPath', hooks)
    await expect(prepare('worktree')).rejects.toMatchObject({
      code: 'WORKTREE_FAILED',
      message: 'Not enough disk space to create the worktree. Free space on this machine, then retry.',
    })
    said.mockRestore()
  })
})