Repository navigation
Description
Where did this happen?
Desktop app (macOS)
Version
1.26
What happened?
Worktrees live under ~/.superset/worktrees/<project-id>/<branch>, and the project id is a UUID:
~/.superset/worktrees/d23fcedd-8180-4bb0-9432-931da5173aab/feat/<branch_slug_name>
On v1 that segment was the project name (~/.superset/worktrees/<my_project_name>/…). Every path I touch outside the app now carries 36 characters of hex I can't recognise — cd, the shell prompt, git worktree list, an editor's recent folders — and with more than one project I can't tell the roots apart without looking ids up.
It also can't be referenced from anywhere outside Superset. Agent skills, shell aliases, scripts that map a ticket to a directory, and project instruction files that document where worktrees live all have to hardcode an opaque id that means nothing to a reader and can't be checked by eye.
A related question I couldn't answer from the outside: is that id stable if I remove a project and add it back? If it's re-minted, every one of those references breaks silently — the paths just stop existing, with nothing to explain why. If it's recovered from the cloud by remote URL, that's worth documenting, because from the filesystem there's no way to tell.
Using the project name for that segment (deduplicated on collision), or letting the project carry an explicit folder alias, would fix both the readability and the referenceability.
Steps to reproduce
- Create a workspace in any project.
git worktree list, or look at the terminal's cwd.- The path is
~/.superset/worktrees/<uuid>/<branch>— no project name anywhere in it.
Logs, screenshots, or recordings
The segment comes from one place — packages/host-service/src/trpc/router/workspace-creation/shared/worktree-paths.ts:
projectWorktreesRoot(projectId, base) → resolve(base ?? ~/.superset/worktrees, projectId)
safeResolveWorktreePath(projectId, branch, base) → <base>/<projectId>/<branch>
Only <base> is configurable (Project Settings → Worktree location, or the host-wide worktreeBaseDir); the id segment is always appended, so pointing the base somewhere friendly still gives ~/dev/<my_project_name>/<uuid>/<branch>.
Workaround I'm using: ln -s <uuid> ~/.superset/worktrees/<my_project_name>. Superset never reads the alias and isInsideProjectWorktreesRoot canonicalises with realpath, so nothing breaks — but it's manual, per machine, and points at an id I'd have to re-check if the project were ever re-added.
Activity
github-actions commentedon Sep 4, 2026
Confirmed from the code: the UUID segment is real, it's the only thing the path scheme allows, and — to answer the question the report couldn't answer from outside — the id is not stable across remove + re-add on the normal import path. Everything below is read from source; I didn't run anything.
The segment
packages/host-service/src/trpc/router/workspace-creation/shared/worktree-paths.ts:43-48is the whole story:and
safeResolveWorktreePath(worktree-paths.ts:91-108) appends the branch to that. The only inputs areprojectIdand the base dir, so the project-settings override and the host-wideworktreeBaseDircan only relocate the parent —<base>/<uuid>/<branch>is fixed. Call sites:packages/host-service/src/trpc/router/workspaces/workspaces.ts:692and:965, both passinglocalProject.id.The v1 comparison in the report holds too —
apps/desktop/src/lib/trpc/routers/workspaces/utils/resolve-worktree-path.ts:12-21joinsproject.name, not the id. So this is a deliberate v1→v2 scheme change, not a regression in a single call site, and the "bug" here is really the readability/referenceability loss that came with it.Is the id re-minted on remove + re-add?
Yes, on the normal path.
randomUUID()atpackages/host-service/src/trpc/router/project/handlers.ts:61.project.remove(packages/host-service/src/trpc/router/project/project.ts:849-909) deletes theprojectsrow outright (the cascade takes workspaces with it).createFromImportLocal(handlers.ts:136-172), whose idempotency guard matches onprojects.repoPath— but only against rows that still exist. After a remove there is no row, so it falls through topersistFromResolvedand a fresh UUID.Two paths do preserve an id, and neither is the one you'd hit re-adding a local folder:
project.findByPathwithwalkAllRemotes(project.ts:512-558) recovers a cloud id by remote URL — but that flag is set only by the v1→v2 importer, and the comment atproject.ts:530-532says it's the last consumer of the cloudv2_projectstable and dies with that importer.project.setup(project.ts:648-676) takes aprojectIdsupplied by the host fan-out, which is what keeps the same UUID across multiple hosts for one project.So: any external reference to
~/.superset/worktrees/<uuid>/…survives a rename but not a remove/re-add, and nothing warns you. Worth documenting regardless of whether the naming changes.The symlink workaround is safe for the reason given —
workspaces.worktree_pathis a stored absolute path (packages/host-service/src/db/schema.ts:220), andisInsideProjectWorktreesRootcanonicalises both sides viarealpathSync(worktree-paths.ts:57-73).Reproduction
Behavioural, no test needed: create a workspace, read
worktreePath; thenproject.removeand re-import the same folder via Add repository → import local, create another workspace, and compare the first segment. Abun:testunit repro fits next toworktree-paths.test.ts:Fix direction, and the traps in it
Name-based segments work, but computing them from the current name at call time is the wrong shape.
projectWorktreesRootis also the security predicate behindisInsideProjectWorktreesRoot, andworkspace-cleanup.ts:483-493and:563-573re-derive it at delete time to decide whether a directrm -rfis allowed. If the segment trackedprojects.name, a rename viaproject.update(project.ts:104-124) would move the computed root out from under every existing worktree, and cleanup would silently skip removal with a warning instead of deleting.What that suggests:
worktreeDirNamecolumn, minted once at project creation from a slug of the name (dirNameForEmptyathandlers.ts:20-32is the existing slug helper) with a numeric suffix on collision, and never rewritten on rename. That also closes the injection angle — project names are free text (z.string().min(1),project.ts:108), so an unsanitised name joined intoresolve()givesprojectWorktreesRootthe traversal problemsafeResolveWorktreePathcurrently only guards for branches.workspaces.worktree_path.Consumers that parse the layout and should be checked against any change:
packages/host-service/src/trpc/router/usage/history/aggregate.ts:146-152(assumes exactly one segment betweenworktreesand the workspace name),apps/desktop/src/main/lib/dev-workspace-name.ts:16-39(segment-count based, likely fine), and the scheme assertions inpackages/host-service/test/integration/workspace-create-delete.integration.test.ts:57and:188.l16i commentedon Sep 25, 2026
Fix with PR #7650