BOT-1571: Clarify stable project IDs after project rename

AGENTS.md

@@ -124,6 +124,12 @@ copies to `src-tauri/binaries/goosed-$(rustc -vV | sed -n 's|host: ||p')`, which
 is the filename Tauri expects. Use `GOOSE_BIN=/path/to/goose` only as an explicit
 local override.
 
+## Projects
+
+`ProjectInfo.id` is assigned when a project is created and must remain
+stable. Renaming a project updates only its display name; sessions, chat
+groups, and other persisted references continue to use the original id.
+
 ## Conventions
 
 - Use `@/` imports for frontend code.

src-tauri/crates/berdctl/api-surface-feedback.json

@@ -924,7 +924,7 @@
       "description": "Manage the user's projects: create, list, get, attach folder, detach folder, set startup mode, archive.",
       "actions": {
         "create": {
-          "description": "Create a new project; it appears immediately in the app's project list.",
+          "description": "Create a new project; it appears immediately in the app's project list. The result includes a warning if a working directory is already attached to another active project.",
           "fields": [
             {
               "name": "name",

src-tauri/crates/berdctl/api-surface.json

@@ -924,7 +924,7 @@
       "description": "Manage the user's projects: create, list, get, attach folder, detach folder, set startup mode, archive.",
       "actions": {
         "create": {
-          "description": "Create a new project; it appears immediately in the app's project list.",
+          "description": "Create a new project; it appears immediately in the app's project list. The result includes a warning if a working directory is already attached to another active project.",
           "fields": [
             {
               "name": "name",

src-tauri/crates/berdctl/cli-surface-feedback.json

@@ -115,7 +115,7 @@
         "create": {
           "action": "create",
           "about": "Create a new project",
-          "afterHelp": "Example:\n  berdctl project create --name \"Code reviews\" \\\n    --instructions \"Prefer small diffs\" \\\n    --working-dir /Users/me/src/api --working-dir /Users/me/src/web\n\nResult:\n  {\"project_id\": \"...\"} — the project appears immediately in the app's\n  project list with both directories attached."
+          "afterHelp": "Example:\n  berdctl project create --name \"Code reviews\" \\\n    --instructions \"Prefer small diffs\" \\\n    --working-dir /Users/me/src/api --working-dir /Users/me/src/web\n\nResult:\n  {\"project_id\": \"...\", \"warning\": \"...\"?} — the project appears\n  immediately in the app's project list with both directories attached."
         },
         "list": {
           "action": "list",
@@ -219,7 +219,7 @@
         "context": {
           "action": "get_context",
           "about": "Read what the user is looking at in the app right now",
-          "afterHelp": "Example:\n  berdctl info context --json\n\nResult:\n  {\"view\": \"...\", \"active_session_id\": \"...\"|null,\n   \"active_project_id\": \"...\"|null, \"voice_session_active\": true|false,\n   \"app_version\": \"...\"}"
+          "afterHelp": "Example:\n  berdctl info context --json\n\nResult:\n  {\"view\": \"...\", \"active_session_id\": \"...\"|null,\n   \"active_project_id\": \"...\"|null, \"active_project_name\": \"...\"|null,\n   \"voice_session_active\": true|false, \"app_version\": \"...\"}\n\n\"active_project_id\" is a stable identifier that does not change when the\nproject is renamed; \"active_project_name\" is the project's current display\nname and may not match the id (e.g. \"goose-internal\" / \"Berd\")."
         }
       }
     }

src-tauri/crates/berdctl/cli-surface.json

@@ -115,7 +115,7 @@
         "create": {
           "action": "create",
           "about": "Create a new project",
-          "afterHelp": "Example:\n  berdctl project create --name \"Code reviews\" \\\n    --instructions \"Prefer small diffs\" \\\n    --working-dir /Users/me/src/api --working-dir /Users/me/src/web\n\nResult:\n  {\"project_id\": \"...\"} — the project appears immediately in the app's\n  project list with both directories attached."
+          "afterHelp": "Example:\n  berdctl project create --name \"Code reviews\" \\\n    --instructions \"Prefer small diffs\" \\\n    --working-dir /Users/me/src/api --working-dir /Users/me/src/web\n\nResult:\n  {\"project_id\": \"...\", \"warning\": \"...\"?} — the project appears\n  immediately in the app's project list with both directories attached."
         },
         "list": {
           "action": "list",
@@ -203,7 +203,7 @@
         "context": {
           "action": "get_context",
           "about": "Read what the user is looking at in the app right now",
-          "afterHelp": "Example:\n  berdctl info context --json\n\nResult:\n  {\"view\": \"...\", \"active_session_id\": \"...\"|null,\n   \"active_project_id\": \"...\"|null, \"voice_session_active\": true|false,\n   \"app_version\": \"...\"}"
+          "afterHelp": "Example:\n  berdctl info context --json\n\nResult:\n  {\"view\": \"...\", \"active_session_id\": \"...\"|null,\n   \"active_project_id\": \"...\"|null, \"active_project_name\": \"...\"|null,\n   \"voice_session_active\": true|false, \"app_version\": \"...\"}\n\n\"active_project_id\" is a stable identifier that does not change when the\nproject is renamed; \"active_project_name\" is the project's current display\nname and may not match the id (e.g. \"goose-internal\" / \"Berd\")."
         }
       }
     }

src/features/berdctl/__tests__/commands/commands.test.ts

@@ -187,6 +187,7 @@ vi.mock("@/features/projects/api/projects", async (importOriginal) => {
     isWorktreeStartupMode: actual.isWorktreeStartupMode,
     normalizeProjectWorkspaces: actual.normalizeProjectWorkspaces,
     projectWorkspaceFromDirectory: actual.projectWorkspaceFromDirectory,
+    findProjectByWorkingDirectory: actual.findProjectByWorkingDirectory,
     listProjects: (...args: unknown[]) => mocks.listProjects(...args),
     createProject: (...args: unknown[]) => mocks.createProject(...args),
     archiveProject: (...args: unknown[]) => mocks.archiveProject(...args),
@@ -3851,6 +3852,31 @@ describe("projects", () => {
     expect(result).toEqual({ project_id: "p-new" });
   });
 
+  it("create warns (but still creates) when a working dir duplicates an existing active project", async () => {
+    const existing = makeProject({
+      id: "existing",
+      name: "Existing Project",
+      workingDirs: ["/work"],
+    });
+    mocks.listProjects.mockResolvedValue([existing]);
+    mocks.createProject.mockResolvedValue(makeProject({ id: "p-new" }));
+
+    const result = await dispatchCommand(
+      "projects",
+      {
+        action: "create",
+        name: "Duplicate Project",
+        working_dir: ["/work"],
+      },
+      ctx,
+    );
+
+    expect(result).toEqual({
+      project_id: "p-new",
+      warning: expect.stringContaining('"Existing Project" (existing)'),
+    });
+  });
+
   it("list refetches from the backend and excludes archived projects", async () => {
     // Stale cache that the refetch must replace.
     useProjectStore.setState({ projects: [makeProject({ id: "stale" })] });
@@ -5182,6 +5208,41 @@ describe("info", () => {
     );
   });
 
+  it("get_context pairs the stable active project id with its current display name", async () => {
+    controller.getAppContext.mockReturnValue({
+      view: "chat",
+      activeSessionId: "session-2",
+      activeProjectId: "project-9",
+    });
+    useProjectStore.setState({
+      projects: [
+        makeProject({ id: "project-9", name: "Renamed Display Name" }),
+      ],
+      hasFetchedProjects: true,
+    });
+    mocks.getVoiceConversationStatus.mockResolvedValue({
+      available: true,
+      unavailableReason: null,
+      lifecycle: "stopped",
+      sessionId: null,
+      ownerWindowLabel: null,
+      microphoneMuted: false,
+      revision: 0,
+    });
+
+    const result = (await dispatchCommand(
+      "info",
+      { action: "get_context" },
+      ctx,
+    )) as {
+      active_project_id: string | null;
+      active_project_name: string | null;
+    };
+
+    expect(result.active_project_id).toBe("project-9");
+    expect(result.active_project_name).toBe("Renamed Display Name");
+  });
+
   it("get_context reports app and active voice context", async () => {
     controller.getAppContext.mockReturnValue({
       view: "chat",

src/features/berdctl/commands/impl/createProject.ts

@@ -24,26 +24,45 @@ export const createProjectCommand = defineCommand({
   destructive: false,
   summary: "Create a new project",
   description:
-    "Create a new project; it appears immediately in the app's project list.",
+    "Create a new project; it appears immediately in the app's project list. " +
+    "The result includes a warning if a working directory is already " +
+    "attached to another active project.",
   helpFooter: `Example:
   berdctl project create --name "Code reviews" \\
     --instructions "Prefer small diffs" \\
     --working-dir /Users/me/src/api --working-dir /Users/me/src/web
 
 Result:
-  {"project_id": "..."} — the project appears immediately in the app's
-  project list with both directories attached.`,
+  {"project_id": "...", "warning": "..."?} — the project appears
+  immediately in the app's project list with both directories attached.`,
   schema: createProjectSchema,
   execute: async (args) => {
     const [
       { DEFAULT_PROJECT_COLOR },
       { DEFAULT_PROJECT_ICON },
       { useProjectStore },
+      { findProjectByWorkingDirectory },
+      { loadProjectsForBerdctl },
     ] = await Promise.all([
       import("@/features/projects/lib/projectDefaults"),
       import("@/features/projects/lib/projectIcons"),
       import("@/features/projects/stores/projectStore"),
+      import("@/features/projects/api/projects"),
+      import("../runtime/projects"),
     ]);
+    const workingDirs = args.working_dir ?? [];
+    let duplicate: { id: string; name: string } | null = null;
+    if (workingDirs.length > 0) {
+      await loadProjectsForBerdctl();
+      const existingProjects = useProjectStore.getState().projects;
+      for (const dir of workingDirs) {
+        const match = findProjectByWorkingDirectory(existingProjects, dir);
+        if (match) {
+          duplicate = match;
+          break;
+        }
+      }
+    }
     // Deliberately no berd_project Create Completed telemetry: berdctl
     // creates are agent/automation-driven, and the event tracks human-driven
     // UI surfaces only — matching the documented berdctl exclusions in the
@@ -57,9 +76,16 @@ Result:
         args.instructions ?? "",
         DEFAULT_PROJECT_ICON,
         DEFAULT_PROJECT_COLOR,
-        args.working_dir ?? [],
+        workingDirs,
         false,
       );
-    return { project_id: project.id };
+    return {
+      project_id: project.id,
+      ...(duplicate
+        ? {
+            warning: `A working directory is already attached to project "${duplicate.name}" (${duplicate.id}); the new project was created anyway.`,
+          }
+        : {}),
+    };
   },
 });

src/features/berdctl/commands/impl/getContext.ts

@@ -8,6 +8,8 @@ interface GetContextResult {
   view: string;
   active_session_id: string | null;
   active_project_id: string | null;
+  /** Current display name of the active project, or null. */
+  active_project_name: string | null;
   voice_session_active: boolean;
   app_version: string;
 }
@@ -41,29 +43,42 @@ export const getContextCommand = defineCommand({
 
 Result:
   {"view": "...", "active_session_id": "..."|null,
-   "active_project_id": "..."|null, "voice_session_active": true|false,
-   "app_version": "..."}`,
+   "active_project_id": "..."|null, "active_project_name": "..."|null,
+   "voice_session_active": true|false, "app_version": "..."}
+
+"active_project_id" is a stable identifier that does not change when the
+project is renamed; "active_project_name" is the project's current display
+name and may not match the id (e.g. "goose-internal" / "Berd").`,
   schema: getContextSchema,
   execute: async (): Promise<GetContextResult> => {
     const [
       { default: packageJson },
       { getAppNavigationController },
       { getVoiceConversationStatus },
       { useVoiceConversationStore },
+      { useProjectStore },
     ] = await Promise.all([
       import("../../../../../package.json"),
       import("../../navigation"),
       import("@/features/voice-conversation/api/voiceConversation"),
       import("@/features/voice-conversation/stores/voiceConversationStore"),
+      import("@/features/projects/stores/projectStore"),
     ]);
     const context = getAppNavigationController().getAppContext();
     const voiceBeforeRefresh = useVoiceConversationStore.getState();
     const nativeVoiceStatus = await getVoiceConversationStatus();
     const voiceAfterRefresh = useVoiceConversationStore.getState();
+    const activeProjectName = context.activeProjectId
+      ? (useProjectStore
+          .getState()
+          .projects.find((project) => project.id === context.activeProjectId)
+          ?.name ?? null)
+      : null;
     return {
       view: context.view,
       active_session_id: context.activeSessionId,
       active_project_id: context.activeProjectId,
+      active_project_name: activeProjectName,
       voice_session_active:
         nativeVoiceStatus.sessionId !== null ||
         rendererVoiceSessionActive(

src/features/projects/api/projects.test.ts

@@ -289,6 +289,8 @@ describe("projects API artifact metadata", () => {
     });
 
     const updateRequest = mocks.sourcesUpdate.mock.calls[0]?.[0];
+    // The source name (the project's stable id) must not change on rename.
+    expect(updateRequest.name).toBe("launch");
     expect(updateRequest.properties.artifact).toEqual(
       createProjectArtifactMetadata({
         projectId: "launch",
@@ -343,6 +345,32 @@ describe("projects API artifact metadata", () => {
   });
 });
 
+describe("findProjectByWorkingDirectory", () => {
+  it("finds an active project via a path-equivalent working directory", async () => {
+    const { findProjectByWorkingDirectory } = await import("./projects");
+    const existing = projectInfo({
+      id: "existing",
+      workingDirs: ["/tmp/launch/"],
+    });
+
+    expect(findProjectByWorkingDirectory([existing], "/tmp/launch")).toEqual(
+      existing,
+    );
+    expect(findProjectByWorkingDirectory([existing], "/tmp/other")).toBeNull();
+  });
+
+  it("ignores archived projects", async () => {
+    const { findProjectByWorkingDirectory } = await import("./projects");
+    const archived = projectInfo({
+      id: "archived",
+      workingDirs: ["/tmp/launch"],
+      archivedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    expect(findProjectByWorkingDirectory([archived], "/tmp/launch")).toBeNull();
+  });
+});
+
 describe("normalizeProjectWorkspaces dedupe identity", () => {
   it("collapses Windows drive-equivalent working dirs to one workspace and ID", async () => {
     const { normalizeProjectWorkspaces } = await import("./projects");

src/features/projects/api/projects.ts

@@ -354,7 +354,10 @@ function slugify(name: string): string {
 /** Pick a slug for `name` that does not collide with any existing project ID
  *  (active or archived). Two display names that normalize to the same slug
  *  (e.g. "My App" and "my-app", or both collapsing to "project" because they
- *  contain no ASCII alphanumerics) are disambiguated with a numeric suffix. */
+ *  contain no ASCII alphanumerics) are disambiguated with a numeric suffix.
+ *
+ *  This becomes `ProjectInfo.id` and is computed once, at creation; renaming
+ *  a project must never recompute it (see AGENTS.md). */
 function uniqueProjectSlug(name: string, existingIds: Set<string>): string {
   const base = slugify(name);
   if (!existingIds.has(base)) {
@@ -390,6 +393,28 @@ export async function listProjects(): Promise<ProjectInfo[]> {
     .sort((a, b) => a.order - b.order);
 }
 
+/** Returns the first active project that already has `workingDir` among its
+ *  working directories, or null. Does not block creation of a duplicate;
+ *  callers use this to warn instead. */
+export function findProjectByWorkingDirectory(
+  projects: ProjectInfo[],
+  workingDir: string,
+): ProjectInfo | null {
+  const normalized = normalizeWorkspacePath(workingDir);
+  if (!normalized) return null;
+  const key = toIdentityKey(normalized);
+  for (const project of projects) {
+    if (project.archivedAt !== null) continue;
+    for (const dir of project.workingDirs) {
+      const candidate = normalizeWorkspacePath(dir);
+      if (candidate && toIdentityKey(candidate) === key) {
+        return project;
+      }
+    }
+  }
+  return null;
+}
+
 export async function scanProjectIcons(
   workingDirs: string[],
 ): Promise<ProjectIconCandidate[]> {