fix(projects): keep nested workspaces out of their repository's row

Repository grouping keyed the sidebar row on the git remote alone, so two
projects in one monorepo collapsed into a single row named after the
repository. That row targets one member and the project picker offers one
entry, so a thread started from it runs in a folder you did not choose.

Group keys now include the repo-relative path. Checkouts of one folder still
share a row across environments and worktrees, which is what the setting is
for. This made repository_path identical to repository, so the duplicate
choice is gone from the web and mobile pickers. The literal stays in the
contract, so stored preferences and per-checkout overrides still decode.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: VIPlearner

apps/mobile/src/features/home/homeThreadList.test.ts

@@ -524,7 +524,7 @@ describe("buildHomeThreadGroups", () => {
     expect(groups[0]?.threads.map((thread) => thread.environmentId)).toEqual([remoteEnvironmentId]);
   });
 
-  it("matches web repository, repository-path, and separate grouping modes", () => {
+  it("keeps monorepo workspaces separate in every web grouping mode", () => {
     const environmentId = EnvironmentId.make("environment-1");
     const repositoryIdentity = {
       canonicalKey: "github.com/t3tools/t3code",
@@ -564,17 +564,11 @@ describe("buildHomeThreadGroups", () => {
       }),
     );
 
-    expect(buildGroups(projects, threads, { projectGroupingMode: "repository" })).toHaveLength(1);
-    expect(
-      buildGroups(projects, threads, { projectGroupingMode: "repository_path" }).map(
-        (group) => group.title,
-      ),
-    ).toEqual(["Mobile", "Web"]);
-    expect(
-      buildGroups(projects, threads, { projectGroupingMode: "separate" }).map(
-        (group) => group.title,
-      ),
-    ).toEqual(["Mobile", "Web"]);
+    for (const projectGroupingMode of ["repository", "repository_path", "separate"] as const) {
+      expect(
+        buildGroups(projects, threads, { projectGroupingMode }).map((group) => group.title),
+      ).toEqual(["Mobile", "Web"]);
+    }
   });
 
   it("default view shows only threads from the last 5 days", () => {

apps/mobile/src/features/settings/SettingsProjectGroupingRouteScreen.tsx

@@ -24,12 +24,7 @@ const GROUPING_OPTIONS: ReadonlyArray<{
   {
     mode: "repository",
     label: "Group by repository",
-    description: "Matching repositories appear as one project.",
-  },
-  {
-    mode: "repository_path",
-    label: "Group by repository path",
-    description: "Keep monorepo paths separate.",
+    description: "Matching checkouts appear as one project. Nested workspaces stay separate.",
   },
   {
     mode: "separate",

apps/web/src/components/LegacySidebar.tsx

@@ -227,7 +227,7 @@ const SIDEBAR_LIST_ANIMATION_OPTIONS = {
 const EMPTY_THREAD_JUMP_LABELS = new Map<string, string>();
 const PROJECT_GROUPING_MODE_LABELS: Record<SidebarProjectGroupingMode, string> = {
   repository: "Group by repository",
-  repository_path: "Group by repository path",
+  repository_path: "Group by repository",
   separate: "Keep separate",
 };
 const SIDEBAR_ICON_ACTION_BUTTON_CLASS =
@@ -269,9 +269,8 @@ function projectExpansionPreferenceKeys(project: SidebarProjectSnapshot): string
 function projectGroupingModeDescription(mode: SidebarProjectGroupingMode): string {
   switch (mode) {
     case "repository":
-      return "Projects from the same repository share one sidebar row.";
     case "repository_path":
-      return "Projects group only when both the repository and repo-relative path match.";
+      return "Checkouts of one repository path share a sidebar row. Nested workspaces stay separate.";
     case "separate":
       return "Every project path gets its own sidebar row.";
   }
@@ -2561,9 +2560,6 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
                   <SelectItem hideIndicator value="repository">
                     {PROJECT_GROUPING_MODE_LABELS.repository}
                   </SelectItem>
-                  <SelectItem hideIndicator value="repository_path">
-                    {PROJECT_GROUPING_MODE_LABELS.repository_path}
-                  </SelectItem>
                   <SelectItem hideIndicator value="separate">
                     {PROJECT_GROUPING_MODE_LABELS.separate}
                   </SelectItem>

apps/web/src/components/settings/ProjectDefaultsSettings.tsx

@@ -435,9 +435,6 @@ export function ProjectDefaultsSettings({
                 <SelectItem value="repository">
                   {PROJECT_GROUPING_MODE_LABELS.repository}
                 </SelectItem>
-                <SelectItem value="repository_path">
-                  {PROJECT_GROUPING_MODE_LABELS.repository_path}
-                </SelectItem>
                 <SelectItem value="separate">{PROJECT_GROUPING_MODE_LABELS.separate}</SelectItem>
               </SelectPopup>
             </Select>

apps/web/src/components/settings/ProjectSettingsPanel.tsx

@@ -124,7 +124,7 @@ const ProjectIconPickerDialog = lazy(() =>
 
 export const PROJECT_GROUPING_MODE_LABELS: Record<SidebarProjectGroupingMode, string> = {
   repository: "Group by repository",
-  repository_path: "Group by repository path",
+  repository_path: "Group by repository",
   separate: "Keep separate",
 };
 
@@ -1308,9 +1308,6 @@ function ProjectDetail({
                   <SelectItem hideIndicator value="repository">
                     {PROJECT_GROUPING_MODE_LABELS.repository}
                   </SelectItem>
-                  <SelectItem hideIndicator value="repository_path">
-                    {PROJECT_GROUPING_MODE_LABELS.repository_path}
-                  </SelectItem>
                   <SelectItem hideIndicator value="separate">
                     {PROJECT_GROUPING_MODE_LABELS.separate}
                   </SelectItem>

docs/user/project-settings.md

@@ -19,6 +19,16 @@ Reset that list to use shared actions again. Existing project actions are preser
 Project names, icons, removal, and importing actions from a checkout remain project-specific.
 When there are several checkouts, the checkout picker selects which actions and grouping to edit.
 
+## Project grouping
+
+Project grouping combines checkouts of one repository folder into a single row. A project at
+`~/code/app` and the same folder on another machine or in a worktree share that row.
+
+Folders inside a repository stay separate. Add `~/code/app` and `~/code/app/services/api` as two
+projects, and each keeps its own row. Start a thread in either one.
+
+Turn grouping off to give every checkout its own row.
+
 ## Project icons
 
 Choose an icon, emoji, or image from the project to make it easier to recognize. The choice applies

packages/client-runtime/src/state/projectGrouping.test.ts

@@ -136,6 +136,38 @@ describe("buildProjectGroups", () => {
     }
   });
 
+  it("keeps a monorepo workspace out of its parent repository's group", () => {
+    const rootIdentity = { ...repositoryIdentity, rootPath: "/work/t3code" };
+    const projects = [
+      makeProject("root", "/work/t3code", { repositoryIdentity: rootIdentity }),
+      makeProject("java", "/work/t3code/java", { repositoryIdentity: rootIdentity }),
+      makeProject("account_approval", "/work/t3code/python/account_approval", {
+        repositoryIdentity: rootIdentity,
+      }),
+    ];
+
+    for (const mode of ["repository", "repository_path"] as const) {
+      const groups = buildProjectGroups({ projects, settings: settings(mode) });
+      expect(groups.map((group) => group.label)).toEqual(["root", "java", "account_approval"]);
+    }
+  });
+
+  it("groups checkouts of one monorepo workspace across environments", () => {
+    const projects = [
+      makeProject("local", "/work/t3code/java", {
+        repositoryIdentity: { ...repositoryIdentity, rootPath: "/work/t3code" },
+      }),
+      makeProject("remote", "/srv/t3code/java", {
+        environmentId: EnvironmentId.make("remote-environment"),
+        repositoryIdentity: { ...repositoryIdentity, rootPath: "/srv/t3code" },
+      }),
+    ];
+
+    const groups = buildProjectGroups({ projects, settings: settings("repository") });
+    expect(groups).toHaveLength(1);
+    expect(groups[0]?.members.map((member) => member.project.id)).toEqual(["local", "remote"]);
+  });
+
   it("uses a shared custom title as the repository group's label", () => {
     const projects = [
       makeProject("first", "/work/t3code", { title: "Custom project" }),

packages/client-runtime/src/state/projectGrouping.ts

@@ -96,19 +96,20 @@ export function resolveProjectGroupingMode(
   );
 }
 
+/**
+ * Groups checkouts of one repository path, so the same workspace opened in
+ * several environments or worktrees shares a row. Nested workspaces keep their
+ * repo-relative path in the key: a monorepo package is its own project, and
+ * collapsing it into the repository row would leave no way to target it.
+ */
 function deriveRepositoryScopedKey(
   project: Pick<EnvironmentProject, "workspaceRoot" | "repositoryIdentity">,
-  groupingMode: SidebarProjectGroupingMode,
 ): string | null {
   const canonicalKey = project.repositoryIdentity?.canonicalKey;
   if (!canonicalKey) {
     return null;
   }
 
-  if (groupingMode === "repository") {
-    return canonicalKey;
-  }
-
   const relativeProjectPath = deriveRepositoryRelativeProjectPath(project);
   if (relativeProjectPath === null) {
     return canonicalKey;
@@ -134,7 +135,7 @@ export function deriveLogicalProjectKey(
   }
 
   return (
-    deriveRepositoryScopedKey(project, groupingMode) ??
+    deriveRepositoryScopedKey(project) ??
     derivePhysicalProjectKey(project) ??
     scopedProjectKey(scopeProjectRef(project.environmentId, project.id))
   );

packages/contracts/src/settings.ts

@@ -52,6 +52,9 @@ export const SidebarThreadSortOrder = Schema.Literals(["updated_at", "created_at
 export type SidebarThreadSortOrder = typeof SidebarThreadSortOrder.Type;
 export const DEFAULT_SIDEBAR_THREAD_SORT_ORDER: SidebarThreadSortOrder = "updated_at";
 
+// "repository_path" is a legacy alias of "repository": both group checkouts of
+// one repository path and keep nested workspaces separate. Stored preferences
+// still carry it, so it stays decodable.
 export const SidebarProjectGroupingMode = Schema.Literals([
   "repository",
   "repository_path",