@kabmo-labs/kabmo 0.6.1 → 0.8.0

package/src/server/lib/fs/relative-path.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One rule for every name the Files panel WRITES: a path relative to the folder
+ * that was named, nested segments allowed, and nothing that can leave it.
+ *
+ * The panel's create and rename both used to accept a bare name only, which made
+ * a nested path unreachable from the UI: creating `src/lib/parse.ts` meant
+ * creating `src`, expanding it, then `lib`, then the file. The restriction was
+ * never about safety — `resolveWithinRoot` already refuses an escape — it was
+ * the shape of the input field, so the grammar is now stated once and both
+ * callers read it.
+ *
+ * What is refused, and why each one is a distinct decision:
+ *
+ * - an ABSOLUTE path (`/etc/passwd`, `C:\x`): `path.join(dir, abs)` discards the
+ *   folder the user named, so the write would land somewhere the dialog never
+ *   showed. `resolveWithinRoot` catches most of it, but a drive-relative `C:x`
+ *   normalizes under the root and would silently create a file named `C:x`.
+ * - any `..` SEGMENT: the escape itself. `resolveWithinRoot` would refuse a
+ *   result outside the root, but `a/../b.ts` resolves INSIDE it, so the refusal
+ *   would be about the wrong thing — the user would get "Invalid path" for a
+ *   path that looks fine.
+ * - a NUL byte: it truncates the path at the syscall boundary.
+ *
+ * A backslash is treated as a separator rather than refused: a Windows user
+ * types `src\lib\x.ts` into the same field, and refusing it would be a rule the
+ * field cannot explain. Empty and `.` segments are dropped, so `src//x.ts` and
+ * `./src/x.ts` name the same file as `src/x.ts`.
+ *
+ * Returns the normalized POSIX-relative path, or null when it names nothing.
+ */
+export function normalizeRelativePath(raw: string): string | null {
+  const trimmed = raw.trim().replace(/\\/g, '/');
+  if (!trimmed || trimmed.includes('\0')) return null;
+  if (trimmed.startsWith('/') || /^[a-zA-Z]:/.test(trimmed)) return null;
+
+  const segments: string[] = [];
+  for (const segment of trimmed.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') return null;
+    segments.push(segment);
+  }
+  return segments.length > 0 ? segments.join('/') : null;
+}

package/src/server/lib/fs/root-worktree.test.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The WORKTREE branch of the scoped-root allow-list.
+ *
+ * A chat started in a linked checkout runs THERE, outside its folder's
+ * `project_path` — and `resolveRoot` answered the fallback for it (measured), so
+ * Files/Search/Git/Terminal silently showed the app root while the agent wrote
+ * to the worktree.
+ *
+ * The rule is deliberately narrow: the candidate's own REPOSITORY ROOT must be a
+ * registered project, so a registered project never becomes a filesystem grant.
+ * A SUBDIRECTORY of a registered checkout stays refused — the allow-list is exact
+ * roots, and a panel is pointed at a worktree root, never at a folder inside it.
+ *
+ * Its own file, with its own database, because it needs a REAL git repository:
+ * `resolveProjectRoot` only answers for a directory holding a `.git` entry, and
+ * faking that would test the fake.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveRoot } from '@/server/lib/fs/root';
+import { getDb } from '@/server/db.server';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { removeDir } from '@/test-support/remove-dir';
+
+const GIT_ENV = { ...Bun.env, GIT_EDITOR: 'true', GIT_TERMINAL_PROMPT: '0' };
+
+function git(cwd: string, ...args: string[]): string {
+  return Bun.spawnSync({ cmd: ['git', ...args], cwd, env: GIT_ENV }).stdout.toString();
+}
+
+function makeRepo(dir: string): string {
+  mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  git(dir, 'config', 'user.email', 'test@example.invalid');
+  git(dir, 'config', 'user.name', 'Test');
+  writeFileSync(join(dir, 'f.txt'), 'a\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'base');
+  return dir;
+}
+
+let workRoot: string;
+const saved = { SYNC_WORKSPACE: Bun.env.SYNC_WORKSPACE, MOCK: Bun.env.MOCK };
+
+beforeEach(async () => {
+  await isolateDb();
+  Bun.env.SYNC_WORKSPACE = 'false';
+  Bun.env.MOCK = 'false';
+  workRoot = mkdtempSync(join(tmpdir(), 'kabmo-root-worktree-'));
+});
+
+afterEach(async () => {
+  await releaseDb();
+  removeDir(workRoot);
+  for (const [key, value] of Object.entries(saved)) {
+    if (value === undefined) delete Bun.env[key];
+    else Bun.env[key] = value;
+  }
+});
+
+describe('resolveRoot and worktrees', () => {
+  test('a linked worktree of a registered project is allowed', async () => {
+    const repo = makeRepo(join(workRoot, 'repo'));
+    const linked = join(workRoot, 'linked-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'feat', linked);
+
+    const db = await getDb();
+    await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', repo]);
+
+    expect(await resolveRoot(linked, '/fallback')).toBe(linked);
+  });
+
+  test('a SUBDIRECTORY of a registered checkout is still refused', async () => {
+    const repo = makeRepo(join(workRoot, 'repo-sub'));
+    const sub = join(repo, 'src');
+    mkdirSync(sub, { recursive: true });
+
+    const db = await getDb();
+    await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', repo]);
+
+    // The allow-list is EXACT roots. Panels point at a worktree root, which is
+    // what the new branch admits; widening it to subdirectories would turn a
+    // registered project into a filesystem grant for anything beneath it.
+    expect(await resolveRoot(sub, '/fallback')).toBe('/fallback');
+  });
+
+  test('a worktree of an UNREGISTERED repository is refused', async () => {
+    const registered = makeRepo(join(workRoot, 'registered'));
+    const stranger = makeRepo(join(workRoot, 'stranger'));
+    const strangerWt = join(workRoot, 'stranger-wt');
+    git(stranger, 'worktree', 'add', '-q', '-b', 's', strangerWt);
+
+    const db = await getDb();
+    await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', registered]);
+
+    expect(await resolveRoot(strangerWt, '/fallback')).toBe('/fallback');
+    expect(await resolveRoot(stranger, '/fallback')).toBe('/fallback');
+  });
+
+  test('an exact registered project path is still honored, and a missing one falls back', async () => {
+    const repo = makeRepo(join(workRoot, 'exact'));
+    const db = await getDb();
+    await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', repo]);
+
+    expect(await resolveRoot(repo, '/fallback')).toBe(repo);
+    expect(await resolveRoot(join(workRoot, 'gone'), '/fallback')).toBe('/fallback');
+  });
+});

package/src/server/lib/fs/root.ts

@@ -14,6 +14,8 @@
 import path from 'path';
 import { getDb } from '@/server/db.server';
 import { pathExists } from '@/server/lib/omp/core/paths';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
 
 const APP_ROOT = process.cwd();
 
@@ -124,8 +126,18 @@ export async function getDefaultFsRoot(mock: boolean): Promise<string> {
  * the server is allowed to operate on.
  *
  * Returns `fallback` when `rawRoot` is missing, does not exist, or is not on
- * the allow-list (app root / subpath / registered project_path), so existing
- * callers keep their previous behavior for unscoped requests.
+ * the allow-list (app root / subpath / registered project_path / **worktree of
+ * a registered project**), so existing callers keep their previous behavior for
+ * unscoped requests.
+ *
+ * The worktree branch is why a worktree session's panels can point anywhere:
+ * a chat started in a linked checkout runs there, and `resolveRoot` answered the
+ * fallback for it — measured, so Files/Search/Git/Terminal silently showed the
+ * app root while the agent wrote to the worktree. The rule is deliberately
+ * narrow: the candidate's own REPOSITORY ROOT must be a registered project, so a
+ * registered project never becomes a filesystem grant. A SUBDIRECTORY is still
+ * refused — the allow-list stays exact roots, and a panel is pointed at the
+ * worktree root, never at a folder inside it.
  */
 export async function resolveRoot(
   rawRoot: string | null | undefined,
@@ -134,22 +146,39 @@ export async function resolveRoot(
   if (!rawRoot || !rawRoot.trim()) return fallback;
 
   const resolved = path.resolve(rawRoot.trim());
+  if (!(await pathExists(resolved))) return fallback;
 
   // Fast path: the app root and anything beneath it are always allowed.
   if (resolved === APP_ROOT || resolved.startsWith(APP_ROOT + path.sep)) {
-    return (await pathExists(resolved)) ? resolved : fallback;
+    return resolved;
   }
 
-  // Registered workspaces are user-opted project roots — allow exact matches.
+  // Registered workspaces are user-opted project roots — allow exact matches,
+  // compared by canonical path so a `/tmp` vs `/private/tmp` spelling of one
+  // directory is not read as two.
   try {
     const db = await getDb();
-    const row = await db.get(
-      'SELECT project_path FROM workspace_folders WHERE project_path IS NOT NULL AND project_path = ? LIMIT 1',
-      [resolved]
-    );
-    if (row && (await pathExists(resolved))) return resolved;
+    const rows = (await db.all(
+      'SELECT project_path FROM workspace_folders WHERE project_path IS NOT NULL'
+    )) as { project_path: string }[];
+    const canonical = await canonicalPath(resolved);
+    for (const row of rows) {
+      if ((await canonicalPath(row.project_path)) === canonical) return resolved;
+    }
+
+    // A worktree ROOT: `resolveProjectRoot` only asks git when the candidate
+    // holds a `.git` entry, so a linked checkout resolves to the main repository
+    // while an ordinary subdirectory resolves to ITSELF and stays refused. That
+    // is what keeps this rule at "the roots of registered repositories" instead
+    // of "anything beneath one".
+    if (rows.length > 0) {
+      const projectRoot = await canonicalPath(await resolveProjectRoot(resolved));
+      for (const row of rows) {
+        if ((await canonicalPath(row.project_path)) === projectRoot) return resolved;
+      }
+    }
   } catch {
-    // Database unavailable — fall through to the safe fallback.
+    // Database or git unavailable — fall through to the safe fallback.
   }
 
   return fallback;

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);
+  });
+});