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.

37.1 KB
Raw Blame
import 'runtime_platform.dart';
import 'folder_commands.dart';

import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'dart:math';

import 'package:path/path.dart' as p;

import 'repository_clone.dart';

class GitBranch {
  const GitBranch(
    this.ref,
    this.name, {
    this.remote = false,
    this.worktree,
    this.harness = false,
  });
  final String ref, name;
  final bool remote;

  /// Harness made this branch for a worktree.
  final bool harness;

  /// Where this local branch is checked out, when it is.
  final String? worktree;
}

class GitProjectInfo {
  const GitProjectInfo({
    this.isGit = false,
    this.branch,
    this.branches = const [],
    this.error,
    this.mainFolder,
    this.mainBranch,
    this.defaultRef,
    this.root,
  });
  factory GitProjectInfo.fromJson(Map<String, dynamic> data) => GitProjectInfo(
    isGit: data['isGit'] == true,
    branch: data['branch'] as String?,
    error: data['error'] as String?,
    mainFolder: data['mainFolder'] is String && validGitPath(data['mainFolder'])
        ? data['mainFolder'] as String
        : null,
    mainBranch: data['mainBranch'] as String?,
    defaultRef: data['defaultRef'] is String && validGitRef(data['defaultRef'])
        ? data['defaultRef'] as String
        : null,
    root: data['root'] is String && validGitPath(data['root'])
        ? data['root'] as String
        : null,
    branches: [
      for (final row in (data['branches'] as List? ?? const []))
        if (row is Map && row['ref'] is String && row['name'] is String)
          GitBranch(
            row['ref'] as String,
            row['name'] as String,
            remote: row['remote'] == true,
            worktree: row['worktree'] is String
                ? row['worktree'] as String
                : null,
            harness: row['harness'] == true,
          ),
    ],
  );
  final bool isGit;
  final String? branch, error;
  final List<GitBranch> branches;

  /// Set only for a folder inside a linked worktree: the same folder in the
  /// repository's main checkout, and the branch that checkout is on.
  final String? mainFolder, mainBranch;

  /// The remote branch new work starts from by default (`origin/HEAD`), and
  /// the checkout the folder belongs to.
  final String? defaultRef, root;

  GitProjectInfo copyWith({String? branch, String? root}) => GitProjectInfo(
    isGit: isGit,
    branch: branch ?? this.branch,
    branches: branches,
    error: error,
    defaultRef: defaultRef,
    root: root ?? this.root,
  );
}

/// One entry of `git worktree list --porcelain`. The main checkout is first.
typedef _Worktree = ({String path, String? ref, bool usable});

List<_Worktree> _parseWorktrees(String output) => [
  for (final block in output.split(RegExp(r'\n\s*\n')))
    if (block
            .split('\n')
            .where((line) => line.startsWith('worktree '))
            .firstOrNull
        case final line?)
      (
        path: line.substring('worktree '.length),
        ref: block
            .split('\n')
            .where((line) => line.startsWith('branch '))
            .firstOrNull
            ?.substring('branch '.length),
        // A bare repository has no files, and a prunable entry lost its folder.
        usable: !block
            .split('\n')
            .any((line) => line == 'bare' || line.startsWith('prunable')),
      ),
];

Future<String> _realPath(String path) async {
  try {
    return await Directory(path).resolveSymbolicLinks();
  } on FileSystemException {
    return p.normalize(path);
  }
}

/// The main checkout, when [root] is one of its linked worktrees.
Future<String?> _mainCheckout(String root, List<_Worktree> trees) async {
  if (trees.length < 2 || !trees.first.usable) return null;
  final here = await _realPath(root);
  if (await _realPath(trees.first.path) == here) return null;
  for (final tree in trees.skip(1)) {
    if (await _realPath(tree.path) == here) return trees.first.path;
  }
  return null;
}

/// Two plain words for a branch nothing has named yet — plumbing, like the
/// worktree's folder: the agent or the person names the real branch when there
/// is something to push. Mirrors cli/src/lib/agentNames.ts.
const kPlaceholderAdjectives = [
  'amber', 'bold', 'brave', 'brisk', 'calm', 'clever', 'cosmic', 'crisp', //
  'dapper', 'eager', 'fancy', 'gentle', 'glad', 'golden', 'happy', 'hidden',
  'jolly', 'keen', 'kind', 'lively', 'lucky', 'merry', 'misty', 'noble', //
  'polite', 'proud', 'quick', 'quiet', 'rapid', 'rosy', 'royal', 'rustic',
  'shiny', 'silent', 'silver', 'sleek', 'smart', 'snowy', 'solar', 'spry',
  'steady', 'sunny', 'swift', 'tidy', 'vivid', 'warm', 'witty', 'zesty',
];
const kPlaceholderNouns = [
  'badger', 'beacon', 'birch', 'bison', 'canyon', 'cedar', 'comet', 'coral',
  'crane', 'delta', 'falcon', 'fern', 'finch', 'fjord', 'fox', 'gecko', //
  'glacier', 'harbor', 'hawk', 'heron', 'ibis', 'island', 'koala', 'lagoon',
  'lark', 'lynx', 'maple', 'meadow', 'meteor', 'moose', 'nebula', 'otter', //
  'owl', 'panda', 'pebble', 'pine', 'puffin', 'quartz', 'raven', 'reef', //
  'river', 'robin', 'sparrow', 'spruce', 'tiger', 'walrus', 'willow', 'zebra',
];

/// `brave-otter`: the branch a new worktree starts on until its session has a
/// name, one none of [taken] (branch names, with or without `refs/heads/`)
/// already uses.
String placeholderBranch(Iterable<String> taken, {Random? random}) {
  final names = {
    for (final name in taken) name.replaceFirst('refs/heads/', ''),
  };
  final pick = random ?? Random();
  String draw() =>
      '${kPlaceholderAdjectives[pick.nextInt(kPlaceholderAdjectives.length)]}'
      '-${kPlaceholderNouns[pick.nextInt(kPlaceholderNouns.length)]}';
  var name = draw();
  for (var tries = 0; tries < 16 && names.contains(name); tries++) {
    name = draw();
  }
  final base = name;
  for (var suffix = 2; names.contains(name); suffix++) {
    name = '$base-$suffix';
  }
  return name;
}

/// The folder a worktree on [branch] is checked out in, under its repository:
/// the branch's last part. Nobody needs to see it, and it keeps its name when
/// the branch is renamed.
String worktreeFolderName(String branch) {
  final name = branch
      .split('/')
      .last
      .replaceAll(RegExp(r'[^A-Za-z0-9._-]+'), '')
      .replaceAll(RegExp(r'^[.-]+'), '');
  return name.isEmpty
      ? 'worktree'
      : name.length > 64
      ? name.substring(0, 64)
      : name;
}

/// What a typed name becomes as a branch, as editors do it: words joined by
/// `-`, and nothing `git check-ref-format` refuses. Empty when nothing is left.
String branchNameFrom(String typed) {
  var name = typed
      .trim()
      .replaceAll(RegExp(r'\s+'), '-')
      .replaceAll(RegExp(r'[\x00-\x1f\x7f~^:?*\[\\]+'), '')
      .replaceAll(RegExp(r'\.{2,}'), '.')
      .replaceAll('@{', '@')
      .replaceAll(RegExp(r'/{2,}'), '/')
      .replaceAll(RegExp(r'/[.]+'), '/')
      .replaceAll(RegExp(r'-{2,}'), '-')
      .replaceAll(RegExp(r'^[-./]+'), '');
  for (var trimmed = ''; trimmed != name;) {
    trimmed = name;
    name = name.replaceAll(RegExp(r'(\.lock|[./])$'), '');
  }
  return name == '@' ? '' : name;
}

/// A name Git accepts for a new branch, checked before Git is asked.
bool plausibleBranchName(String name) =>
    name.isNotEmpty &&
    name.length <= 255 &&
    !name.startsWith('-') &&
    !RegExp(r'[\x00-\x20\x7f~^:?*\[\\]').hasMatch(name);

/// `branch.<name>.harness` marks a branch Harness made: `placeholder` while its
/// name waits for the session's, `created` once it has one or was named at
/// Start. Mirrors cli/src/lib/gitProject.ts.
const kHarnessBranchKey = 'harness';

bool validGitPath(String path) =>
    p.isAbsolute(path) &&
    path.length <= 4096 &&
    !RegExp(r'[\x00-\x1f\x7f]').hasMatch(path);
bool validGitRef(String ref) =>
    ref.length <= 1024 &&
    RegExp(r'^refs/(heads|remotes)/[^\s\x00-\x1f\x7f]+$').hasMatch(ref);

typedef GitProcessStarter = Future<Process> Function(
  List<String> arguments,
  Map<String, String> environment,
);

final _branchRefreshes = <String, Future<Map<String, List<String>?>>>{};

/// Coalesce concurrent pickers, including linked worktrees of the same repo.
/// Ask for names only; downloading objects is deferred until Start.
Future<Map<String, List<String>?>> _refreshRemoteBranches(
  String source, {
  GitProcessStarter? startProcess,
}) async {
  final common = await _git(source, [
    'rev-parse',
    '--git-common-dir',
  ], startProcess: startProcess);
  if (common.code != 0) {
    throw const RepositoryCloneException('Git is unavailable.');
  }
  final key = await _realPath(
    p.isAbsolute(common.output) ? common.output : p.join(source, common.output),
  );
  if (_branchRefreshes[key] case final pending?) return pending;
  final refresh = () async {
    final remotes = await _git(source, ['remote'], startProcess: startProcess);
    if (remotes.code != 0) {
      throw const RepositoryCloneException('Git is unavailable.');
    }
    final results = await Future.wait([
      for (final remote
          in remotes.output.split('\n').where((s) => s.isNotEmpty))
        () async {
          try {
            final result = await _git(
              source,
              ['ls-remote', '--heads', '--', remote],
              timeout: const Duration(seconds: 8),
              startProcess: startProcess,
            );
            return MapEntry(
              remote,
              result.code == 0
                  ? [
                      for (final line in result.output.split('\n'))
                        if (line.split('\t') case [_, final ref]
                            when ref.startsWith('refs/heads/'))
                          ref.substring('refs/heads/'.length),
                    ]
                  : null,
            );
          } on RepositoryCloneException {
            return MapEntry<String, List<String>?>(remote, null);
          }
        }(),
    ]);
    return Map<String, List<String>?>.fromEntries(results);
  }();
  _branchRefreshes[key] = refresh;
  try {
    return await refresh;
  } finally {
    _branchRefreshes.remove(key);
  }
}

/// Whether [path] or a folder above it holds `.git`: a directory, or the file
/// a linked worktree has.
Future<bool> insideGitCheckout(String path) async {
  // git resolves the folder physically: ~/proj linked into a repository's
  // packages/app is in that repository though nothing above ~/proj says so.
  final String real;
  try {
    real = await Directory(path).resolveSymbolicLinks();
  } on FileSystemException {
    // Gone or unreadable: let git give its own answer.
    return true;
  }
  var dir = p.normalize(p.absolute(real));
  while (true) {
    final type = await FileSystemEntity.type(p.join(dir, '.git'));
    if (type != FileSystemEntityType.notFound) return true;
    final parent = p.dirname(dir);
    if (parent == dir) return false;
    dir = parent;
  }
}

/// Read cached choices, or explicitly refresh remote branches first. Refresh
/// failures retain usable local results and are reported separately.
Future<Map<String, dynamic>> readLocalGitProject(
  String source, {
  bool refresh = false,
  GitProcessStarter? startProcess,
  Future<bool> Function(String path) insideCheckout = insideGitCheckout,
}) async {
  Future<({int code, String output, String errorOutput})> git(
    List<String> arguments,
  ) => _git(source, arguments, startProcess: startProcess);
  if (!validGitPath(source)) return {'error': 'INVALID_PATH'};
  // A folder with no `.git` in it or above it is not a Git project, and saying so needs no git. On a
  // Mac without the Command Line Tools, /usr/bin/git is Apple's installer stub: it exits 1 (not git's
  // 128), so a returning user's second harness in their first project failed with "Could not check
  // Git" (fresh macOS VM, 2026-10-08), and the stub may also offer to install the tools.
  if (!await insideCheckout(source)) return {'isGit': false};
  try {
    final root = await git(['rev-parse', '--show-toplevel']);
    if (root.code != 0) {
      return root.code == 128 ? {'isGit': false} : {'error': 'GIT_UNAVAILABLE'};
    }
    Map<String, List<String>?>? discovered;
    if (refresh) {
      try {
        discovered = await _refreshRemoteBranches(
          source,
          startProcess: startProcess,
        );
      } on RepositoryCloneException {
        /* Keep saved choices available offline. */
      }
    }
    final results = await Future.wait([
      git(['symbolic-ref', '--quiet', 'HEAD']),
      git([
        'for-each-ref',
        '--format=%(refname)%09%(refname:short)%09%(symref)',
        'refs/heads',
        'refs/remotes',
      ]),
      git(['worktree', 'list', '--porcelain']),
      git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']),
      git(['config', '--get-regexp', '^branch\\..*\\.$kHarnessBranchKey\$']),
    ]);
    final marked = {
      for (final line in results[4].output.split('\n'))
        if (line.split(' ').first case final key
            when key.startsWith('branch.') &&
                key.endsWith('.$kHarnessBranchKey'))
          key.substring(7, key.length - kHarnessBranchKey.length - 1),
    };
    if (results[1].code != 0) return {'error': 'GIT_UNAVAILABLE'};
    final branches = <Map<String, dynamic>>[
      for (final line in results[1].output.split('\n'))
        if (line.split('\t') case [final ref, final name, ''])
          {'ref': ref, 'name': name, 'remote': ref.startsWith('refs/remotes/')},
    ];
    for (final entry
        in discovered?.entries ?? const <MapEntry<String, List<String>?>>[]) {
      final names = entry.value;
      if (names == null) continue;
      final prefix = 'refs/remotes/${entry.key}/';
      branches.removeWhere(
        (branch) => (branch['ref'] as String).startsWith(prefix),
      );
      branches.addAll([
        for (final name in names)
          {'ref': '$prefix$name', 'name': '${entry.key}/$name', 'remote': true},
      ]);
    }
    final refs = {for (final branch in branches) branch['ref']};
    // Where new work starts by default: the remote's default branch, as a
    // clone names it, else its main or master.
    final defaultRef = [
      if (results[3].code == 0) results[3].output,
      'refs/remotes/origin/main',
      'refs/remotes/origin/master',
    ].where(refs.contains).firstOrNull;
    final trees = results[2].code == 0
        ? _parseWorktrees(results[2].output)
        : const <_Worktree>[];
    final checkedOut = {
      for (final tree in trees)
        if (tree.usable && tree.ref != null) tree.ref!: tree.path,
    };
    // A worktree is a temporary folder. The launcher shows its repository.
    String? mainFolder, mainBranch;
    if (await _mainCheckout(root.output, trees) case final main?) {
      final prefix = await git(['rev-parse', '--show-prefix']);
      final relative = prefix.code == 0
          ? prefix.output.replaceFirst(RegExp(r'/$'), '')
          : '';
      mainFolder =
          relative.isNotEmpty &&
              await Directory(p.join(main, relative)).exists()
          ? p.join(main, relative)
          : main;
      mainBranch = trees.first.ref?.replaceFirst('refs/heads/', '');
    }
    return {
      'isGit': true,
      if (refresh)
        'refreshed':
            discovered != null &&
            discovered.values.every((names) => names != null),
      'root': root.output,
      'branch': results[0].code == 0
          ? results[0].output.replaceFirst('refs/heads/', '')
          : null,
      'mainFolder': ?mainFolder,
      'mainBranch': ?mainBranch,
      'defaultRef': ?defaultRef,
      'branches': [
        for (final branch in branches)
          {
            ...branch,
            'worktree': ?checkedOut[branch['ref']],
            if (branch['remote'] == false &&
                (marked.contains(branch['name']) ||
                    (branch['name'] as String).startsWith('harness/')))
              'harness': true,
          },
      ],
    };
  } on RepositoryCloneException {
    return {'error': 'GIT_UNAVAILABLE'};
  }
}

/// Worktree on: a new worktree under `<projectHome>/worktrees/<repository>`,
/// on [branchName] — created from [branchRef], or with [existingBranch] an
/// existing local branch checked out as it is. Without a name one is made up
/// (`harness/brave-otter`). A remote base is fetched first, briefly.
///
/// Worktree off: the folder on the local [branchRef]. A branch that already
/// has a worktree opens there; any other is switched to, only in a folder with
/// nothing uncommitted. With [branchName] the folder moves to that new branch,
/// made where it is now, uncommitted changes and all.
Future<String> prepareGitProject(
  String source,
  String projectHome, {
  required bool worktree,
  String? branchRef,
  String? branchName,
  bool existingBranch = false,
  bool placeholder = false,
  Random? random,
  GitProcessStarter? startProcess,
}) async {
  Future<({int code, String output, String errorOutput})> git(
    List<String> arguments, {
    Duration timeout = const Duration(seconds: 4),
    String? at,
  }) => _git(
    at ?? source,
    arguments,
    timeout: timeout,
    startProcess: startProcess,
  );
  if (!validGitPath(source) ||
      branchRef != null && !validGitRef(branchRef) ||
      branchName != null && !plausibleBranchName(branchName) ||
      existingBranch && branchName == null) {
    throw const RepositoryCloneException('Choose a Git project and branch.');
  }
  final root = await git(['rev-parse', '--show-toplevel']);
  if (root.code != 0) {
    throw const RepositoryCloneException('Choose a Git working folder.');
  }
  // A new branch for the folder itself: [branchRef] names it and does not exist.
  final creating = !worktree && branchName != null && !existingBranch;
  final remote = worktree && !existingBranch ? _remoteBranch(branchRef) : null;
  if (branchRef != null && !creating && remote == null) {
    final ref = await git(['show-ref', '--verify', '--hash', '--', branchRef]);
    if (ref.code != 0) {
      throw const RepositoryCloneException(
        'That branch is no longer available. Choose another branch.',
      );
    }
  }
  // New work starts from where its branch is now, not from the last fetch: a
  // remote branch is fetched; a local one is fetched against its upstream and
  // the newer of the two taken, so nothing only the local one has is lost.
  // Offline, slow or refused, it starts from what is here.
  var start = existingBranch
      ? 'refs/heads/$branchName'
      : creating
      ? 'HEAD'
      : branchRef ?? 'HEAD';
  String? upstream;
  if (worktree && !existingBranch && branchRef != null && remote == null) {
    final tracked = await git([
      'for-each-ref',
      '--format=%(upstream)',
      branchRef,
    ]);
    if (tracked.code == 0 && _remoteBranch(tracked.output) != null) {
      upstream = tracked.output;
    }
  }
  final fetch = remote ?? _remoteBranch(upstream);
  if (fetch != null) {
    try {
      await git([
        'fetch',
        '--quiet',
        '--no-tags',
        fetch.remote,
        fetch.refspec,
      ], timeout: const Duration(seconds: 10));
    } on RepositoryCloneException {
      // Too slow: start from the last fetch.
    }
  }
  if (upstream != null && branchRef != null) {
    // Behind or level with its upstream: the upstream is the newer.
    final behind = await git([
      'merge-base',
      '--is-ancestor',
      branchRef,
      upstream,
    ]);
    if (behind.code == 0) start = upstream;
  }
  final head = await git([
    'rev-parse',
    '--verify',
    '--end-of-options',
    '$start^{commit}',
  ]);
  if (head.code != 0) {
    throw const RepositoryCloneException(
      'Worktree needs a branch with at least one commit. Turn Worktree off for an empty repository.',
    );
  }
  final prefix = await git(['rev-parse', '--show-prefix']);
  if (prefix.code != 0) {
    throw const RepositoryCloneException('Could not read the project folder.');
  }
  final relative = prefix.output;
  if (relative.isNotEmpty) {
    final tree = await git([
      'cat-file',
      '-t',
      '${head.output}:${relative.replaceFirst(RegExp(r'/$'), '')}',
    ]);
    if (tree.code != 0 || tree.output != 'tree') {
      throw const RepositoryCloneException(
        'This folder is not in the selected branch. Choose the repository root.',
      );
    }
  }
  String inside(String folder) => relative.isEmpty
      ? folder
      : p.join(folder, relative.replaceFirst(RegExp(r'/$'), ''));
  final listed = await git(['worktree', 'list', '--porcelain']);
  final trees = listed.code == 0
      ? _parseWorktrees(listed.output)
      : const <_Worktree>[];
  if (creating) {
    final exists = await git([
      'show-ref',
      '--verify',
      '--quiet',
      '--',
      'refs/heads/$branchName',
    ]);
    if (exists.code == 0) {
      throw RepositoryCloneException(
        'A branch named $branchName already exists. Choose it instead.',
      );
    }
    final format = await git(['check-ref-format', '--branch', branchName]);
    if (format.code != 0) {
      throw RepositoryCloneException('$branchName is not a valid branch name.');
    }
    final made = await git(['switch', '-c', branchName]);
    if (made.code != 0) {
      throw RepositoryCloneException('Could not create $branchName here.');
    }
    return source;
  }
  if (!worktree) {
    if (branchRef == null || !branchRef.startsWith('refs/heads/')) {
      throw const RepositoryCloneException(
        'Choose a local branch, or turn Worktree on.',
      );
    }
    final current = await git(['symbolic-ref', '--quiet', 'HEAD']);
    if (current.code == 0 && current.output == branchRef) return source;
    // A branch that already has a worktree is worked on there: Git would
    // refuse to check it out twice, and the folder is not the person's concern.
    for (final tree in trees) {
      if (tree.usable &&
          tree.ref == branchRef &&
          await Directory(tree.path).exists()) {
        return inside(tree.path);
      }
    }
    final status = await git(['status', '--porcelain']);
    if (status.code != 0 || status.output.isNotEmpty) {
      throw const RepositoryCloneException(
        'This folder has uncommitted changes. Commit or stash them before switching branches, or turn Worktree on.',
      );
    }
    final result = await git([
      'switch',
      '--',
      branchRef.substring('refs/heads/'.length),
    ], timeout: const Duration(minutes: 2));
    if (result.code != 0) {
      throw const RepositoryCloneException(
        'Could not switch branches. Commit or stash conflicting changes, or turn Worktree on.',
      );
    }
    return source;
  }
  // Grouped by repository, so the leaf only needs the branch.
  final repository = trees.firstOrNull?.usable == true
      ? p.basename(trees.first.path)
      : p.basename(root.output);
  final locals = await git([
    'for-each-ref',
    '--format=%(refname)',
    'refs/heads',
  ]);
  final taken = locals.output.split('\n').toSet();
  var branch = branchName ?? placeholderBranch(taken, random: random);
  final madeUp = branchName == null || placeholder;
  // The composer keeps the placeholder it drew, so a start that made it and
  // was then cancelled leaves it taken for the next press. Nobody chose that
  // name: take the next free number, as the CLI does (gitProject.ts).
  if (madeUp && !existingBranch) {
    final base = branch;
    for (var suffix = 2; taken.contains('refs/heads/$branch'); suffix++) {
      branch = '$base-$suffix';
    }
  }
  if (existingBranch) {
    if (!taken.contains('refs/heads/$branch')) {
      throw const RepositoryCloneException(
        'That branch is no longer available. Choose another branch.',
      );
    }
    if (trees.any((tree) => tree.ref == 'refs/heads/$branch')) {
      throw RepositoryCloneException(
        '$branch is checked out in another worktree. Turn Worktree off to open it there.',
      );
    }
  } else {
    if (taken.contains('refs/heads/$branch')) {
      throw RepositoryCloneException(
        'A branch named $branch already exists. Choose another name.',
      );
    }
    final format = await git(['check-ref-format', '--branch', branch]);
    if (format.code != 0) {
      throw RepositoryCloneException('$branch is not a valid branch name.');
    }
  }
  late final String destination;
  try {
    final home = Directory(p.join(projectHome, 'worktrees'));
    final parent = Directory(p.join(home.path, repository));
    await parent.create(recursive: true);
    // Spotlight would index every checkout again.
    if (Platform.isMacOS) {
      await File(p.join(home.path, '.metadata_never_index'))
          .writeAsString('', flush: true)
          .catchError((_) => File(''));
    }
    final leaf = worktreeFolderName(branch);
    for (var attempt = 1; ; attempt++) {
      if (attempt > 100) {
        throw FileSystemException('No free worktree name', parent.path);
      }
      final folder = p.join(
        parent.path,
        attempt == 1 ? leaf : '$leaf-$attempt',
      );
      // Directory.create accepts an existing directory; mkdir reserves the
      // name exclusively, so concurrent starts never share a worktree.
      final reservation = await reserveDirectory(folder);
      if (reservation.exitCode == 0) {
        destination = folder;
        break;
      }
      if (_diskFullMessage(reservation.stderr.toString())) {
        throw const RepositoryCloneException(_worktreeDiskFull);
      }
      if (await FileSystemEntity.type(folder, followLinks: false) ==
          FileSystemEntityType.notFound) {
        throw FileSystemException('Could not create folder', folder);
      }
    }
  } on FileSystemException catch (error) {
    if ([28, 69, 122].contains(error.osError?.errorCode)) {
      throw const RepositoryCloneException(_worktreeDiskFull);
    }
    throw const RepositoryCloneException(
      'Could not create a worktree folder. Check folder permissions, then retry.',
    );
  } on ProcessException {
    throw const RepositoryCloneException(
      'Could not create a worktree folder. Check folder permissions, then retry.',
    );
  }
  if (!existingBranch && remote != null && remote.branch == branch) {
    // Single-branch clones need a tracking rule for this branch. Add only
    // the selected branch, at Start, never while reading search results.
    final key = 'remote.${remote.remote}.fetch';
    final configured = await git(['config', '--get-all', key]);
    final mappings = configured.output
        .split('\n')
        .map((ref) => ref.replaceFirst(RegExp(r'^\+'), ''));
    if (!mappings.contains(remote.refspec.substring(1)) &&
        !mappings.contains('refs/heads/*:refs/remotes/${remote.remote}/*')) {
      final configured = await git(['config', '--add', key, remote.refspec]);
      if (configured.code != 0) {
        throw const RepositoryCloneException(
          'Could not set up branch tracking. Check Git permissions, then retry.',
        );
      }
    }
  }
  final result = await git(
    existingBranch
        ? ['worktree', 'add', '--', destination, branch]
        // A remote branch checked out under its own name tracks it; a new
        // branch from one must not, or it would push onto the base.
        : remote != null && remote.branch == branch
        ? [
            'worktree',
            'add',
            '--track',
            '-b',
            branch,
            '--',
            destination,
            branchRef!,
          ]
        : [
            'worktree',
            'add',
            '--no-track',
            '-b',
            branch,
            '--',
            destination,
            head.output,
          ],
    timeout: const Duration(minutes: 2),
  );
  if (result.code != 0) {
    // A partial checkout or branch stays available for recovery.
    throw RepositoryCloneException(
      _diskFullMessage(result.errorOutput)
          ? _worktreeDiskFull
          : 'Could not create the worktree at $destination. Check Git and folder permissions, then retry.',
    );
  }
  // Harness made this branch: its cleanup may remove it, and a made-up name
  // gives way to the session's.
  if (!existingBranch) {
    await git([
      'config',
      'branch.$branch.$kHarnessBranchKey',
      madeUp ? 'placeholder' : 'created',
    ]);
  }
  await _copyIncluded(root.output, destination, startProcess);
  return inside(destination);
}

/// Takes back a worktree [prepareGitProject] made for a start that was then
/// cancelled: its folder, and the branch Harness made for it. A cancelled
/// start left both behind, and the next press was refused for the branch
/// (desktop 1.3.41, 2026-10-30). [folder] is what [prepareGitProject]
/// returned, a subfolder of the worktree for a subfolder project.
///
/// True once the worktree is gone. Anything that may be somebody's work stays:
/// a repository's own checkout, a worktree with changes in it, a branch that
/// cannot be shown to have no commits of its own. With [keepBranch] (a branch
/// that was there before the start) only the folder goes; a branch without
/// Harness's mark keeps its branch too.
Future<bool> discardPreparedWorktree(
  String folder, {
  bool keepBranch = false,
  GitProcessStarter? startProcess,
}) async {
  Future<({int code, String output, String errorOutput})> git(
    String at,
    List<String> arguments, {
    Duration timeout = const Duration(seconds: 4),
  }) => _git(at, arguments, timeout: timeout, startProcess: startProcess);
  final dirs = await git(folder, [
    'rev-parse',
    '--path-format=absolute',
    '--show-toplevel',
    '--git-dir',
    '--git-common-dir',
  ]);
  final lines = dirs.code == 0 ? dirs.output.split('\n') : const <String>[];
  if (lines.length != 3 || lines.any((line) => line.isEmpty)) return false;
  final [top, gitDir, common] = lines;
  // The repository's own checkout has its git directory as the common one.
  if (gitDir == common) return false;
  final current = await git(folder, ['symbolic-ref', '--quiet', 'HEAD']);
  final head = await git(folder, ['rev-parse', '--verify', 'HEAD']);
  if (head.code != 0) return false;
  final ref = current.code == 0 ? current.output : null;
  final branch = ref?.replaceFirst('refs/heads/', '');
  final mark = branch == null
      ? null
      : await git(folder, [
          'config',
          '--get',
          'branch.$branch.$kHarnessBranchKey',
        ]);
  final made =
      !keepBranch && mark != null && mark.code == 0 && mark.output.isNotEmpty;
  if (made) {
    // Proof, not absence of evidence: one entry ("branch: Created from …")
    // that is still the tip. No reflog at all (core.logAllRefUpdates=false)
    // proves nothing, and a branch with a commit there was lost in review.
    final log = await git(folder, ['reflog', 'show', '--format=%H', ref!]);
    if (log.code != 0 || log.output != head.output) return false;
  }
  // Without --force: a worktree with changes in it refuses. Ignored files
  // (what `.worktreeinclude` copied in) do not count as changes. As long as
  // `worktree add` may take: a deadline mid-delete leaves half a folder.
  // From the common directory: `-C folder` would stand git inside the folder
  // it deletes, and Windows refuses to delete a process's current folder.
  final removed = await git(common, [
    'worktree',
    'remove',
    '--',
    top,
  ], timeout: const Duration(minutes: 2));
  if (removed.code != 0) return false;
  if (made) {
    // The tip proven above; one that moved since is kept.
    final deleted = await git(common, ['update-ref', '-d', ref!, head.output]);
    if (deleted.code == 0) {
      await git(common, ['config', '--remove-section', 'branch.$branch']);
    }
  }
  return true;
}

/// `refs/remotes/origin/fix/typo` → origin, fix/typo, and a refspec that
/// updates exactly that remote-tracking branch.
({String remote, String branch, String refspec})? _remoteBranch(String? ref) {
  final match = RegExp(
    r'^refs/remotes/([A-Za-z0-9._][A-Za-z0-9._-]*)/([A-Za-z0-9._][^\s]*)$',
  ).firstMatch(ref ?? '');
  if (match == null || match.group(2) == 'HEAD') return null;
  final remote = match.group(1)!, branch = match.group(2)!;
  return (
    remote: remote,
    branch: branch,
    refspec: '+refs/heads/$branch:refs/remotes/$remote/$branch',
  );
}

/// `.worktreeinclude` (gitignore syntax) in the repository names ignored files
/// a new worktree needs and Git will not bring: `.env`, local config. Only
/// files that are both listed and ignored are copied, never over one the
/// checkout has. A copy that fails leaves the worktree as Git made it.
Future<void> _copyIncluded(
  String from,
  String to,
  GitProcessStarter? startProcess,
) async {
  final include = p.join(from, '.worktreeinclude');
  try {
    if (!await File(include).exists()) return;
    Future<List<String>> list(String exclude) async {
      final out = await _git(from, [
        'ls-files',
        '-z',
        '--others',
        '--ignored',
        '--directory',
        exclude,
      ], startProcess: startProcess);
      return out.code == 0
          ? out.output.split('\u0000').where((e) => e.isNotEmpty).toList()
          : const [];
    }

    final listed = await list('--exclude-from=$include');
    final ignored = await list('--exclude-standard');
    bool isIgnored(String entry) => ignored.any(
      (path) => path == entry || path.endsWith('/') && entry.startsWith(path),
    );
    for (final entry in listed.where(isIgnored).take(200)) {
      final relative = entry.replaceFirst(RegExp(r'/$'), '');
      if (relative.split('/').contains('..')) continue;
      final target = p.join(to, relative);
      if (await FileSystemEntity.type(target, followLinks: false) !=
          FileSystemEntityType.notFound) {
        continue;
      }
      await Directory(p.dirname(target)).create(recursive: true);
      if (RuntimePlatform.isWindows) {
        await copyTree(p.join(from, relative), target);
        continue;
      }
      await Process.run('cp', [
        '-R',
        '-p',
        '--',
        p.join(from, relative),
        target,
      ]);
    }
  } on FileSystemException {
    return;
  } on ProcessException {
    return;
  } on RepositoryCloneException {
    return;
  }
}

const _worktreeDiskFull =
    'Not enough disk space to create the worktree. Free space on this machine, then retry.';

bool _diskFullMessage(String message) => RegExp(
  r'no space left on device|disk quota exceeded',
  caseSensitive: false,
).hasMatch(message);

/// Runs git in [source] the way every reader here does: a scrubbed
/// environment, no prompts, at most 1 MiB of output, and a deadline. Throws
/// [RepositoryCloneException] when git cannot start, overflows or times out.
Future<({int code, String output, String errorOutput})> runLocalGit(
  String source,
  List<String> arguments, {
  Duration timeout = const Duration(seconds: 4),
}) => _git(source, arguments, timeout: timeout);

Future<({int code, String output, String errorOutput})> _git(
  String source,
  List<String> arguments, {
  Duration timeout = const Duration(seconds: 4),
  GitProcessStarter? startProcess,
}) async {
  final environment = Map<String, String>.of(Platform.environment)
    ..removeWhere(
      (key, _) => const [
        'GIT_DIR',
        'GIT_WORK_TREE',
        'GIT_COMMON_DIR',
        'GIT_INDEX_FILE',
        'GIT_NAMESPACE',
        'GIT_PREFIX',
      ].contains(key),
    )
    ..addAll({
      'GIT_TERMINAL_PROMPT': '0',
      'GCM_INTERACTIVE': 'Never',
      'GIT_OPTIONAL_LOCKS': '0',
    });
  Process process;
  final argv = ['--no-optional-locks', '-C', source, ...arguments];
  try {
    process =
        await (startProcess?.call(argv, environment) ??
            Process.start(
              'git',
              argv,
              environment: environment,
              includeParentEnvironment: false,
            ));
  } on ProcessException {
    throw const RepositoryCloneException(
      'Git could not start. Install Git, then retry.',
    );
  }
  unawaited(process.stdin.close());
  final output = StringBuffer();
  var errorOutput = '';
  var overflow = false;
  final outDone = Completer<void>(), errDone = Completer<void>();
  final stdout = process.stdout
      .transform(const Utf8Decoder(allowMalformed: true))
      .listen(
        (chunk) {
          if (output.length + chunk.length <= 1024 * 1024) {
            output.write(chunk);
          } else {
            overflow = true;
            process.kill(ProcessSignal.sigkill);
          }
        },
        onDone: outDone.complete,
        onError: outDone.completeError,
      );
  final stderr = process.stderr
      .transform(const Utf8Decoder(allowMalformed: true))
      .listen(
        (chunk) {
          errorOutput += chunk;
          // Keep a bounded tail for failure classification; never show raw Git
          // output, which can contain credentials or repository contents.
          if (errorOutput.length > 8192) {
            errorOutput = errorOutput.substring(errorOutput.length - 8192);
          }
        },
        onDone: errDone.complete,
        onError: errDone.completeError,
      );
  try {
    final results = await Future.wait<dynamic>([
      process.exitCode,
      outDone.future,
      errDone.future,
    ]).timeout(timeout);
    if (overflow) {
      throw const RepositoryCloneException(
        'This repository has too many branches to read.',
      );
    }
    return (
      code: results.first as int,
      output: output.toString().replaceFirst(RegExp(r'\r?\n$'), ''),
      errorOutput: errorOutput,
    );
  } on TimeoutException {
    process.kill(ProcessSignal.sigkill);
    throw const RepositoryCloneException(
      'Git took too long. Check this machine, then retry.',
    );
  } finally {
    await stdout.cancel();
    await stderr.cancel();
  }
}