@kabmo-labs/kabmo 0.7.0 → 0.9.0

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

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Carry-over: the one capability lost by not calling `omp worktree add`.
+ *
+ * Plain git does NOT copy ignored files — measured: a repository with
+ * `node_modules` and a `.gitignore` yields a worktree holding only the tracked
+ * files, so the agent's first `bun run dev` fails on a project that was working
+ * a second earlier. This copies the ignored build folders with a copy-on-write
+ * clone where the filesystem has one.
+ *
+ * Every path is checked with `git check-ignore`: the allow-list only narrows
+ * WHAT to ask about, it never substitutes for git's answer. A candidate that is
+ * tracked, or that does not exist, is skipped rather than guessed at.
+ */
+
+import { existsSync, statSync } from 'fs';
+import { copyFile, mkdir } from 'fs/promises';
+import path from 'path';
+import { runGit } from '@/server/lib/fs/git-run';
+import { pathExists } from '@/server/lib/omp/core/paths';
+
+/** Folders worth asking git about. A name here that git does not ignore is skipped. */
+export const CARRY_CANDIDATES = [
+  'node_modules',
+  '.venv',
+  'venv',
+  'target',
+  'dist',
+  'build',
+  'out',
+  '.next',
+  '.nuxt',
+  '.turbo',
+  '.parcel-cache',
+  '.cache',
+  'vendor',
+  '__pycache__',
+];
+
+/** Files whose absence breaks a run and whose contents are not in git. */
+export const CARRY_FILE_CANDIDATES = ['.env', '.env.local', '.env.development', '.env.production'];
+
+export type CopyStrategy = 'clonefile' | 'reflink' | 'plain';
+
+export function copyStrategy(platform: NodeJS.Platform = process.platform): CopyStrategy {
+  if (platform === 'darwin') return 'clonefile';
+  if (platform === 'linux') return 'reflink';
+  return 'plain';
+}
+
+export interface CarryResult {
+  copied: string[];
+  /** Candidates git does not call ignored, or that are not there. */
+  skipped: string[];
+  strategy: CopyStrategy;
+}
+
+async function isIgnored(repo: string, relative: string): Promise<boolean> {
+  const probe = await runGit(['check-ignore', '--quiet', '--', relative], { cwd: repo });
+  return probe.exitCode === 0;
+}
+
+/** `cp -c` (APFS clonefile) / `cp --reflink=auto` / `cp -R`, plus a Windows branch. */
+async function copyTree(source: string, destination: string, strategy: CopyStrategy): Promise<void> {
+  await mkdir(path.dirname(destination), { recursive: true });
+  // A regular FILE (`.env`) is not a tree, and every branch below is a tree
+  // copy. `robocopy` takes directories: measured on a Windows runner, a `.env`
+  // source produced no file at the destination and no exit code the caller
+  // reads as a failure, so the carry reported success and the worktree had no
+  // env file — the one thing that path exists to prevent.
+  if (!statSync(source).isDirectory()) {
+    await copyFile(source, destination);
+    return;
+  }
+  if (process.platform === 'win32') {
+    const result = Bun.spawnSync({
+      cmd: ['robocopy', source, destination, '/MIR', '/NFL', '/NDL', '/NJH', '/NJS', '/NC', '/NS', '/NP'],
+      stdout: 'ignore',
+      stderr: 'pipe',
+    });
+    // robocopy reports 0–7 as success codes; anything from 8 up is a real failure.
+    if (result.exitCode !== null && result.exitCode >= 8) {
+      throw new Error(`Failed to copy ${path.basename(source)}: ${result.stderr.toString().trim()}`);
+    }
+    return;
+  }
+  const args = strategy === 'clonefile' ? ['-cR'] : strategy === 'reflink' ? ['--reflink=auto', '-R'] : ['-R'];
+  const result = Bun.spawnSync({ cmd: ['cp', ...args, source, destination], stdout: 'ignore', stderr: 'pipe' });
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to copy ${path.basename(source)}: ${result.stderr.toString().trim()}`);
+  }
+}
+
+/**
+ * Copy the project's ignored build folders and env files into a fresh worktree.
+ *
+ * A failure here is not a failed worktree: the caller reports what could not be
+ * carried and keeps the checkout, because a worktree without `node_modules` is
+ * still a worktree.
+ */
+export async function carryIgnoredInto(input: {
+  primaryRoot: string;
+  worktreePath: string;
+  candidates?: string[];
+}): Promise<CarryResult> {
+  const strategy = copyStrategy();
+  const copied: string[] = [];
+  const skipped: string[] = [];
+
+  const candidates = [...(input.candidates ?? CARRY_CANDIDATES), ...CARRY_FILE_CANDIDATES];
+  for (const candidate of candidates) {
+    const source = path.join(input.primaryRoot, candidate);
+    if (!existsSync(source)) continue;
+    if (!(await isIgnored(input.primaryRoot, candidate))) {
+      skipped.push(candidate);
+      continue;
+    }
+    const destination = path.join(input.worktreePath, candidate);
+    // A tracked path already checked out in the worktree, or a directory that
+    // appeared meanwhile, is not ours to overwrite.
+    if (await pathExists(destination)) {
+      skipped.push(candidate);
+      continue;
+    }
+    await copyTree(source, destination, strategy);
+    copied.push(candidate);
+  }
+
+  return { copied, skipped, strategy };
+}

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

@@ -0,0 +1,249 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Creating a worktree, against real repositories.
+ *
+ * The refusals are the point of this file. git creates the branch BEFORE it
+ * discovers the problem — measured on 2.56: `Preparing worktree` is printed,
+ * the branch exists, and only then does the command fail with "already checked
+ * out", "already exists", or (unborn) `object not found: HEAD`. A create that
+ * relied on git's own ordering would leave a branch behind for an operation the
+ * user was told had failed, so every check runs first and this file proves
+ * nothing is left over.
+ *
+ * The ignored-file carry is the second half: plain `git worktree add` does NOT
+ * copy `node_modules`, so a fresh worktree cannot run a project that worked a
+ * second earlier in the checkout.
+ */
+
+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 } from '@/server/lib/fs/canonical';
+import { createWorktree, planWorktree, type CreateWorktreeDeps } from '@/server/lib/fs/worktree/create';
+import { WorktreeError } from '@/server/lib/fs/worktree/errors';
+import { listWorktrees } from '@/server/lib/fs/worktree/list';
+import { invalidateWorktreeTopology } from '@/server/lib/fs/worktree/topology';
+import { removeDir } from '@/test-support/remove-dir';
+
+const FIXTURE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-worktree-create-'));
+const DATA_DIR = path.join(FIXTURE_ROOT, 'data');
+
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({
+    cmd: ['git', ...args],
+    cwd,
+    env: { ...GIT_ENV_FOR_TESTS },
+  });
+  return result.stdout.toString();
+}
+
+const GIT_ENV_FOR_TESTS = {
+  ...Bun.env,
+  GIT_EDITOR: 'true',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 'test@example.invalid',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 'test@example.invalid',
+};
+
+/** A repository with one commit, a gitignored `node_modules` and a `.env`. */
+function makeRepo(name: string): string {
+  const dir = path.join(FIXTURE_ROOT, name);
+  fs.mkdirSync(path.join(dir, 'node_modules', 'dep'), { recursive: true });
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'node_modules\n.env\n');
+  fs.writeFileSync(path.join(dir, 'node_modules', 'dep', 'index.js'), 'module.exports = {};\n');
+  fs.writeFileSync(path.join(dir, '.env'), 'SECRET=1\n');
+  fs.writeFileSync(path.join(dir, 'readme.md'), 'hello\n');
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'base');
+  return dir;
+}
+
+function makeEmptyRepo(name: string): string {
+  const dir = path.join(FIXTURE_ROOT, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  return dir;
+}
+
+/** The registry, as a Map — the production one is a SQLite row write. */
+function depsFor(records: Map<string, { startRef: string; projectId: string }>): CreateWorktreeDeps {
+  return {
+    identityFor: async () => null,
+    carryIgnored: true,
+    dataDir: DATA_DIR,
+    configuredDirectory: null,
+    record: async (row) => {
+      records.set(await canonicalPath(row.path), { startRef: row.startRef, projectId: row.projectId });
+    },
+  };
+}
+
+afterAll(async () => {
+  await invalidateWorktreeTopology();
+  removeDir(FIXTURE_ROOT);
+});
+
+describe('createWorktree', () => {
+  test('a new branch, a folder that follows it, and our prefix stripped', async () => {
+    const repo = makeRepo('create-basic');
+    const records = new Map<string, { startRef: string; projectId: string }>();
+    const created = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/cosmic-dolphin' },
+      depsFor(records),
+    );
+
+    expect(created.branch).toBe('wt/cosmic-dolphin');
+    expect(path.basename(created.path)).toBe('cosmic-dolphin');
+    expect(fs.existsSync(created.path)).toBe(true);
+    expect(git(created.path, 'rev-parse', '--abbrev-ref', 'HEAD').trim()).toBe('wt/cosmic-dolphin');
+    // `start_ref` is the one value git cannot answer later, so it is recorded.
+    expect(records.get(await canonicalPath(created.path))?.startRef).toBe('HEAD');
+    // The default root is keyed by the repository's identity. Canonicalized
+    // because the fixture root itself resolves through a symlink on macOS.
+    expect(created.path.startsWith(await canonicalPath(path.join(DATA_DIR, 'worktrees')))).toBe(true);
+  });
+
+  test('ignored build folders and .env come along, and the worktree stays clean', async () => {
+    const repo = makeRepo('create-carry');
+    const created = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/carry' },
+      depsFor(new Map()),
+    );
+
+    expect(fs.existsSync(path.join(created.path, 'node_modules', 'dep', 'index.js'))).toBe(true);
+    expect(fs.readFileSync(path.join(created.path, '.env'), 'utf8')).toContain('SECRET');
+    expect(created.carried?.copied).toContain('node_modules');
+    expect(created.carried?.strategy).toBe(
+      process.platform === 'darwin' ? 'clonefile' : process.platform === 'linux' ? 'reflink' : 'plain',
+    );
+    // A carry must not make the new worktree dirty: `git status` there is what a
+    // commit from that tree would be built on.
+    const status = git(created.path, 'status', '--porcelain').trim();
+    expect(status).toBe('');
+  });
+
+  test('the carry can be turned off, and turns nothing else off', async () => {
+    const repo = makeRepo('create-no-carry');
+    const created = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/no-carry', carryIgnored: false },
+      depsFor(new Map()),
+    );
+    expect(fs.existsSync(path.join(created.path, 'node_modules'))).toBe(false);
+    expect(created.carried).toBeNull();
+  });
+
+  test('an existing branch is checked out as it is, and gets no start ref', async () => {
+    const repo = makeRepo('create-existing');
+    git(repo, 'branch', 'free-branch');
+    const created = await createWorktree(
+      { projectPath: repo, mode: 'existing', branch: 'free-branch' },
+      depsFor(new Map()),
+    );
+
+    expect(created.branch).toBe('free-branch');
+    expect(created.createdBranch).toBe(false);
+    expect(created.startRef).toBe('');
+    expect(git(created.path, 'rev-parse', '--abbrev-ref', 'HEAD').trim()).toBe('free-branch');
+  });
+
+  test('an existing branch already checked out is refused before anything is created', async () => {
+    const repo = makeRepo('create-in-use');
+    const failure = createWorktree(
+      { projectPath: repo, mode: 'existing', branch: 'main' },
+      depsFor(new Map()),
+    );
+    await expect(failure).rejects.toThrow(/already checked out/i);
+    expect((await listWorktrees(repo)).filter((entry) => !entry.isPrimary).length).toBe(0);
+  });
+
+  test('an unborn repository is refused with its own code', async () => {
+    const empty = makeEmptyRepo('create-unborn');
+    const failure = createWorktree({ projectPath: empty, mode: 'new', branch: 'wt/x' }, depsFor(new Map()));
+    await expect(failure).rejects.toBeInstanceOf(WorktreeError);
+    await failure.catch((error: WorktreeError) => expect(error.code).toBe('no_commits'));
+  });
+
+  test('a branch that already exists is refused, and leaves no second worktree', async () => {
+    const repo = makeRepo('create-dup');
+    const records = new Map<string, { startRef: string; projectId: string }>();
+    const first = await createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/dup' }, depsFor(records));
+
+    const failure = createWorktree({ projectPath: repo, mode: 'new', branch: 'wt/dup' }, depsFor(records));
+    await failure.catch((error: WorktreeError) => expect(error.code).toBe('branch_exists'));
+
+    const entries = await listWorktrees(repo);
+    expect(entries.filter((entry) => !entry.isPrimary).length).toBe(1);
+    expect(entries.some((entry) => entry.path === first.path)).toBe(true);
+  });
+
+  test('an invalid branch name never reaches git', async () => {
+    const repo = makeRepo('create-bad-name');
+    const failure = createWorktree({ projectPath: repo, mode: 'new', branch: 'has space' }, depsFor(new Map()));
+    await failure.catch((error: WorktreeError) => expect(error.code).toBe('invalid_name'));
+  });
+
+  test('a taken folder name is suffixed, never refused', async () => {
+    const repo = makeRepo('create-collide');
+    const records = new Map<string, { startRef: string; projectId: string }>();
+    const first = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/one', worktreeName: 'same' },
+      depsFor(records),
+    );
+    const second = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/two', worktreeName: 'same' },
+      depsFor(records),
+    );
+
+    expect(path.basename(first.path)).toBe('same');
+    expect(path.basename(second.path)).not.toBe('same');
+    expect(path.basename(second.path).startsWith('same-')).toBe(true);
+  });
+
+  test('a non-Latin branch gets a generated folder instead of an empty one', async () => {
+    const repo = makeRepo('create-cjk');
+    const created = await createWorktree(
+      { projectPath: repo, mode: 'new', branch: '分支/测试' },
+      depsFor(new Map()),
+    );
+    expect(path.basename(created.path).length).toBeGreaterThan(0);
+    // The branch is what the caller typed, verbatim — only the FOLDER needed a
+    // generated name because the branch left no slug.
+    expect(created.branch).toBe('分支/测试');
+  });
+});
+
+describe('planWorktree', () => {
+  test('answers the same refusals without touching disk', async () => {
+    const repo = makeRepo('plan-none');
+    const plan = await planWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/planned' },
+      { identityFor: async () => null, dataDir: DATA_DIR, configuredDirectory: null },
+    );
+    expect(plan.branch).toBe('wt/planned');
+    expect(fs.existsSync(plan.directory)).toBe(false);
+
+    const dup = planWorktree(
+      { projectPath: repo, mode: 'existing', branch: 'main' },
+      { identityFor: async () => null, dataDir: DATA_DIR, configuredDirectory: null },
+    );
+    await dup.catch((error: WorktreeError) => expect(error.code).toBe('branch_in_use'));
+  });
+
+  test('a configured directory wins over the data-dir default', async () => {
+    const repo = makeRepo('plan-configured');
+    const configured = path.join(FIXTURE_ROOT, 'elsewhere');
+    const plan = await planWorktree(
+      { projectPath: repo, mode: 'new', branch: 'wt/configured' },
+      { identityFor: async () => null, dataDir: DATA_DIR, configuredDirectory: configured },
+    );
+    expect(plan.directory.startsWith(await canonicalPath(configured))).toBe(true);
+  });
+});

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

@@ -0,0 +1,262 @@
+/**
+ * @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, isWorkTree, 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);
+  if (!(await isWorkTree(projectPath))) {
+    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) };
+}