feat: add workspace labels (#231)

* feat: add workspace labels

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address workspace label review

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: centdix

backend/src/__tests__/agents-ui-service.test.ts

@@ -5,6 +5,7 @@ describe("buildAgentsUiWorktreeSummary", () => {
   it("maps worktree snapshots into conversation-aware summary data", () => {
     const summary = buildAgentsUiWorktreeSummary({
       branch: "feature/search",
+      label: "Search ranking",
       baseBranch: "main",
       path: "/repo/__worktrees/feature-search",
       dir: "/repo/__worktrees/feature-search",
@@ -87,6 +88,7 @@ describe("buildAgentsUiWorktreeSummary", () => {
   it("defaults missing conversation metadata to null", () => {
     const summary = buildAgentsUiWorktreeSummary({
       branch: "feature/idle",
+      label: null,
       path: "/repo/__worktrees/feature-idle",
       dir: "/repo/__worktrees/feature-idle",
       archived: false,

backend/src/__tests__/claude-conversation-service.test.ts

@@ -46,6 +46,7 @@ function makeMeta(): WorktreeMeta {
 function makeWorktree(): WorktreeSnapshot {
   return {
     branch: "claude-feature",
+    label: null,
     path: "/tmp/worktrees/claude-feature",
     dir: "claude-feature",
     archived: false,

backend/src/__tests__/lifecycle-service.test.ts

@@ -1063,6 +1063,66 @@ describe("LifecycleService", () => {
     expect(archiveState.entries[0]?.path).toBe(join(repoRoot, "__worktrees", "feature-archive"));
   });
 
+  it("updates and clears a worktree label in metadata and runtime state", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const lifecycle = makeLifecycleService(repoRoot, tmux, runtime);
+
+    const worktreePath = join(repoRoot, "__worktrees", "feature-label");
+    await lifecycle.createWorktree({ branch: "feature-label" });
+    const gitDir = new BunGitGateway().resolveWorktreeGitDir(worktreePath);
+    const paths = getWorktreeStoragePaths(gitDir);
+    await Bun.write(paths.runtimeEnvPath, "runtime-marker\n");
+    await Bun.write(paths.controlEnvPath, "control-marker\n");
+    const allocatedPorts = { ...(await readWorktreeMeta(gitDir))?.allocatedPorts };
+    const labeled = await lifecycle.setWorktreeLabel("feature-label", "  Search ranking  ");
+
+    expect(labeled).toEqual({ label: "Search ranking" });
+    expect((await readWorktreeMeta(gitDir))?.label).toBe("Search ranking");
+    expect(runtime.getWorktreeByBranch("feature-label")?.label).toBe("Search ranking");
+    expect(await Bun.file(paths.runtimeEnvPath).text()).toBe("runtime-marker\n");
+    expect(await Bun.file(paths.controlEnvPath).text()).toBe("control-marker\n");
+    expect((await readWorktreeMeta(gitDir))?.allocatedPorts).toEqual(allocatedPorts);
+
+    const cleared = await lifecycle.setWorktreeLabel("feature-label", "");
+
+    expect(cleared).toEqual({ label: null });
+    expect((await readWorktreeMeta(gitDir))?.label).toBeUndefined();
+    expect(runtime.getWorktreeByBranch("feature-label")?.label).toBeNull();
+    expect(await Bun.file(paths.runtimeEnvPath).text()).toBe("runtime-marker\n");
+    expect(await Bun.file(paths.controlEnvPath).text()).toBe("control-marker\n");
+    expect((await readWorktreeMeta(gitDir))?.allocatedPorts).toEqual(allocatedPorts);
+  });
+
+  it("rejects labeling unmanaged worktrees without creating metadata", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const lifecycle = makeLifecycleService(repoRoot, tmux, runtime);
+    const git = new BunGitGateway();
+    const worktreePath = join(repoRoot, "__worktrees", "feature-unmanaged-label");
+
+    git.createWorktree({
+      repoRoot,
+      worktreePath,
+      branch: "feature-unmanaged-label",
+      mode: "new",
+      baseBranch: "main",
+    });
+    const gitDir = git.resolveWorktreeGitDir(worktreePath);
+    const paths = getWorktreeStoragePaths(gitDir);
+
+    await expect(lifecycle.setWorktreeLabel("feature-unmanaged-label", "Search ranking"))
+      .rejects.toMatchObject({
+        status: 409,
+        message: "Worktree feature-unmanaged-label has no managed metadata to label",
+      });
+    expect(await Bun.file(paths.metaPath).exists()).toBe(false);
+    expect(await Bun.file(paths.runtimeEnvPath).exists()).toBe(false);
+    expect(await Bun.file(paths.controlEnvPath).exists()).toBe(false);
+  });
+
   it("creates a managed docker worktree through the container runtime path", async () => {
     const repoRoot = await initRepo();
     const runtime = new ProjectRuntime();

backend/src/__tests__/native-terminal-service.test.ts

@@ -6,6 +6,7 @@ function makeState(overrides: Partial<ManagedWorktreeRuntimeState> = {}): Manage
   return {
     worktreeId: "wt_feature_search",
     branch: "feature/search",
+    label: null,
     baseBranch: null,
     path: "/repo/__worktrees/feature-search",
     profile: "default",

backend/src/__tests__/project-runtime.test.ts

@@ -16,6 +16,7 @@ describe("ProjectRuntime", () => {
 
     expect(state.worktreeId).toBe("wt_search");
     expect(state.branch).toBe("feature/search");
+    expect(state.label).toBeNull();
     expect(state.baseBranch).toBe("main");
     expect(state.profile).toBe("default");
     expect(state.agentName).toBe("claude");
@@ -109,4 +110,26 @@ describe("ProjectRuntime", () => {
     expect(runtime.getWorktreeByBranch("feature/search")).toBeNull();
     expect(runtime.getWorktreeByBranch("feature/search-v2")?.worktreeId).toBe("wt_search");
   });
+
+  it("updates label metadata without changing branch lookups", () => {
+    const runtime = new ProjectRuntime();
+    runtime.upsertWorktree({
+      worktreeId: "wt_search",
+      branch: "feature/search",
+      label: "Search UI",
+      path: "/repo/__worktrees/feature-search",
+      runtime: "host",
+    });
+
+    const state = runtime.upsertWorktree({
+      worktreeId: "wt_search",
+      branch: "feature/search",
+      label: "Search ranking",
+      path: "/repo/__worktrees/feature-search",
+      runtime: "host",
+    });
+
+    expect(state.label).toBe("Search ranking");
+    expect(runtime.getWorktreeByBranch("feature/search")?.label).toBe("Search ranking");
+  });
 });

backend/src/__tests__/snapshot-service.test.ts

@@ -9,6 +9,7 @@ describe("buildProjectSnapshot", () => {
     runtime.upsertWorktree({
       worktreeId: "wt_search",
       branch: "feature/search",
+      label: "Search ranking",
       baseBranch: "main",
       path: "/repo/__worktrees/feature-search",
       profile: "default",
@@ -100,6 +101,7 @@ describe("buildProjectSnapshot", () => {
     expect(snapshot.worktrees).toEqual([
       {
         branch: "feature/search",
+        label: "Search ranking",
         baseBranch: "main",
         path: "/repo/__worktrees/feature-search",
         dir: "/repo/__worktrees/feature-search",
@@ -219,6 +221,7 @@ describe("buildProjectSnapshot", () => {
     expect(snapshot.worktrees).toEqual([
       {
         branch: "feature/new-flow",
+        label: null,
         baseBranch: "main",
         path: "/repo/__worktrees/feature/new-flow",
         dir: "/repo/__worktrees/feature/new-flow",

backend/src/__tests__/worktree-conversation-service.test.ts

@@ -162,6 +162,7 @@ function makeCodexConversationMeta(threadId: string, cwd: string, lastSeenAt = "
 function makeWorktree(): WorktreeSnapshot {
   return {
     branch: "codex-feature",
+    label: null,
     path: "/tmp/worktrees/codex-feature",
     dir: "codex-feature",
     archived: false,

backend/src/__tests__/worktree-storage.test.ts

@@ -13,6 +13,7 @@ import {
   readWorktreeMeta,
   renderEnvFile,
   writeWorktreePrs,
+  writeWorktreeMeta,
 } from "../adapters/fs";
 import type { WorktreeMeta } from "../domain/model";
 import { createManagedWorktree, initializeManagedWorktree } from "../services/worktree-service";
@@ -398,6 +399,17 @@ describe("initializeManagedWorktree", () => {
     });
   });
 
+  it("normalizes blank labels out of worktree metadata", async () => {
+    gitDir = await mkdtemp(join(tmpdir(), "webmux-meta-label-"));
+
+    await writeWorktreeMeta(gitDir, {
+      ...makeMeta(),
+      label: "   ",
+    });
+
+    expect((await readWorktreeMeta(gitDir))?.label).toBeUndefined();
+  });
+
   it("round-trips PR storage through the worktree webmux dir", async () => {
     gitDir = await mkdtemp(join(tmpdir(), "webmux-prs-gitdir-"));
 

backend/src/adapters/fs.ts

@@ -218,14 +218,25 @@ function normalizeConversationMeta(raw: WorktreeConversationMeta | null | undefi
   return normalized;
 }
 
+function normalizeOptionalString(raw: unknown): string | undefined {
+  return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
+}
+
 function normalizeWorktreeMeta(meta: WorktreeMeta): WorktreeMeta {
   const conversation = normalizeConversationMeta(meta.conversation);
-  return conversation === meta.conversation
-    ? meta
-    : {
-        ...meta,
-        conversation,
-      };
+  const normalizedLabel = normalizeOptionalString(meta.label);
+  if (conversation === meta.conversation && normalizedLabel === meta.label) {
+    return meta;
+  }
+
+  const rest: WorktreeMeta = { ...meta };
+  delete rest.label;
+  delete rest.conversation;
+  return {
+    ...rest,
+    ...(normalizedLabel ? { label: normalizedLabel } : {}),
+    ...(conversation !== undefined ? { conversation } : {}),
+  };
 }
 
 function isPrComment(raw: unknown): raw is PrComment {

backend/src/domain/model.ts

@@ -30,6 +30,7 @@ export interface WorktreeMeta {
   schemaVersion: number;
   worktreeId: string;
   branch: string;
+  label?: string;
   baseBranch?: string;
   createdAt: string;
   profile: string;
@@ -162,6 +163,7 @@ export interface WorktreeCreationSnapshot {
 export interface ManagedWorktreeRuntimeState {
   worktreeId: string;
   branch: string;
+  label: string | null;
   baseBranch: string | null;
   path: string;
   profile: string | null;
@@ -184,6 +186,7 @@ export interface NotificationView {
 
 export interface WorktreeSnapshot {
   branch: string;
+  label: string | null;
   baseBranch?: string;
   path: string;
   dir: string;