@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/shared/lib/fs/file-tree.test.ts

@@ -0,0 +1,183 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The tree edits that let a create and a rename skip a reload.
+ *
+ * Each rule here is a way the rendered tree would disagree with the disk:
+ *
+ * 1. **A nested entry brings the chain that leads to it.** `lib/parse.ts` names
+ *    a folder the tree does not carry yet; without the chain the row is placed
+ *    under a key no branch reaches and simply never renders.
+ * 2. **A collapsed folder is not guessed at.** Its children are not this
+ *    tree's knowledge, so an entry created inside one is deliberately NOT
+ *    inserted — expanding it reads the real directory, which by then holds the
+ *    new entry. Inserting into a guess would show a listing the server never
+ *    produced.
+ * 3. **A rename re-points every descendant.** A folder's children carry its
+ *    path as a prefix; moving the folder without rewriting them leaves rows
+ *    whose `path` no longer resolves and an expansion set keyed by names that
+ *    are gone.
+ * 4. **A rename never loses the moved entry's own loaded children.** Its cache
+ *    entry is rekeyed with it, so a folder renamed while open stays open with
+ *    its contents.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { FsNode } from '@/shared/types';
+import {
+  baseNameOf,
+  parentPathOf,
+  placeEntry,
+  rekeyCache,
+  rekeyExpansion,
+  renameEntryAt,
+  sortEntries,
+  takeEntry,
+} from '@/shared/lib/fs/file-tree';
+
+const file = (path: string): FsNode => ({ name: baseNameOf(path), path, type: 'file' });
+const folder = (path: string, children?: FsNode[]): FsNode =>
+  children ? { name: baseNameOf(path), path, type: 'folder', children } : { name: baseNameOf(path), path, type: 'folder' };
+
+describe('placeEntry', () => {
+  test('a top-level entry lands in the root, folders first', () => {
+    const placed = placeEntry([folder('src'), file('z.ts')], {}, file('a.ts'));
+
+    expect(placed.nodes.map((node) => node.path)).toEqual(['src', 'a.ts', 'z.ts']);
+    expect(placed.cache).toEqual({});
+  });
+
+  test('a nested entry creates the chain that leads to it', () => {
+    const placed = placeEntry([], {}, file('lib/deep/parse.ts'));
+
+    expect(placed.nodes.map((node) => node.path)).toEqual(['lib']);
+    expect(placed.cache.lib?.map((node) => node.path)).toEqual(['lib/deep']);
+    expect(placed.cache['lib/deep']?.map((node) => node.path)).toEqual(['lib/deep/parse.ts']);
+  });
+
+  test('an existing chain is extended, not duplicated', () => {
+    const placed = placeEntry([folder('lib')], { lib: [folder('lib/deep')], 'lib/deep': [] }, file('lib/deep/x.ts'));
+
+    expect(placed.nodes).toHaveLength(1);
+    expect(placed.cache['lib/deep']?.map((node) => node.path)).toEqual(['lib/deep/x.ts']);
+  });
+
+  test('an entry inside a COLLAPSED folder is not inserted', () => {
+    // `src` is listed with `children: null` — the tree has never read it, so
+    // there is nothing to place the entry into and no guess to make.
+    const tree = [folder('src')];
+    const placed = placeEntry(tree, {}, file('src/hidden.ts'));
+
+    expect(placed.nodes).toBe(tree);
+    expect(placed.cache).toEqual({});
+  });
+
+  test('an empty folder is LOADED, and can receive an entry', () => {
+    const placed = placeEntry([folder('src')], { src: [] }, file('src/new.ts'));
+
+    expect(placed.cache.src?.map((node) => node.path)).toEqual(['src/new.ts']);
+  });
+
+  test('a created folder is a folder in the cache too, so it can be expanded', () => {
+    const placed = placeEntry([], {}, folder('packages'));
+
+    expect(placed.nodes[0].type).toBe('folder');
+    expect(placed.nodes[0].children).toBeUndefined();
+  });
+});
+
+describe('takeEntry', () => {
+  test('removes a root entry and hands it back', () => {
+    const taken = takeEntry([file('a.ts'), file('b.ts')], {}, 'a.ts');
+
+    expect(taken.entry?.path).toBe('a.ts');
+    expect(taken.nodes.map((node) => node.path)).toEqual(['b.ts']);
+  });
+
+  test('removes a nested entry from its parent cache', () => {
+    const taken = takeEntry([folder('src')], { src: [file('src/a.ts'), file('src/b.ts')] }, 'src/a.ts');
+
+    expect(taken.entry?.path).toBe('src/a.ts');
+    expect(taken.cache.src?.map((node) => node.path)).toEqual(['src/b.ts']);
+  });
+
+  test('a path the tree does not carry reports no entry and changes nothing', () => {
+    const cache = { src: [file('src/a.ts')] };
+    const taken = takeEntry([folder('src')], cache, 'src/hidden.ts');
+
+    expect(taken.entry).toBeNull();
+    expect(taken.cache).toBe(cache);
+  });
+});
+
+describe('renameEntryAt', () => {
+  test('re-points the node and every descendant', () => {
+    const tree = [folder('src', [folder('src/lib', [file('src/lib/a.ts')])])];
+    const moved = renameEntryAt(tree, 'src', 'lib');
+
+    expect(moved[0].path).toBe('lib');
+    expect(moved[0].name).toBe('lib');
+    expect(moved[0].children?.[0].path).toBe('lib/lib');
+    expect(moved[0].children?.[0].children?.[0].path).toBe('lib/lib/a.ts');
+  });
+
+  test('a sibling whose path merely shares a prefix is left alone', () => {
+    const tree = [file('src.ts'), file('src/a.ts')];
+    const moved = renameEntryAt(tree, 'src', 'lib');
+
+    expect(moved[0]).toBe(tree[0]);
+    expect(moved[1].path).toBe('lib/a.ts');
+  });
+
+  test('a file rename updates its own name', () => {
+    const moved = renameEntryAt([file('a.ts')], 'a.ts', 'nested/b.ts');
+
+    expect(moved[0].path).toBe('nested/b.ts');
+    expect(moved[0].name).toBe('b.ts');
+  });
+});
+
+describe('rekeyCache', () => {
+  test('moves the folder key and every key beneath it', () => {
+    const cache = { src: [folder('src/lib')], 'src/lib': [file('src/lib/a.ts')], other: [file('other/x.ts')] };
+    const moved = rekeyCache(cache, 'src', 'app');
+
+    expect(Object.keys(moved).sort()).toEqual(['app', 'app/lib', 'other']);
+    expect(moved['app/lib']?.[0].path).toBe('app/lib/a.ts');
+    expect(moved.other).toBe(cache.other);
+  });
+});
+
+describe('rekeyExpansion', () => {
+  test('an open folder and its open children stay open under their new paths', () => {
+    const next = rekeyExpansion(new Set(['src', 'src/lib', 'docs']), 'src', 'app');
+
+    expect([...next].sort()).toEqual(['app', 'app/lib', 'docs']);
+  });
+
+  test('a path that only shares a prefix is untouched', () => {
+    const next = rekeyExpansion(new Set(['src.ts']), 'src', 'app');
+
+    expect([...next]).toEqual(['src.ts']);
+  });
+});
+
+describe('sortEntries', () => {
+  test('folders first, then by name — the server’s own order', () => {
+    const sorted = sortEntries([file('b.ts'), folder('z'), file('a.ts'), folder('a')]);
+
+    expect(sorted.map((node) => node.path)).toEqual(['a', 'z', 'a.ts', 'b.ts']);
+  });
+});
+
+describe('path helpers', () => {
+  test('parentPathOf and baseNameOf split a nested path', () => {
+    expect(parentPathOf('lib/deep/a.ts')).toBe('lib/deep');
+    expect(parentPathOf('a.ts')).toBe('.');
+    expect(baseNameOf('lib/deep/a.ts')).toBe('a.ts');
+    expect(baseNameOf('a.ts')).toBe('a.ts');
+  });
+});

package/src/shared/lib/fs/file-tree.ts

@@ -29,3 +29,162 @@ export function rehydrateTree(nodes: FsNode[], cache: Record<string, FsNode[]>):
     return { ...node, children: rehydrateTree(cached, cache) };
   });
 }
+
+/** The folder a path lives in: `.` for a top-level entry. */
+export function parentPathOf(path: string): string {
+  const cut = path.lastIndexOf('/');
+  return cut === -1 ? '.' : path.slice(0, cut);
+}
+
+/** The last segment of a path. */
+export function baseNameOf(path: string): string {
+  const cut = path.lastIndexOf('/');
+  return cut === -1 ? path : path.slice(cut + 1);
+}
+
+/**
+ * The server's own ordering (`lib/fs/listing.ts`): folders first, then by name.
+ *
+ * A locally inserted row has to land where the server would have put it, or the
+ * next real read would visibly reorder the tree under the user.
+ */
+export function sortEntries(nodes: FsNode[]): FsNode[] {
+  return [...nodes].sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'folder' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+/** The listing after a local edit: the root list plus the children cache. */
+export interface TreeEdit {
+  nodes: FsNode[];
+  cache: Record<string, FsNode[]>;
+}
+
+/**
+ * Insert `entry` where its own path says it belongs, creating the folder chain
+ * that leads to it when the tree does not carry it yet.
+ *
+ * This is what lets a create and a rename skip a reload: the panel already
+ * knows the whole answer, and re-reading the root plus every open folder to
+ * learn it back would collapse nothing but cost a request per open folder.
+ *
+ * A chain is only extended through folders whose children are KNOWN — the root
+ * list plus the cache. A collapsed folder's contents are not this tree's to
+ * guess at, so an entry created inside one is simply not inserted: expanding it
+ * reads the real directory, which by then holds the new entry. The chain nodes
+ * that ARE inserted carry no `children` array, so the row's own expand effect
+ * reads them from disk like any other unread folder.
+ */
+export function placeEntry(nodes: FsNode[], cache: Record<string, FsNode[]>, entry: FsNode): TreeEdit {
+  const segments = entry.path.split('/');
+  const nextNodes = [...nodes];
+  const nextCache = { ...cache };
+  let container = nextNodes;
+  let containerKey: string | null = null;
+
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    const folderPath = segments.slice(0, i + 1).join('/');
+    const existing = container.find((node) => node.path === folderPath);
+    const known = existing ? (nextCache[folderPath] ?? existing.children) : null;
+    if (existing && !Array.isArray(known)) return { nodes, cache };
+    const children = Array.isArray(known) ? [...known] : [];
+    if (!existing) container.push({ name: segments[i], path: folderPath, type: 'folder', ignored: false });
+    nextCache[folderPath] = children;
+    container = children;
+    containerKey = folderPath;
+  }
+
+  container.push(entry);
+  if (containerKey !== null) nextCache[containerKey] = sortEntries(container);
+  return { nodes: sortEntries(nextNodes), cache: nextCache };
+}
+
+/**
+ * Remove the entry at `path` from wherever it lives, leaving the rest of the
+ * tree untouched. Returns `entry: null` when the path is not in this tree —
+ * a collapsed folder's contents are not, and that is not an error.
+ */
+export function takeEntry(
+  nodes: FsNode[],
+  cache: Record<string, FsNode[]>,
+  path: string,
+): TreeEdit & { entry: FsNode | null } {
+  const parent = parentPathOf(path);
+  if (parent === '.') {
+    const entry = nodes.find((node) => node.path === path) ?? null;
+    if (!entry) return { entry: null, nodes, cache };
+    return { entry, nodes: nodes.filter((node) => node.path !== path), cache };
+  }
+  const siblings = cache[parent];
+  const entry = siblings?.find((node) => node.path === path) ?? null;
+  if (!entry || !siblings) return { entry: null, nodes, cache };
+  return {
+    entry,
+    nodes,
+    cache: { ...cache, [parent]: siblings.filter((node) => node.path !== path) },
+  };
+}
+
+/**
+ * Re-point one entry and every path beneath it at a new location.
+ *
+ * A folder's descendants carry their parent's path as a prefix, so moving the
+ * folder without rewriting them would leave every child pointing at the old
+ * tree — a row whose `path` no longer resolves, and an expansion set keyed by
+ * names that are gone.
+ *
+ * A branch that does not hold the moved path is returned AS IS: the arrays are
+ * what React diffs, and a rename that rebuilt every unrelated subtree would
+ * re-render the whole tree for a change it did not touch.
+ */
+export function renameEntryAt(nodes: FsNode[], fromPath: string, toPath: string): FsNode[] {
+  let changed = false;
+  const next = nodes.map((node) => {
+    const isMoved = node.path === fromPath || node.path.startsWith(`${fromPath}/`);
+    const nested = Array.isArray(node.children) ? renameEntryAt(node.children, fromPath, toPath) : undefined;
+    // `nested === node.children` holds for a file (`undefined`) and for a folder
+    // whose subtree did not move, so an untouched row keeps its identity.
+    if (!isMoved && nested === node.children) return node;
+    changed = true;
+    const path = isMoved ? (node.path === fromPath ? toPath : `${toPath}${node.path.slice(fromPath.length)}`) : node.path;
+    const renamed: FsNode = isMoved ? { ...node, path, name: baseNameOf(path) } : { ...node };
+    if (nested !== undefined) renamed.children = nested;
+    return renamed;
+  });
+  return changed ? next : nodes;
+}
+
+/**
+ * Move every cache entry under `fromPath` to `toPath`, paths included.
+ *
+ * An entry outside the move keeps its own array identity, for the reason
+ * `renameEntryAt` does: those arrays are what the tree diffs.
+ */
+export function rekeyCache(
+  cache: Record<string, FsNode[]>,
+  fromPath: string,
+  toPath: string,
+): Record<string, FsNode[]> {
+  const next: Record<string, FsNode[]> = {};
+  for (const [key, children] of Object.entries(cache)) {
+    const moved = key === fromPath
+      ? toPath
+      : key.startsWith(`${fromPath}/`)
+        ? `${toPath}${key.slice(fromPath.length)}`
+        : key;
+    next[moved] = moved === key ? children : renameEntryAt(children, fromPath, toPath);
+  }
+  return next;
+}
+
+/** Rewrite the expansion set for a renamed folder, so open branches stay open. */
+export function rekeyExpansion(expanded: Set<string>, fromPath: string, toPath: string): Set<string> {
+  const next = new Set<string>();
+  for (const path of expanded) {
+    if (path === fromPath) next.add(toPath);
+    else if (path.startsWith(`${fromPath}/`)) next.add(`${toPath}${path.slice(fromPath.length)}`);
+    else next.add(path);
+  }
+  return next;
+}

package/src/shared/lib/fs/paths.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { isVirtualPath, stripReadSelector } from '@/shared/lib/fs/paths';
+import { isVirtualPath, lastPathSegment, stripReadSelector } from '@/shared/lib/fs/paths';
 
 describe('stripReadSelector', () => {
   test('peels every selector shape omp accepts', () => {
@@ -88,3 +88,26 @@ describe('isVirtualPath', () => {
     expect(isVirtualPath('')).toBe(false);
   });
 });
+
+describe('lastPathSegment', () => {
+  test('names the last segment on either separator', () => {
+    // The Windows case is the one that shipped broken: the composer's target
+    // trigger read `kabmo · C:\Users\…\cosmic-dolphin`, because `split('/')`
+    // has nothing to cut in a `\`-separated absolute path.
+    expect(lastPathSegment('/data/worktrees/abc/cosmic-dolphin')).toBe('cosmic-dolphin');
+    expect(lastPathSegment('C:\\Users\\u\\AppData\\Local\\worktrees\\abc\\cosmic-dolphin')).toBe('cosmic-dolphin');
+    expect(lastPathSegment('wt/nested/branch')).toBe('branch');
+  });
+
+  test('a trailing separator names the same thing', () => {
+    expect(lastPathSegment('/data/worktrees/abc/cosmic-dolphin/')).toBe('cosmic-dolphin');
+    expect(lastPathSegment('C:\\worktrees\\abc\\cosmic-dolphin\\')).toBe('cosmic-dolphin');
+  });
+
+  test('nothing to name is empty, not a stray separator', () => {
+    expect(lastPathSegment(undefined)).toBe('');
+    expect(lastPathSegment(null)).toBe('');
+    expect(lastPathSegment('')).toBe('');
+    expect(lastPathSegment('/')).toBe('');
+  });
+});

package/src/shared/lib/fs/paths.ts

@@ -107,3 +107,20 @@ export function toAbsolutePath(baseDir: string | null | undefined, relPath: stri
   // Join with the base's own separator: `C:\proj` + `src` → `C:\proj\src`.
   return `${base}${base.includes('\\') && !base.includes('/') ? '\\' : '/'}${rel}`;
 }
+
+/**
+ * The last segment of a path on ANY platform.
+ *
+ * `split('/').pop()` is the shape this replaces, and it is wrong for every
+ * ABSOLUTE path on Windows: a worktree the server created under
+ * `C:\…\worktrees\<id>\cosmic-dolphin` came back whole, so the composer's target
+ * trigger read `kabmo · C:\Users\…\cosmic-dolphin` instead of
+ * `kabmo · cosmic-dolphin` (measured on the Windows E2E leg, which is the only
+ * place it shows — every POSIX path splits the same either way). A trailing
+ * separator is dropped first so `…/cosmic-dolphin/` names the same worktree.
+ */
+export function lastPathSegment(target: string | null | undefined): string {
+  if (!target) return '';
+  const parts = target.replace(/[/\\]+$/, '').split(/[/\\]/);
+  return parts[parts.length - 1] ?? '';
+}

package/src/shared/lib/fs/worktree/settings-keys.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The two worktree setting keys, in a module with NO server imports.
+ *
+ * The server reads them from `kabmo_settings` (`lib/fs/worktree/settings.server.ts`)
+ * and the settings panel writes them through `writeSetting`; both sides need the
+ * same strings, and the client bundle must not pull in `@/db.server` to get them.
+ */
+
+/** Parent directory new worktrees are created in; empty means the default. */
+export const WORKTREE_DIRECTORY_SETTING = 'worktreeDirectory';
+
+/** Whether a create copies the project's ignored build folders. Default: on. */
+export const WORKTREE_CARRY_SETTING = 'worktreeCarryIgnored';

package/src/shared/lib/omp/session/prewarm.ts

@@ -32,7 +32,14 @@ export function spawnCwdForNewSession(
   folders: PrewarmFolderShape[],
   activeSessionId: string | number | null,
   folderId?: number | string,
+  /**
+   * A worktree the draft chose. It wins over the folder's project path, because
+   * that is the whole point of picking one: the chat is born in the worktree and
+   * nothing is ever relocated afterwards.
+   */
+  worktreePath?: string | null,
 ): string | null {
+  if (worktreePath) return worktreePath;
   const target = folderId !== undefined
     ? folders.find((f) => String(f.id) === String(folderId))
     : folders.find((f) => f.sessions?.some((s) => String(s.id) === String(activeSessionId)))

package/src/shared/lib/updates/shell-ua.ts

@@ -19,14 +19,34 @@
  */
 
 /** The native shells that report themselves on the UA. */
-export type ShellKind = 'android' | 'ios';
+export type MobileShellKind = 'android' | 'ios';
 
-/** The token's name, before the slash, per shell. */
-export const SHELL_UA_PREFIXES: Record<ShellKind, string> = {
+/**
+ * The desktop shells. They carry NO User-Agent token — a desktop app is not
+ * downloaded from the console, so the server has nothing to parse per request.
+ * They report their version over the shell bridge instead (`__kabmoDesktop`),
+ * which is why they are a separate family: the version exists, the UA channel
+ * does not.
+ */
+export type DesktopShellKind = 'macos' | 'windows' | 'linux';
+
+/** Every shell Kabmo publishes an artifact for. */
+export type ShellKind = MobileShellKind | DesktopShellKind;
+
+/** The token's name, before the slash, per MOBILE shell. */
+export const SHELL_UA_PREFIXES: Record<MobileShellKind, string> = {
   android: 'KabmoAndroid/',
   ios: 'KabmoIOS/',
 };
 
+/** The desktop family, in the order their release tracks were added. */
+export const DESKTOP_SHELL_KINDS: readonly DesktopShellKind[] = ['macos', 'windows', 'linux'];
+
+/** Whether a shell reports itself over the bridge rather than the User-Agent. */
+export function isDesktopShellKind(kind: string): kind is DesktopShellKind {
+  return (DESKTOP_SHELL_KINDS as readonly string[]).includes(kind);
+}
+
 /**
  * Whether this request came from an Android device at all — the app or a
  * browser on it.
@@ -60,7 +80,7 @@ export function isAndroidDevice(userAgent: string | null | undefined): boolean {
  */
 export function shellVersion(
   userAgent: string | null | undefined,
-  kind: ShellKind,
+  kind: MobileShellKind,
 ): string | null {
   if (!userAgent) return null;
 

package/src/shared/lib/workspace/active-project.ts

@@ -23,6 +23,29 @@ export function activeProjectForSession(
   return { folder: null, projectPath: null };
 }
 
+/**
+ * The root the right-panel tools should operate on for this session: its own
+ * worktree when the session's cwd is a linked checkout, else the folder's
+ * registered project path.
+ *
+ * A worktree session runs OUTSIDE its folder's project directory, so pointing
+ * the panels at `project_path` showed the checkout the agent had left — measured:
+ * every panel kept reading the main tree while the run wrote to the worktree.
+ * The server's `resolveRoot` accepts a worktree of a registered project for the
+ * same reason, so the two agree about what is readable.
+ */
+export function effectiveRootFor(
+  folders: WorkspaceFolderData[],
+  sessionId: string | number | null | undefined,
+): string | null {
+  const { folder } = activeProjectForSession(folders, sessionId);
+  if (!folder) return null;
+  const row = (folder.sessions || []).find((session) => String(session.id) === String(sessionId));
+  const worktree = row?.worktree;
+  if (worktree && worktree.status === 'ready') return worktree.path;
+  return folder.project_path ?? null;
+}
+
 /**
  * Resolve the workspace root the composer should scope `@` file mentions to:
  * the active session's bound project first, then the explicitly selected

package/src/shared/lib/workspace/workspace-modules.test.ts

@@ -20,7 +20,7 @@
 
 import { afterAll, afterEach, describe, expect, test } from 'bun:test';
 
-import { activeProjectForSession, composerRootFor } from '@/shared/lib/workspace/active-project';
+import { activeProjectForSession, composerRootFor, effectiveRootFor } from '@/shared/lib/workspace/active-project';
 import { diffTabId, diffTabName, fileTabId } from '@/shared/lib/workspace/file-tab-id';
 import {
   DEFAULT_RIGHT_PANEL_FRACTION,
@@ -173,6 +173,54 @@ describe('active-project', () => {
     expect(composerRootFor(folders, 30, 1)).toBe('/work/gamma');
   });
 
+  /**
+   * The root the panels follow. A worktree session runs OUTSIDE its folder's
+   * project path, so pointing the panels at `project_path` showed the checkout
+   * the agent had left — measured: every panel kept reading the main tree while
+   * the run wrote to the worktree.
+   */
+  describe('effectiveRootFor', () => {
+    const withWorktree = (status: 'ready' | 'missing'): WorkspaceFolderData[] => [
+      {
+        id: 1,
+        name: 'alpha',
+        project_path: '/work/alpha',
+        isExpanded: true,
+        hasMore: false,
+        totalSessions: 2,
+        sessions: [
+          {
+            id: 'wt-session',
+            folder_id: 1,
+            title: 'in a worktree',
+            worktree: {
+              branch: 'wt/cosmic-dolphin',
+              path: '/data/worktrees/abc/cosmic-dolphin',
+              primaryRoot: '/work/alpha',
+              status,
+              detached: false,
+            },
+          },
+          { id: 'plain', folder_id: 1, title: 'in the checkout' },
+        ],
+      },
+    ];
+
+    test('a ready worktree wins over the folder project path', () => {
+      expect(effectiveRootFor(withWorktree('ready'), 'wt-session')).toBe('/data/worktrees/abc/cosmic-dolphin');
+    });
+
+    test('a MISSING worktree falls back to the project path — a directory that is gone is not a root', () => {
+      expect(effectiveRootFor(withWorktree('missing'), 'wt-session')).toBe('/work/alpha');
+    });
+
+    test('an ordinary session keeps the project path', () => {
+      expect(effectiveRootFor(withWorktree('ready'), 'plain')).toBe('/work/alpha');
+      expect(effectiveRootFor(folders, 30)).toBe('/work/gamma');
+      expect(effectiveRootFor(folders, 999)).toBeNull();
+    });
+  });
+
   test('composerRootFor falls back to the selected folder without a session match', () => {
     expect(composerRootFor(folders, null, 3)).toBe('/work/gamma');
     expect(composerRootFor(folders, 999, 3)).toBe('/work/gamma');

package/src/shared/lib/workspace/worktree/branch-name.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Branch naming and slugging.
+ *
+ * Two rules here are load-bearing and each was a defect first:
+ *
+ *  - `slug('..')` is `..`, and `path.join(root, '..')` escapes the root — so a
+ *    dot-only result is REJECTED, not passed through.
+ *  - our own `wt/` namespace is stripped from the folder (the folder does not
+ *    repeat it) while a repository's own namespace stays visible (`feat/x` →
+ *    `feat-x`), so a folder never reads as a second branch name.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  defaultWorktreeBranch,
+  folderNameForBranch,
+  generateBranchSlug,
+  isPlausibleBranchName,
+  normalizeBranchName,
+  slugWorktreeName,
+  WORKTREE_BRANCH_PREFIX,
+} from '@/shared/lib/workspace/worktree/branch-name';
+
+describe('worktree branch names', () => {
+  test('the generated branch carries our namespace', () => {
+    const branch = defaultWorktreeBranch();
+    expect(branch.startsWith(`${WORKTREE_BRANCH_PREFIX}/`)).toBe(true);
+    expect(branch.slice(WORKTREE_BRANCH_PREFIX.length + 1)).toMatch(/^[a-z]+-[a-z]+$/);
+  });
+
+  test('the ref namespace is stripped and only that', () => {
+    expect(normalizeBranchName('refs/heads/wt/x')).toBe('wt/x');
+    expect(normalizeBranchName('heads/wt/x')).toBe('wt/x');
+    expect(normalizeBranchName('  wt/x  ')).toBe('wt/x');
+  });
+});
+
+describe('folder naming', () => {
+  test('our namespace is stripped, a repository namespace is kept', () => {
+    expect(folderNameForBranch('wt/cosmic-dolphin')).toBe('cosmic-dolphin');
+    expect(folderNameForBranch('feat/payments')).toBe('feat-payments');
+    expect(folderNameForBranch('refs/heads/wt/yak')).toBe('yak');
+    expect(folderNameForBranch('plain')).toBe('plain');
+  });
+
+  test('a folder is one path segment and cannot escape its root', () => {
+    expect(slugWorktreeName('../../etc/passwd')).toBe('etc-passwd');
+    expect(slugWorktreeName('a b/c')).toBe('a-b-c');
+    expect(slugWorktreeName('-weird-')).toBe('weird');
+    // The trap: these two ARE valid path segments and would leave the root.
+    expect(slugWorktreeName('..')).toBe('');
+    expect(slugWorktreeName('.')).toBe('');
+    expect(slugWorktreeName('...')).toBe('');
+  });
+
+  test('a folder name is bounded', () => {
+    expect(slugWorktreeName('x'.repeat(200)).length).toBeLessThanOrEqual(80);
+  });
+
+  test('a non-Latin branch leaves no slug, so the caller generates a name', () => {
+    expect(folderNameForBranch('测试分支')).toBe('');
+  });
+});
+
+describe('generated slugs', () => {
+  test('stay inside the word lists and vary', () => {
+    const seen = new Set<string>();
+    for (let index = 0; index < 60; index += 1) seen.add(generateBranchSlug());
+    expect(seen.size).toBeGreaterThan(10);
+    for (const slug of seen) expect(slug).toMatch(/^[a-z]+-[a-z]+$/);
+  });
+});
+
+describe('branch name plausibility', () => {
+  test('accepts what git accepts', () => {
+    expect(isPlausibleBranchName('wt/ok')).toBe(true);
+    expect(isPlausibleBranchName('feat/payments-v2')).toBe(true);
+  });
+
+  test('refuses what git refuses, before git has to say so', () => {
+    expect(isPlausibleBranchName('')).toBe(false);
+    expect(isPlausibleBranchName('has space')).toBe(false);
+    expect(isPlausibleBranchName('a..b')).toBe(false);
+    expect(isPlausibleBranchName('-leading')).toBe(false);
+    expect(isPlausibleBranchName('trailing/')).toBe(false);
+    expect(isPlausibleBranchName('tilde~1')).toBe(false);
+    expect(isPlausibleBranchName('at@{1}')).toBe(false);
+    expect(isPlausibleBranchName('a//b')).toBe(false);
+  });
+});