feat(worktree): use human-readable names for worktree branches

packages/git/src/worktree-name.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { generateHumanReadableName } from "./worktree-name";
+
+describe("generateHumanReadableName", () => {
+  it("returns a string matching adjective-noun-NN", () => {
+    const name = generateHumanReadableName();
+    expect(name).toMatch(/^[a-z]+-[a-z]+-\d{2}$/);
+  });
+
+  it("produces varied names over many calls", () => {
+    const names = new Set<string>();
+    for (let i = 0; i < 50; i++) {
+      names.add(generateHumanReadableName());
+    }
+    // With 36 * 36 * 90 = ~116k combinations, 50 draws should yield
+    // many unique values. Allow generous slack for randomness.
+    expect(names.size).toBeGreaterThan(20);
+  });
+
+  const samples = Array.from({ length: 25 }, () => generateHumanReadableName());
+
+  it.each(samples)("uses only filesystem-safe characters: %s", (name) => {
+    expect(name).toMatch(/^[a-z0-9-]+$/);
+  });
+
+  it.each(samples)("stays compact (≤32 chars): %s", (name) => {
+    expect(name.length).toBeLessThanOrEqual(32);
+  });
+});

packages/git/src/worktree-name.ts

@@ -0,0 +1,34 @@
+import * as crypto from "node:crypto";
+
+/**
+ * Curated adjective-noun word list used to label worktrees. Words are short,
+ * filesystem-safe (lowercase a-z only), and chosen to be inoffensive.
+ */
+// biome-ignore format: keep word lists compact
+const ADJECTIVES = [
+  "amber", "brave", "calm", "clever", "cosmic", "crisp", "dapper", "dusty",
+  "eager", "fancy", "fluffy", "gentle", "happy", "jolly", "lively", "lucky",
+  "merry", "mighty", "nimble", "plucky", "proud", "quick", "quiet", "rapid",
+  "shiny", "silver", "smooth", "snappy", "spry", "sturdy", "sunny", "swift",
+  "tidy", "vivid", "witty", "zesty",
+];
+
+// biome-ignore format: keep word lists compact
+const NOUNS = [
+  "badger", "beetle", "bison", "cedar", "comet", "cricket", "delta", "ember",
+  "falcon", "ferret", "finch", "fjord", "glade", "harbor", "heron", "ibex",
+  "lemur", "lynx", "marlin", "meadow", "mountain", "otter", "panda", "petal",
+  "pebble", "puffin", "quokka", "raven", "river", "robin", "sparrow", "summit",
+  "tiger", "valley", "willow", "wombat",
+];
+
+/**
+ * Generates a short, human-readable random name (e.g. "swift-otter-42").
+ * Suffix is a 2-digit number to reduce collisions while keeping names compact.
+ */
+export function generateHumanReadableName(): string {
+  const adjective = ADJECTIVES[crypto.randomInt(0, ADJECTIVES.length)];
+  const noun = NOUNS[crypto.randomInt(0, NOUNS.length)];
+  const suffix = crypto.randomInt(10, 100).toString();
+  return `${adjective}-${noun}-${suffix}`;
+}

packages/git/src/worktree.ts

@@ -1,5 +1,4 @@
 import { execFile, spawn } from "node:child_process";
-import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getCleanEnv, getGitOperationManager } from "./operation-manager";
@@ -11,6 +10,7 @@ import {
   listWorktrees as listWorktreesRaw,
 } from "./queries";
 import { clonePath, forceRemove, safeSymlink } from "./utils";
+import { generateHumanReadableName } from "./worktree-name";
 
 export interface WorktreeInfo {
   worktreePath: string;
@@ -44,7 +44,7 @@ export class WorktreeManager {
   }
 
   generateWorktreeName(): string {
-    return crypto.randomInt(1000, 10000).toString();
+    return generateHumanReadableName();
   }
 
   private getWorktreeBaseFolderPath(): string {