Skip to content

fix(worktrees): honor absolute Linux worktree base paths for WSL repos (STA-4772) - #15384

Merged
Jinwoo-H merged 5 commits into
mainfrom
OrcaWin/aug18-p1-sta-4772-wsl-base-path-claude
Aug 21, 2026
Merged

Jinwoo-H merged 5 commits into
mainfrom
OrcaWin/aug18-p1-sta-4772-wsl-base-path-claude

Conversation

@OrcaWin

@OrcaWin OrcaWin commented Aug 18, 2026 •

Copy link
Copy Markdown
Collaborator
Files Added Deleted Net
Test 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​298 $\color{#cf222e}{\Huge{\mathbf{−}}}$​2 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​296
Prod 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​60 $\color{#cf222e}{\Huge{\mathbf{−}}}$​5 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​55

Summary

Fixes STA-4772: for a WSL-backed repository, a project-setup worktree base path written as an absolute Linux path (e.g. /home/user/project/.orca-worktrees) was accepted and reported ready, but worktree create silently ignored it and fell back to the default ~/orca/workspaces mirror inside the distro. The equivalent \\wsl.localhost\<distro>\... UNC value worked.

Root cause

getWorktreePathSettings merges the repo-level worktreeBasePath into workspaceDir before computeWorkspaceRoot runs. For a WSL repo, shouldMirrorWorkspaceDirInsideWsl treats any non-UNC "absolute" value as a desktop-local root that must be mirrored into ~/orca/workspaces — and win32.isAbsolute('/home/…') is true, so an absolute Linux path was classified as a desktop root and silently discarded. No warning is surfaced anywhere on this path.

Fix (create-time normalization)

New shared helper resolveWslRepoWorktreeBasePath(repoPath, basePath) in src/shared/wsl-paths.ts: when (and only when) the repo itself lives on a WSL UNC path and the configured base path is POSIX-absolute (single leading /), translate the base path onto that repo's distro UNC view (\\wsl.localhost\<distro>\<path>), collapsing dot segments. /mnt/<drive> bases deliberately stay on the distro UNC view rather than being remapped to a drive letter — a drive-letter result would re-trigger the desktop-mirroring heuristic that discards the base (found in review). Applied at the two resolution boundaries:

  • src/main/ipc/worktree-logic.ts getEffectiveWorktreeBasePath — covers worktree create (local + remote), base-directory watch targets, trash sweep roots, name retirement, filesystem allowed roots, root preparation, and folder rename.
  • src/shared/worktree/ownership.ts getRepoWorktreeBasePath — keeps buildKnownOrcaWorkspaceLayouts consistent with where creation actually places worktrees, so ownership classification matches.

Create-time (resolution-time) was chosen over save-time as the authoritative boundary because it also repairs already-persisted values, values arriving over the wire from older clients, and keeps the stored setting verbatim as the user typed it (no schema or wire change; the host that executes creation interprets the value).

Deliberately untouched:

  • Native Windows repos (C:\…), macOS/Linux repos, and SSH repos never rewrite: normalization requires the repo path itself to be a WSL UNC path.
  • UNC, drive-letter, //-rooted, and relative base values pass through unchanged.
  • The global workspaceDir setting is not reinterpreted — only the repo-scoped base path, where the repo pins the distro and makes the value unambiguous.

Reproduction evidence (real WSL, Windows 2, Ubuntu-24.04)

Product-level (installed Orca app, disposable repo via orca-cli):

  1. repo add for \\wsl.localhost\Ubuntu-24.04\home\neil\sta4772-repro\repo, then project setup-update --worktree-base-path /home/neil/sta4772-repro/.orca-worktrees → stored verbatim, setupState: ready, no warning.
  2. worktree create → created at \\wsl.localhost\Ubuntu-24.04\home\neil\orca\workspaces\repo\linux-base-probe, warnings: [] — configured base silently ignored. Bug confirmed.
  3. Same with the UNC base value → created at …\sta4772-repro\.orca-worktrees\repo\unc-base-probe. UNC control honored.

Source-level oracle (uncommitted scratch vitest against real wsl.exe, incl. a real git worktree add through the resolved path):

  • baseline 1b5cc00870 (latest main): linux-base cases FAIL (resolve to ~/orca/workspaces), UNC/native/POSIX/default PASS
  • with this change: all 5 PASS (real git worktree created inside the configured Linux base)
  • with this change reverted: identical baseline failures return

Tests

  • src/shared/wsl-paths.test.ts — unit coverage: Linux path → distro UNC (incl. legacy \\wsl$ repos), /mnt/<drive> mapping, UNC/drive/relative passthrough, non-WSL repo passthrough (native Windows, POSIX, //server/share).
  • src/main/ipc/worktree-logic-wsl.test.ts — create-path coverage: Linux base honored through getWorktreePathSettings, repeated calls stable, no dependence on the distro home lookup (first-fallback: getWslHome returning null no longer matters for configured bases), relative bases still anchored to the repo.
  • src/shared/worktree/ownership-worktree-base-path.test.ts — ownership layout for a WSL repo with a Linux base path matches created worktree paths.

Validation

  • pnpm run typecheck clean; oxlint clean on changed files.
  • Targeted vitest suites (wsl-paths, worktree-logic, ownership, trash, root-preparation, watch targets, retirement, allowed roots, local create flow, persistence/IPC setup): pass. worktree-base-directory-watcher.test.ts fails identically on unmodified main (pre-existing Windows failure).
  • Native Windows golden E2E (test:e2e:workspace-session-golden): candidate and unmodified-baseline runs produce identical results on this machine (1 pass; the same two specs fail on both, worktree-create-switch with the harness error "seeded e2e worktrees did not load" — a pre-existing fixture seeding issue unrelated to this change, which only alters behavior when the repo path is a WSL UNC path and a POSIX-absolute repo base path is configured).

Linear: STA-4772.

…s (STA-4772)

Project setup accepted /home/... worktree base paths for WSL-backed
repos and reported them ready, but the WSL workspace-mirroring
heuristic read them as desktop-absolute roots (win32.isAbsolute) and
silently replaced them with ~/orca/workspaces at create time. Resolve
repo-scoped POSIX-absolute base paths into the repo's own distro UNC
form at the resolution boundary, for both creation-path settings and
ownership layouts. UNC, drive, relative, native Windows, macOS/Linux,
and SSH base paths pass through unchanged.
@coderabbitai

coderabbitai Bot commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 396044b3-3dff-42d4-8a0f-2f24dfc1afdc

📥 Commits

Reviewing files that changed from the base of the PR and between 654d3cb and 3b12352.

📒 Files selected for processing (1)
  • src/main/ipc/worktree-logic-wsl.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.


📝 Walkthrough

Walkthrough

The change adds WSL-aware resolution for repository-specific worktree base paths. Absolute POSIX paths are normalized and converted to distro-specific WSL UNC paths. /mnt paths remain in the distro UNC view. Windows, UNC, relative, and non-WSL paths remain unchanged. Worktree path and ownership logic now use the resolved paths. Tests cover synchronous and asynchronous worktree computation, path conversion, fallback behavior, and external worktree classification.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 5 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check ⚠️ Warning The description explains the problem, solution, scope, issue, tests, and validation, but it omits several required template sections and checklist items. Add the required ELI5, Visual Proof with N/A rationale, AI Disclosure, Review, Agent skill boundary, Notes, and Checklist sections.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly identifies the WSL worktree fix and the main behavior change: honoring absolute Linux base paths.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/shared/wsl-paths.ts (1)

61-72: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Shorten this comment.

The comment repeats implementation detail and incident history. Keep the public contract only.

Proposed change
-/**
- * Resolve a repo-scoped worktree base path against the repo's own WSL distro.
- *
- * Why: project setup stores the value verbatim, and for a WSL-backed repo an
- * absolute Linux path like /home/user/trees is the natural spelling of a
- * location inside that distro. Windows path code reads it as drive-relative,
- * so the WSL workspace-mirroring heuristic silently replaced it with
- * ~/orca/workspaces (STA-4772). The repo path pins the distro, making the
- * value unambiguous — translate it to its UNC form. Non-WSL repos and
- * non-POSIX values (UNC, drive, relative) pass through untouched, so native
- * Windows, macOS/Linux, and SSH base paths keep their meaning.
- */
+/** Resolve an absolute POSIX base path for a WSL repo against its distro. Preserve other values. */

As per coding guidelines: “Comments must be concise, non-obvious, and brief—prefer one line.”

Source: Coding guidelines


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ab902be9-72fa-46c0-870c-3dfdbecc0b17

📥 Commits

Reviewing files that changed from the base of the PR and between 1b5cc00 and 00c20fd.

📒 Files selected for processing (6)
  • src/main/ipc/worktree-logic-wsl.test.ts
  • src/main/ipc/worktree-logic.ts
  • src/shared/worktree/ownership-worktree-base-path.test.ts
  • src/shared/worktree/ownership.ts
  • src/shared/wsl-paths.test.ts
  • src/shared/wsl-paths.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

…view

Review findings from three independent passes: mapping /mnt/<drive>
bases to drive letters re-triggered the desktop-mirroring heuristic
that discards the configured base, and uncollapsed dot segments made
ownership layouts disagree with creation. Resolve every POSIX base of
a WSL repo onto the distro UNC view and collapse dot segments in the
resolver so both consumers see one spelling.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/shared/wsl-paths.ts (1)

72-77: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Condense this rationale comment.

Lines 72-77 use six lines for two invariants. Keep a brief comment that states that drvfs paths must remain UNC paths and dot segments must normalize before ownership comparison.

Proposed change
- * Why not toWindowsWslPath: its /mnt/<drive> branch emits a drive-letter path,
- * which the workspace-mirroring heuristic reads as desktop-local and discards —
- * the very bug this resolves. drvfs bases stay on the distro UNC view instead.
- * Dot segments collapse here because ownership layouts compare paths without
- * resolving them, so creation and classification must see the same spelling.
+ * Keep drvfs paths in the distro UNC view so workspace mirroring preserves them.
+ * Normalize dot segments so ownership and creation compare the same path.

As per coding guidelines, “Comments must be concise, non-obvious, and brief—prefer one line.”

Source: Coding guidelines


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 11aa5575-4806-4927-b5db-7678fe451f10

📥 Commits

Reviewing files that changed from the base of the PR and between 00c20fd and 346139d.

📒 Files selected for processing (3)
  • src/main/ipc/worktree-logic-wsl.test.ts
  • src/shared/wsl-paths.test.ts
  • src/shared/wsl-paths.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

@OrcaWin

OrcaWin commented Aug 18, 2026

Copy link
Copy Markdown
Collaborator Author

Independent review pass (3× GPT-5.6-luna via Codex CLI, distinct lenses)

Three read-only reviewers ran against the first commit (00c20fdff9): path-semantics, full consumer sweep + wire safety, and repro/test-quality. All three returned REQUEST-CHANGES; every finding was re-verified against the code before acting. Dispositions:

Confirmed and fixed in 346139d3da:

  1. (all three, major) /mnt/<drive> bases were translated to drive-letter form (/mnt/d/trees → D:\trees), which shouldMirrorWorkspaceDirInsideWsl then read as a desktop-local absolute root and mirrored away — the original silent-ignore bug, surviving for drvfs paths. Fixed: every POSIX base of a WSL repo now resolves onto the distro UNC view (\\wsl.localhost\<distro>\mnt\d\trees), which the mirror heuristic recognizes as an explicit WSL root. End-to-end regression test added through getWorktreePathSettings + computeWorktreePath, plus a real-WSL oracle case.
  2. (two reviewers, minor) Dot segments (/home/x/../trees) collapsed during creation via win32.normalize but not in ownership layouts, so classification could diverge from creation. Fixed: the resolver collapses ./.. segments lexically before translation, so both consumers see one spelling. Tests added (incl. /../.. clamping at the distro root).
  3. (reviewer 3, minor) Async twin and repeated-call coverage was thin. Added an async-twin equivalence test (computeWorktreePathAsync resolves identically) and kept the repeated-resolution assertion.

Verified and declined, with rationale:

  • "Syntax-only decision ignores execution host" (an SSH or POSIX host repo whose path literally spells //wsl.localhost/... would be normalized): this matches the codebase's documented convention that path semantics are decided by syntax, never client platform (isCaseInsensitiveRuntimeRoot, buildWslWorkspaceLayouts already parse WSL UNC unguarded), and a genuine directory with that spelling on a POSIX host is pathological. For real SSH repos (connectionId set, POSIX repo paths) the resolver is a no-op — covered by tests.
  • "Validate/warn at save-time for //home/... or \home\... style values": save-time behavior is unchanged from main (trim-only) by design — create-time resolution is the authoritative boundary chosen here because it also repairs already-persisted values and values from older clients without any wire change. A save-time effective-path preview/warning would be a worthwhile follow-up UX change, tracked outside this fix.
  • "Mixed separators (/home/x\y)": a backslash is a legal POSIX filename character that no \\wsl.localhost\... UNC path can represent at all — a pre-existing limitation of the Windows WSL bridge, not introduced here; such values behave no worse than on main.

Validation after the fixes: 20 test files / 308 tests pass (wsl-paths, worktree-logic, ownership, trash, root-preparation, retirement, plus the real-WSL oracle incl. an actual git worktree add into the configured Linux base); typecheck clean. Golden E2E rerun on the final candidate: golden-worktree-create-switch and golden-quit-relaunch-session pass; the only failure (golden-terminal-file-link) fails identically on unmodified origin/main on this machine (pre-existing, unrelated to worktrees).

Round-two review (3x gpt-5.6-luna + Opus): pin the dotted-base collapse
on both the creation and ownership sides so a one-sided normalization
change cannot silently break classification, and pin the deliberate
drive-letter-base mirror into the distro home.
@OrcaWin

OrcaWin commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator Author

Review round 2 (pre-merge): 3× GPT-5.6-luna + 1× Claude Opus

Fresh reviewers against the final diff on current main (4e058d4a52; branch merges clean, no file overlap with the 61 commits landed since the base). Also re-verified today that the bug still exists on current main: swapping main's resolver files into the branch fails the same 3 real-WSL oracle cases; the branch passes 6/6 — not superseded.

Verdicts: luna: APPROVE, APPROVE-WITH-NITS ×2 · Opus: APPROVE-WITH-NITS. No blockers, no majors.

Acted on (commit 07fe9d2cce, tests only):

  • End-to-end pins for dotted POSIX bases on both sides — creation (computeWorktreePath) and ownership classification — so a future one-sided normalization change can't silently break classification (Opus finding 2, luna finding).
  • End-to-end pin that a drive-letter base (D:\trees) on a WSL repo still deliberately mirrors into the distro home (luna finding).

On record, no change (with rationale):

  • //home/... and \home\... spellings still fall through to the default silently — identical to main for these degenerate inputs; the // exclusion is load-bearing (it protects //server/share UNC bases from mangling), and POSIX leaves // implementation-defined. Belongs to the save-time validation/preview follow-up.
  • Stale "why" comment on the retirement collision-key cache guard (worktree-name-retirement.ts): harmless (the recompute is pure string work now), the comment is still accurate for repos without a configured base, and that file was refactored on main (fix(worktrees): cover WSL distro history and bound the retirement backfill scan (STA-4472, STA-4473) #14924) — touching it here would manufacture a merge conflict for zero behavior change. Post-merge follow-up if desired.

Opus verification highlights: ran 26 adversarial inputs through the real resolver (all round-trip cleanly through parseWslUncPath / comparison folding / relativePathInsideRoot); audited every worktreeBasePath consumer incl. the retirement refactor on current main (all route through the fixed boundary; ProjectHostSetup.worktreeBasePath is write-only); confirmed no wire change (repo-update-schema ships the raw string, resolution is host-side); confirmed pre-fix worktrees under ~/orca/workspaces keep their classification (mirror root is always a known layout) and settings UI keeps showing the user's raw value; mutation-tested the suite (reverting each fix site fails the corresponding new tests).

Full validation on the final head: 114 tests across the four touched suites, typecheck clean.

…rate WSL base-path trade-offs

Opus review round: pin the real invariant (creation output classifies)
instead of paired hardcoded strings, and record that the /mnt UNC route
and the single-leading-slash guard are deliberate so neither gets
'optimized' back into the mirror-discard bug.
@OrcaWin

OrcaWin commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator Author

Review round 2 — 3× GPT-5.6-luna (Codex CLI) + Claude Opus

Fresh lenses against the final diff on current origin/main (4e058d4a52): adversarial input hunt, current-main integration (incl. the retirement-discovery refactor 21b66197be), user-impact/rollout audit, and a full independent Opus review that also adjudicated round-one's declined findings.

Verdicts: luna: APPROVE / APPROVE-WITH-NITS / APPROVE-WITH-NITS. Opus: APPROVE-WITH-NITS. No blockers or majors anywhere; all round-one declines were upheld on re-examination.

Acted on (07fe9d2cce, 654d3cb0d8 — tests and comments only, no behavior change):

Verified and declined:

  • //, ///x, and backslash-rooted (\home\x) base values keep exactly main's behavior (mirror fallback). All are ambiguous with Windows UNC / drive-relative spellings; reinterpreting them would violate the no-silent-reinterpretation rule. Opus concurred on the multi-slash case; the leading-backslash case is the save-time-validation follow-up's territory.
  • Retirement memoization guard comment (worktree-name-retirement.ts) is now conservatively stale for honored-Linux-base repos (key is stable but never memoized — pure string math, zero I/O impact). That file isn't in this diff and was refactored on main (21b66197be); fixing it here invites a needless conflict. Follow-up-sized.
  • repos:update mkdir can wait on a stopped distro's UNC path where the old fallback landed on the desktop dir — pre-existing class for WSL repos, errors handled, OS-bounded (Opus Fix MaxListenersExceededWarning with singleton PTY dispatcher #6, informational).

Notable confirmations from Opus: legacy worktrees under ~/orca/workspaces keep identical classification/visibility with and without a Linux base (the mirror layout is emitted unconditionally); filesystem allow-listing keeps existing mirrored worktrees authorized; no wire change (worktreeBasePath stays a raw string everywhere; nothing reads orcaCreationWorkspaceLayout.path); the retirement-discovery refactor on main actually benefits — an honored UNC root now buckets into the correct distro.

Pre-existing bug found in passing (not this PR): src/main/agent-hooks/first-work-folder-rename.ts:58 passes raw global settings instead of getWorktreePathSettings(repo, …), so macOS/Linux repos with a repo-level base path compute the rename target against the wrong parent and silently skip the rename (WSL unaffected — the planner returns null on win32). Deserves its own ticket.

Opus follow-up: a regressed resolver lands in the ~/orca/workspaces
mirror layout, which also classifies 'external', so the ownership
assertion alone passed either way. Assert containment in the repo-base
layout, which goes red under both one-sided and full reverts.
@OrcaWin

OrcaWin commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator Author

Opus follow-up round: it empirically caught that the new creation/ownership agreement test in 654d3cb was vacuous — a regressed resolver lands in the unconditional ~/orca/workspaces mirror layout, which also classifies external, so the assertion passed either way. Fixed in 3b12352 per its suggestion: assert containment in the repo-base layout (relativePathInsideRoot(layouts[0].path, createdPath) non-null). Revert-verified: 11/11 green with the fix; 5 tests (incl. this one) go red with worktree-logic.ts restored to origin/main. Opus verdict unchanged: APPROVE-WITH-NITS, production code byte-identical since its main report.

@OrcaWin

OrcaWin commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator Author

Opus final pass: verified 3b12352 independently (test-only diff, containment assertion discriminates under revert as predicted, 16/16 green by name). Finding 7 closed; no further findings. Final Opus verdict: APPROVE. Deferred nits on record: retirement memo-guard comment (post-refactor follow-up), stopped-distro mkdir latency (pre-existing class), and the separate-ticket first-work-folder-rename bug.

@Jinwoo-H
Jinwoo-H merged commit 2c24025 into main Aug 21, 2026
47 checks passed
@Jinwoo-H
Jinwoo-H deleted the OrcaWin/aug18-p1-sta-4772-wsl-base-path-claude branch August 21, 2026 02:10
paidaxingyo666 pushed a commit to paidaxingyo666/Manta that referenced this pull request Aug 23, 2026
dallascrilley pushed a commit to dallascrilley/orca that referenced this pull request Aug 27, 2026
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants