@kabmo-labs/kabmo 0.6.1 → 0.8.0

package/src/server/lib/fs/worktree/create.ts

@@ -0,0 +1,263 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Create a worktree, in the order that matters.
+ *
+ * Every refusal git would only raise mid-way is checked FIRST, because git
+ * creates the branch before it discovers the problem. Measured on git 2.56:
+ * `git worktree add` prints `Preparing worktree`, creates the branch, and only
+ * then fails with "already checked out", "already exists", or for an unborn
+ * branch `object not found: HEAD` — each leaving a branch behind for a create
+ * the user was told had failed.
+ *
+ * Two deliberate absences:
+ *
+ *  - **no `--force`**, so git never overwrites a directory or steals a branch
+ *    another worktree holds;
+ *  - **no carry of uncommitted changes.** Their edits are indistinguishable from
+ *    another session's in the same checkout, and a `stash`+`apply` is a
+ *    repository-wide operation that can take them. The dialog says the changes
+ *    stay put, and this is what makes that true.
+ */
+
+import path from 'path';
+import { mkdir } from 'fs/promises';
+import { getDataDir } from '@/server/lib/lifecycle/paths';
+import { runGit } from '@/server/lib/fs/git-run';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
+import { pathExists } from '@/server/lib/omp/core/paths';
+import {
+  folderNameForBranch,
+  isPlausibleBranchName,
+  normalizeBranchName,
+  slugWorktreeName,
+  WORKTREE_BRANCH_PREFIX,
+} from '@/shared/lib/workspace/worktree/branch-name';
+import type { WorktreeInfo } from '@/shared/lib/workspace/worktree/types';
+import { carryIgnoredInto, type CarryResult } from '@/server/lib/fs/worktree/carry';
+import { WorktreeError } from '@/server/lib/fs/worktree/errors';
+import {
+  defaultWorktreeRoot,
+  resolveConfiguredWorktreeRoot,
+  resolveTargetDirectory,
+} from '@/server/lib/fs/worktree/location';
+import { findBranchInUse, refExists } from '@/server/lib/fs/worktree/list';
+import { resolveProjectId } from '@/server/lib/fs/worktree/project-id';
+
+/**
+ * The `-c` flags a create carries.
+ *
+ * `core.longpaths` is not cosmetic: the data-dir prefix plus a nested repository
+ * path exceeds Windows' 260-character MAX_PATH, and git then fails during the
+ * checkout with "Filename too long" and leaves a half-populated worktree.
+ * `core.hooksPath` keeps a repository's hooks out of a checkout Kabmo makes.
+ */
+export const WORKTREE_ADD_CONFIG = [
+  'core.longpaths=true',
+  `core.hooksPath=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`,
+];
+
+export interface CreateWorktreeInput {
+  /** Absolute path of the project (or any directory inside the repository). */
+  projectPath: string;
+  mode: 'new' | 'existing';
+  /** The branch: free text in `new`, a pick in `existing`. Empty generates one. */
+  branch?: string;
+  /** The folder name from the dialog; empty follows the branch. */
+  worktreeName?: string;
+  startRef?: string;
+  /** Overrides the stored setting, which is what the dialog's Quick path does. */
+  carryIgnored?: boolean;
+}
+
+export interface CreatedWorktree extends WorktreeInfo {
+  projectId: string;
+  primaryRoot: string;
+  carried: CarryResult | null;
+  /** False for `existing`, where the branch already belonged to the repository. */
+  createdBranch: boolean;
+}
+
+export interface CreateWorktreeDeps {
+  /** The identity cache, in production `worktreeIdentityFor(getDb(), …)`. */
+  identityFor: (primaryRoot: string) => Promise<string | null>;
+  /** The stored carry default; the request may override it. */
+  carryIgnored: boolean;
+  dataDir?: string;
+  configuredDirectory?: string | null;
+  /** Called with the finished row — the registry write, injected for tests. */
+  record: (row: {
+    path: string;
+    primaryRoot: string;
+    projectId: string;
+    branch: string;
+    startRef: string;
+    createdAt: string;
+  }) => Promise<void>;
+}
+
+async function gitOk(args: string[], cwd: string): Promise<string> {
+  const result = await runGit(args, { cwd, maxBuffer: 4 * 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.exitCode !== 0) throw new Error(result.stderr.trim() || result.stdout.trim() || `git exited ${result.exitCode}`);
+  return result.stdout;
+}
+
+/** Resolve the destination the create would use, without touching disk. */
+export async function planWorktree(
+  input: CreateWorktreeInput,
+  deps: Pick<CreateWorktreeDeps, 'identityFor' | 'dataDir' | 'configuredDirectory'>,
+): Promise<{ primaryRoot: string; projectId: string; root: string; name: string; directory: string; branch: string; startRef: string }> {
+  const projectPath = path.resolve(input.projectPath);
+  const insideWorkTree = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd: projectPath });
+  if (insideWorkTree.exitCode !== 0 || insideWorkTree.stdout.trim() !== 'true') {
+    throw new WorktreeError('not_a_repo', 'This folder is not a Git repository.');
+  }
+
+  const primaryRoot = await resolveProjectRoot(projectPath);
+  const head = await runGit(['rev-parse', '--verify', 'HEAD'], { cwd: primaryRoot });
+  if (head.exitCode !== 0) {
+    throw new WorktreeError('no_commits', 'This repository has no commits yet.');
+  }
+
+  const existing = input.mode === 'existing';
+  // The RAW name is validated, then normalized only by stripping a ref prefix.
+  // Normalizing first was a silent rewrite: `normalizeBranchName` turns spaces
+  // into dashes, so a typed `has space` became the valid `has-space` and the
+  // dialog created a branch the user never asked for.
+  const typed = (input.branch ?? '').trim();
+  const requested = normalizeBranchName(typed);
+  if (existing && !requested) {
+    throw new WorktreeError('invalid_name', 'Pick a branch to check out.', { field: 'branch' });
+  }
+  if (typed && !isPlausibleBranchName(typed)) {
+    throw new WorktreeError('invalid_name', `"${typed}" is not a valid branch name.`, { field: 'branch' });
+  }
+  if (requested) {
+    const exists = await refExists(primaryRoot, `refs/heads/${requested}`);
+    if (existing && !exists) {
+      throw new WorktreeError('branch_exists', `Branch ${requested} does not exist.`, { field: 'branch' });
+    }
+    if (!existing && exists) {
+      throw new WorktreeError('branch_exists', `Branch ${requested} already exists.`, { field: 'branch' });
+    }
+    const inUse = await findBranchInUse(primaryRoot, requested);
+    if (inUse) {
+      throw new WorktreeError('branch_in_use', `${requested} is already checked out in ${inUse.path}.`, {
+        field: 'branch',
+      });
+    }
+  }
+
+  const projectId = await resolveProjectId(primaryRoot, deps.identityFor);
+  const dataDir = deps.dataDir ?? getDataDir();
+  // Canonical from the start: the directory is compared against git's own paths
+  // and stored as a primary key, and two spellings of one folder must be one
+  // row (macOS: `/tmp` typed, `/private/tmp` reported).
+  const root = await canonicalPath(
+    resolveConfiguredWorktreeRoot(deps.configuredDirectory ?? null, primaryRoot)
+      ?? defaultWorktreeRoot(dataDir, projectId),
+  );
+
+  // The folder follows the branch unless the dialog named one; a non-Latin
+  // branch leaves no slug, so a generated name stands in rather than an empty
+  // folder.
+  const candidateName = input.worktreeName?.trim() || folderNameForBranch(requested) || slugWorktreeName(requested);
+  const target = await resolveTargetDirectory({
+    root,
+    preferredName: candidateName,
+    // The branch the user typed is used VERBATIM in both modes; only an empty
+    // one generates. Passing it as generated for `new` renamed a typed
+    // `分支/测试` to `wt/lucid-toucan` — measured, and the caller never sees the
+    // branch it asked for.
+    explicitBranch: requested || null,
+    generatedBranch: (name) => `${WORKTREE_BRANCH_PREFIX}/${name}`,
+    branchExists: async (branch) => Boolean(await findBranchInUse(primaryRoot, branch)) || refExists(primaryRoot, `refs/heads/${branch}`),
+  });
+
+  const startRef = input.startRef?.trim() || 'HEAD';
+  return { primaryRoot, projectId, root, name: target.name, directory: target.directory, branch: target.branch, startRef };
+}
+
+/** Create the worktree, carry the ignored build folders, and record the row. */
+export async function createWorktree(
+  input: CreateWorktreeInput,
+  deps: CreateWorktreeDeps,
+): Promise<CreatedWorktree> {
+  const plan = await planWorktree(input, deps);
+  const existing = input.mode === 'existing';
+  const carry = input.carryIgnored ?? deps.carryIgnored;
+
+  await mkdir(plan.root, { recursive: true });
+
+  // git's grammar is `worktree add [--no-checkout] [-b <new>] <path> [<commit-ish>]`:
+  // an EXISTING branch is the commit-ish and therefore follows the path.
+  // Measured: putting the branch first is read as the path and git answers
+  // `fatal: invalid reference: <the path we meant to use>`.
+  // ONE `-c` per pair: `['-c', a, b, 'worktree']` makes git read `b` as the
+  // SUBCOMMAND, and it answers `git: 'core.hooksPath=/dev/null' is not a git
+  // command` — measured, and every create failed on it.
+  const configArgs = WORKTREE_ADD_CONFIG.flatMap((pair) => ['-c', pair]);
+  const args = [...configArgs, 'worktree', 'add', '--no-checkout'];
+  if (existing) {
+    args.push(plan.directory, plan.branch);
+  } else {
+    args.push('-b', plan.branch, plan.directory);
+    if (plan.startRef !== 'HEAD') args.push(plan.startRef);
+  }
+
+  try {
+    await gitOk(args, plan.primaryRoot);
+    // `--no-checkout` keeps the add cheap; the same flags then populate it, so a
+    // path that cannot be checked out fails HERE and is reported.
+    await gitOk([...configArgs, 'checkout'], plan.directory);
+  } catch (error) {
+    // A failed create leaves nothing behind: the branch was ours, so it goes.
+    if (!existing) {
+      await runGit(['branch', '-D', plan.branch], { cwd: plan.primaryRoot });
+    }
+    throw new WorktreeError('create_failed', error instanceof Error ? error.message : String(error));
+  }
+
+  let carried: CarryResult | null = null;
+  if (carry) {
+    try {
+      carried = await carryIgnoredInto({ primaryRoot: plan.primaryRoot, worktreePath: plan.directory });
+    } catch (error) {
+      // Reported, not fatal: a worktree without node_modules is still a worktree.
+      carried = { copied: [], skipped: [], strategy: 'plain' };
+      void error;
+    }
+  }
+
+  const createdAt = new Date().toISOString();
+  await deps.record({
+    path: plan.directory,
+    primaryRoot: plan.primaryRoot,
+    projectId: plan.projectId,
+    branch: plan.branch,
+    startRef: existing ? '' : plan.startRef,
+    createdAt,
+  });
+
+  return {
+    path: plan.directory,
+    branch: plan.branch,
+    head: (await runGit(['rev-parse', 'HEAD'], { cwd: plan.directory })).stdout.trim(),
+    detached: false,
+    missing: !(await pathExists(plan.directory)),
+    isPrimary: false,
+    dirty: 0,
+    aheadOfStart: 0,
+    startRef: existing ? '' : plan.startRef,
+    sessions: 0,
+    projectId: plan.projectId,
+    primaryRoot: plan.primaryRoot,
+    carried,
+    createdBranch: !existing,
+  };
+}

package/src/server/lib/fs/worktree/errors.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A worktree refusal, carrying the code and the field it belongs to.
+ *
+ * The route answers `{ error, code, field }` from this, so the dialog can mark
+ * the input that caused it instead of printing one sentence under the buttons.
+ * Codes are stable; messages are for people.
+ */
+
+import type { WorktreeErrorCode, WorktreeFailure } from '@/shared/lib/workspace/worktree/types';
+
+export class WorktreeError extends Error {
+  readonly code: WorktreeErrorCode;
+  readonly field?: WorktreeFailure['field'];
+  readonly count?: number;
+
+  constructor(code: WorktreeErrorCode, message: string, options: { field?: WorktreeFailure['field']; count?: number } = {}) {
+    super(message);
+    this.name = 'WorktreeError';
+    this.code = code;
+    this.field = options.field;
+    this.count = options.count;
+  }
+
+  toFailure(): WorktreeFailure {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.field ? { field: this.field } : {}),
+      ...(this.count !== undefined ? { count: this.count } : {}),
+    };
+  }
+}
+
+/** Turn anything thrown into a failure, so an unexpected error is still typed. */
+export function asWorktreeFailure(error: unknown): WorktreeFailure {
+  if (error instanceof WorktreeError) return error.toFailure();
+  return { code: 'create_failed', message: error instanceof Error ? error.message : String(error) };
+}

package/src/server/lib/fs/worktree/list.test.ts

@@ -0,0 +1,207 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Worktree listing, against real repositories.
+ *
+ * Three answers here cannot be faked by a hand-written porcelain string, and
+ * each is a case that has to keep working:
+ *
+ *  - a linked worktree is NOT the primary, and a deleted directory is `missing`
+ *    while its entry stays in the list (the sessions that lived there must keep
+ *    their row);
+ *  - two spellings of one directory reconcile — on macOS git prints
+ *    `/private/tmp/...` for a path the caller typed as `/tmp/...`, and a
+ *    comparison that ignored that decided a worktree was not inside itself;
+ *  - the session → worktree lookup picks the INNER worktree, because that is
+ *    the directory the agent writes to.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalPath, pathHolds } from '@/server/lib/fs/canonical';
+import { findBranchInUse, listWorktrees, parseWorktreePorcelain } from '@/server/lib/fs/worktree/list';
+import { invalidateWorktreeTopology, readProjectWorktrees, worktreeForCwd } from '@/server/lib/fs/worktree/topology';
+import { removeDir } from '@/test-support/remove-dir';
+
+const FIXTURE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-worktree-list-'));
+
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({
+    cmd: ['git', ...args],
+    cwd,
+    env: { ...Bun.env, GIT_EDITOR: 'true', GIT_TERMINAL_PROMPT: '0' },
+  });
+  return result.stdout.toString();
+}
+
+function makeRepo(name: string): string {
+  const dir = path.join(FIXTURE_ROOT, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  git(dir, 'config', 'user.email', 'test@example.invalid');
+  git(dir, 'config', 'user.name', 'Test');
+  fs.writeFileSync(path.join(dir, 'f.txt'), 'a\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'base');
+  return dir;
+}
+
+afterAll(async () => {
+  await invalidateWorktreeTopology();
+  removeDir(FIXTURE_ROOT);
+});
+
+describe('parseWorktreePorcelain', () => {
+  const PORCELAIN = [
+    'worktree /repo',
+    'HEAD aaa',
+    'branch refs/heads/main',
+    '',
+    'worktree /wt/detached',
+    'HEAD bbb',
+    'detached',
+    '',
+    'worktree /wt/gone',
+    'HEAD ccc',
+    'branch refs/heads/feat',
+    'prunable gitdir file points to non-existent location',
+    '',
+    'worktree /bare',
+    'bare',
+    '',
+  ].join('\n');
+
+  test('reads the branch, a detached HEAD, a prunable entry, and drops a bare repo', () => {
+    const entries = parseWorktreePorcelain(PORCELAIN);
+    expect(entries.map((entry) => entry.path)).toEqual(['/repo', '/wt/detached', '/wt/gone']);
+    expect(entries[0]?.branch).toBe('main');
+    expect(entries[1]?.detached).toBe(true);
+    expect(entries[1]?.branch).toBe('');
+    expect(entries[2]?.missing).toBe(true);
+  });
+
+  test('a bare repository is not a checkout anything can run in', () => {
+    expect(parseWorktreePorcelain(PORCELAIN).some((entry) => entry.path === '/bare')).toBe(false);
+  });
+});
+
+describe('listWorktrees', () => {
+  test('flags the primary and a linked worktree apart', async () => {
+    const repo = makeRepo('list-basic');
+    const linked = path.join(FIXTURE_ROOT, 'list-basic-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'feat', linked);
+
+    const entries = await listWorktrees(repo);
+    const primary = entries.find((entry) => entry.isPrimary);
+    const other = entries.find((entry) => !entry.isPrimary);
+    expect(primary?.path).toBe(await canonicalPath(repo));
+    expect(other?.branch).toBe('feat');
+    expect(other?.missing).toBe(false);
+    // Paths come back canonical, whichever spelling git was handed.
+    expect(other?.path).toBe(await canonicalPath(linked));
+  });
+
+  test('a directory deleted outside git stays listed as missing', async () => {
+    const repo = makeRepo('list-missing');
+    const linked = path.join(FIXTURE_ROOT, 'list-missing-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'gone', linked);
+    fs.rmSync(linked, { recursive: true, force: true });
+
+    const entries = await listWorktrees(repo);
+    const entry = entries.find((candidate) => !candidate.isPrimary);
+    expect(entry?.missing).toBe(true);
+    // And the missing path still canonicalizes, so it can be matched at all.
+    expect(entry?.path).toBe(await canonicalPath(linked));
+  });
+
+  test('findBranchInUse names the worktree that holds a branch', async () => {
+    const repo = makeRepo('list-in-use');
+    const linked = path.join(FIXTURE_ROOT, 'list-in-use-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'held', linked);
+
+    const hit = await findBranchInUse(repo, 'held');
+    expect(hit?.path).toBe(await canonicalPath(linked));
+    expect(await findBranchInUse(repo, 'free')).toBeNull();
+  });
+});
+
+describe('canonical paths', () => {
+  test('a sibling sharing a prefix is not inside', async () => {
+    const base = path.join(FIXTURE_ROOT, 'holds');
+    fs.mkdirSync(path.join(base, 'repo', 'src'), { recursive: true });
+    fs.mkdirSync(path.join(base, 'repo-other'), { recursive: true });
+
+    expect(await pathHolds(path.join(base, 'repo'), path.join(base, 'repo'))).toBe(true);
+    expect(await pathHolds(path.join(base, 'repo'), path.join(base, 'repo', 'src'))).toBe(true);
+    expect(await pathHolds(path.join(base, 'repo'), path.join(base, 'repo-other'))).toBe(false);
+  });
+
+  test('a MISSING path resolves through its nearest existing ancestor', async () => {
+    const base = path.join(FIXTURE_ROOT, 'canonical-missing');
+    fs.mkdirSync(base, { recursive: true });
+    const missing = path.join(base, 'gone', 'deeper');
+    expect(await canonicalPath(missing)).toBe(path.join(await canonicalPath(base), 'gone', 'deeper'));
+  });
+
+  test('`..` cannot escape', async () => {
+    const base = path.join(FIXTURE_ROOT, 'canonical-escape');
+    fs.mkdirSync(base, { recursive: true });
+    expect(await pathHolds(base, path.join(base, '..', 'elsewhere'))).toBe(false);
+  });
+});
+
+describe('session → worktree', () => {
+  test('an inner worktree wins over the checkout that contains it', async () => {
+    const repo = makeRepo('topology');
+    const outer = path.join(FIXTURE_ROOT, 'topology-outer');
+    git(repo, 'worktree', 'add', '-q', '-b', 'outer', outer);
+    fs.mkdirSync(path.join(outer, 'sub'), { recursive: true });
+
+    const entries = await listWorktrees(repo);
+    const primary = entries.find((entry) => entry.isPrimary)?.path as string;
+
+    const inner = await worktreeForCwd(entries, path.join(outer, 'sub'), primary);
+    expect(inner?.path).toBe(await canonicalPath(outer));
+    expect(inner?.branch).toBe('outer');
+    expect(inner?.status).toBe('ready');
+
+    // A session in the checkout itself has no badge — it is not a worktree session.
+    expect(await worktreeForCwd(entries, primary, primary)).toBeNull();
+  });
+
+  test('a missing worktree still answers, with status `missing`', async () => {
+    const repo = makeRepo('topology-missing');
+    const linked = path.join(FIXTURE_ROOT, 'topology-missing-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'vanish', linked);
+    fs.rmSync(linked, { recursive: true, force: true });
+
+    const entries = await listWorktrees(repo);
+    const primary = entries.find((entry) => entry.isPrimary)?.path as string;
+    const badge = await worktreeForCwd(entries, linked, primary);
+    expect(badge?.status).toBe('missing');
+    expect(badge?.branch).toBe('vanish');
+  });
+
+  test('the topology read is cached, and invalidation drops it', async () => {
+    const repo = makeRepo('topology-cache');
+    const first = await readProjectWorktrees(repo);
+    const second = await readProjectWorktrees(repo);
+    expect(second).toBe(first); // same array identity — a real cache hit
+
+    const linked = path.join(FIXTURE_ROOT, 'topology-cache-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'new-one', linked);
+    // Cached: the new worktree is not visible yet.
+    expect((await readProjectWorktrees(repo)).length).toBe(1);
+
+    // AWAITED: the invalidation resolves the canonical key asynchronously, so an
+    // un-awaited call races the read below — measured on both CI legs, where the
+    // read won and the cache still answered one entry.
+    await invalidateWorktreeTopology(await canonicalPath(repo));
+    expect((await readProjectWorktrees(repo)).length).toBe(2);
+  });
+});

package/src/server/lib/fs/worktree/list.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `git worktree list --porcelain`, parsed into rows.
+ *
+ * The two markers a naive parse loses, and both matter to a reader:
+ *
+ *  - **no `branch` line** → detached HEAD, which the row shows as `detached @
+ *    <sha>` and the delete dialog treats as not-a-branch;
+ *  - **`prunable`** → the directory is gone or the gitdir pointer is broken. The
+ *    entry STAYS in the list: the sessions that lived there must keep their row,
+ *    and dropping it would hide them with no way back.
+ *
+ * Paths are canonicalized here, once, for every consumer — git echoes the
+ * spelling it was given while the repository root resolves through symlinks, and
+ * two spellings of one directory must not read as two worktrees.
+ */
+
+import { existsSync } from 'fs';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { runGit } from '@/server/lib/fs/git-run';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
+
+export interface WorktreeEntry {
+  path: string;
+  /** `refs/heads/` stripped; `''` when detached. */
+  branch: string;
+  head: string;
+  detached: boolean;
+  /** git reports it prunable, or the directory is not there. */
+  missing: boolean;
+  /** The checkout the worktree was created from — never removable. */
+  isPrimary: boolean;
+}
+
+/** Split on blank lines; a bare repository is not a checkout anything can run in. */
+export function parseWorktreePorcelain(stdout: string): Omit<WorktreeEntry, 'isPrimary'>[] {
+  interface Pending {
+    path: string;
+    branch?: string;
+    head?: string;
+    missing: boolean;
+    bare: boolean;
+  }
+
+  const entries: Omit<WorktreeEntry, 'isPrimary'>[] = [];
+  let current: Pending | null = null;
+
+  const flush = () => {
+    if (!current?.path || current.bare) {
+      current = null;
+      return;
+    }
+    const branch = current.branch ?? '';
+    const head = current.head ?? '';
+    entries.push({
+      path: current.path,
+      branch,
+      head,
+      detached: !branch && Boolean(head),
+      missing: current.missing,
+    });
+    current = null;
+  };
+
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trimEnd();
+    if (!line) {
+      flush();
+      continue;
+    }
+    if (line.startsWith('worktree ')) {
+      flush();
+      current = { path: line.slice('worktree '.length).trim(), missing: false, bare: false };
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith('HEAD ')) {
+      current.head = line.slice('HEAD '.length).trim();
+      continue;
+    }
+    if (line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).trim().replace(/^refs\/heads\//, '');
+      continue;
+    }
+    if (line === 'bare') current.bare = true;
+    if (line === 'prunable' || line.startsWith('prunable ')) current.missing = true;
+  }
+  flush();
+
+  return entries;
+}
+
+/** Every worktree of the repository `cwd` belongs to, primary first. */
+export async function listWorktrees(cwd: string): Promise<WorktreeEntry[]> {
+  const primaryRoot = await resolveProjectRoot(cwd);
+  const listed = await runGit(['worktree', 'list', '--porcelain'], { cwd: primaryRoot, maxBuffer: 1024 * 1024 });
+  if (listed.exitCode !== 0) throw new Error(listed.stderr.trim() || 'Failed to list git worktrees');
+
+  const canonicalPrimary = await canonicalPath(primaryRoot);
+  const entries: WorktreeEntry[] = [];
+  for (const entry of parseWorktreePorcelain(listed.stdout)) {
+    const canonical = await canonicalPath(entry.path);
+    entries.push({
+      ...entry,
+      path: canonical,
+      isPrimary: canonical === canonicalPrimary,
+      // A directory removed without `prune` answers `existsSync` false, and both
+      // signals mean the same thing to a reader.
+      missing: entry.missing || !existsSync(canonical),
+    });
+  }
+  return entries;
+}
+
+/** Whether `branch` is checked out in any worktree of this repository, and where. */
+export async function findBranchInUse(cwd: string, branch: string): Promise<{ path: string } | null> {
+  const entries = await listWorktrees(cwd);
+  const hit = entries.find((entry) => entry.branch === branch);
+  return hit ? { path: hit.path } : null;
+}
+
+export async function refExists(cwd: string, ref: string): Promise<boolean> {
+  const probe = await runGit(['show-ref', '--verify', '--quiet', ref], { cwd });
+  return probe.exitCode === 0;
+}