[brennanb2025]

	Files	Added	Deleted	Net
Test	38	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1826	$\color{#cf222e}{\Huge{\mathbf{−}}}$​143	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1683
Prod	76	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2289	$\color{#cf222e}{\Huge{\mathbf{−}}}$​441	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1848

ELI5

A project whose files live inside WSL (for example \\wsl.localhost\Ubuntu\home\you\app) should run on that Linux distro, not on Windows. Until now, adding such a folder saved it as a Windows project, so Orca refused to start chat-view chats in it: the agent menu showed "No chat in WSL" and you could only open agents in a terminal. With this PR, adding a WSL folder registers the project with that distro's own Orca server. Chats then start and run inside WSL, and they keep working after Orca restarts.

This only takes effect where WSL hosts are turned on, which today is an internal setting. Everyone else sees no change.

What Changed

Before: every way of adding a WSL folder saved it as a project belonging to Windows. Its files were in Linux, but Windows was in charge of it. Chats need to run on the machine that runs the project, so they were refused.

After: each way of adding a WSL folder asks one question first: which machine runs this folder? If the answer is a WSL distro, Orca starts that distro's Orca server if it isn't running yet (Orca already sets these servers up and pairs with them) and saves the project there. From then on, that server runs the project's chats, including after a restart. This covers:

• the Add Project dialog, with both \\wsl$\… and \\wsl.localhost\… paths
• creating a new Git repository in a WSL folder
• opening a folder, and "Add as Project" from the file explorer
• importing several repositories from one folder; your chosen order is kept, and each project lands where it belongs
• setting a project's location to a WSL folder
• adding a folder from the Orca CLI

What stays the same, or is made safer:

• If the folder is already a saved project, Orca keeps using it. Nothing is moved or converted.
• Duplicate checks run before anything is set up. If setup fails, Orca shows the error. It never quietly saves the folder as a Windows project instead.
• Only the distro you picked is started. Other distros stay stopped.
• Folder projects open in the subfolder you picked. Git Add opens the repo's default checkout, unchanged from main.
• When a chat can't run in chat view (for example, a Windows project that you set to run in WSL), Orca opens the agent in a terminal and says why.
• Saved Windows-owned WSL projects still work from phones. Projects added on a distro's server by this PR cannot yet be reached from a phone through the Windows desktop; that access is tracked in feat(mobile): let paired phones use chats on WSL hosts #28972 and feat(wsl-host): a paired phone reaches the desktop's WSL host and never starts its distro (E6) #33911. Paired clients cannot add new desktop-managed WSL projects and are told to add them on the Windows desktop.
• Adding a folder on this computer no longer picks up a saved SSH project just because the path text matches.

No new saved settings and no new messages between apps, so older phones and paired servers keep working.

Why

The machine that runs a project should be the one in charge of it. That is how SSH projects already work in Orca, and it is the common pattern for remote projects. When Windows was in charge of a project that runs in Linux, Windows and the distro disagreed about who could start its chats, so chats were refused.

The alternative was to keep these as Windows projects and start each chat from Windows through a WSL wrapper. That keeps the split in place: the same project would have two possible owners. It would also need a second launch path for every agent. Reusing the existing server setup removes the split with no new kind of project.

Known limits and follow-ups

• Temporary: if the desktop’s saved distro list is out of date, re-adding a project can still race an earlier removal; tracked in STA-12331.

• Temporary: if the reply to creating a group is lost during a WSL nested import, retrying can leave an extra empty group; tracked in STA-12331.

• Temporary: adding the same new WSL folder twice at the same moment can save it twice; tracked in STA-12331.

• Intended: with WSL hosts turned on, adding a new WSL 1 folder is refused with guidance. Saved projects keep working. WSL 1 support ends under the decision recorded in fix(wsl-host): tell users how to fix a distro Orca can't host (D1c-1) #33085.

• Temporary: importing one group that mixes already-saved Windows projects with new WSL ones is refused before anything changes, with a message to import them separately. This goes away once saved Windows projects can be moved onto their distro, tracked in WSL mover - move driver runs a WSL move end to end (stacked on D1b-8) #31417.

• Temporary: creating a new workspace together with a chat keeps today's order (the workspace is set up first, then the chat starts). That ordering applies to every kind of project and is tracked in STA-11252.

• Temporary: WSL projects on a Windows drive (such as C:\… opened from WSL) keep their current behavior, tracked in feat(wsl): run Git for Windows for a WSL project on a Windows drive (D1c-2) #33090.

• Temporary: other spellings of the same WSL path that Orca doesn't recognize today are tracked in STA-11388.

• Intended: cloning a repository into a WSL folder still clones the way it does today. Cloning on the distro is separate work.

• Intended: a Windows Orca server running without the desktop app refuses to add new WSL projects and says to use the desktop app. Setting up a distro's server is done by the desktop app (where it's set up, where adding refuses without it).

• Intended: WSL hosts stay behind the existing internal setting. Turning them on for everyone is a separate decision.

Related: #28136 (agent launches in folder projects) and #28697 (finding agents in multi-repository folders).

Linked Issue

None (maintainer PR).

Visual Proof

Before	After

The refusal for a mixed group import:

Screenshots for every flow tested, next to the same flow on the release build, are in the review status comment.

Testing

Tested for real on Windows 11 with WSL (Ubuntu), using real Claude and Codex:

• Upgrade: chats created on the released v1.4.240, then the same profile upgraded to this PR. Both Claude and Codex chats replied twice more after the upgrade.
• New WSL chats: new Claude and Codex chats in WSL projects replied. After a normal restart, the same chats came back and replied twice more each, with no duplicate tabs.
• Every way of adding a WSL folder listed above, including both path spellings and the CLI.
• Paired-client boundary: authenticated loopback calls to the Windows desktop refused new WSL Git Create and nested import, with catalogs and files unchanged. This does not establish phone access to guest-owned projects.
• Setting off: with WSL hosts turned off, they are unavailable.
• Terminal fallback opened a working Claude terminal.

Test limits: the Windows folder picker itself was not operated (test agents can't use system dialogs). Adding a folder used the same picker substitute as Orca's automated tests, followed by the real button and everything after it. The desktop app used the reviewed build. A compatible older CI-built WSL server was deliberately retained for the mixed-version checks; its exact provenance is in the review status comment.

CI is green on 2eaaf24152f (47 successful checks and 25 skipped), including typecheck, real WSL terminal checks and old/new version compatibility checks. The necessary main integrations and the removal/re-add ordering correction passed focused tests and independent review. The audit’s targeted Add and nested-import checks passed. The drive-UNC Git Create correction passed source review, its failed-before regression and real Windows QA on ab664e4456e, carried across the reviewed main merges: the new Git project kept Windows ownership and the original UNC path, with one initial commit and a clean working tree. The full result and evidence are in the review status comment.

• I manually tested these changes locally
• Automated tests added/updated

Agent skill upstream boundary

• Not applicable: no upstream skill resources copied.

Author: @BrennanKB5

[brennanb2025]

Adding a WSL folder could leave it owned by Windows, so the first agent launch could not open a native chat in the selected distro. This PR registers supported Add, Git Create, Open root, nested import, existing-folder setup and CLI Add operations on the distro’s server, then carries the returned owner through launch and restart. Saved Windows-owned projects retain their identity. Drive-mount paths keep Windows ownership.

Review: the original source, architecture, reference and performance review is accepted. The audit fixes correct extended UNC placement, linked-worktree matching against an older guest, useful Add errors, all-failed nested import and drive-mount ownership. Ten regression cases failed before those fixes; the 28 tests in two named files then passed. The later drive-UNC Create repair passed independent review and its genuine failed-before regression (23 tests passed), plus the ordinary hook. The necessary main integration passed narrow review, its required hook, and 304 tests in 19 named files. Two later test-only fixture adaptations passed independent review, focused tests and ordinary hooks. Previous CI on bfc125e71b2: 38 successful checks and 25 skipped. The blocking-conflict merge ce01a94cb56 also fixes the incoming deferred-removal race for desktop UNC re-add by reusing the existing environment chain before IPC; the genuine failed-before regression, 54 named tests, required merge hook and narrow both-parent review passed. The later blocking-conflict merge ab664e4456e preserves incoming runtime-registration and composer changes; its hook, 64 tests in seven named files and narrow both-parent review passed. CI on the QA head ab664e4456e: 37 successful checks and 25 skipped. Mobile verify passed one failed-only retry of the unchanged 1,000-row accessibility test timeout; static/typecheck, all unit shards, layouts, old/new version compatibility, packaging and real WSL checks passed.

The later blocking-conflict merge 7dce6f329d2 integrates pinned main 4cd62c4946b, preserving both parents across nine conflicts and ten automatically overlapping files. Its required merge hook and 183 tests in 27 named files passed; independent narrow review agreed on exact tree 8621aa2303b2. The approved Create code and Add ordering chain are unchanged. GitHub did not publish its PR Checks run during the outage; the coordinator authorized empty commit 16f400e49a6 to retrigger it. A new blocking conflict then required merge 2eaaf24152f against main a012e457e8d. That merge preserves the live host lookup after setup while using main’s restored catalog field names; its required hook and 164 tests in 16 named files passed, and independent both-parent review agreed on exact tree ac20767e5041. Final CI on 2eaaf24152f: 47 successful checks and 25 skipped, including static analysis/typecheck, all unit shards, mobile, packaging, layouts, SSH, cross-version compatibility, persistence, real WSL checks and CodeQL. Linux persistence passed one failed-only retry after an npm dependency download timed out in its fixed historical Bun fixture, before tests ran; successful jobs were preserved. The aggregate watch hit GitHub API TLS timeouts, so the remaining CodeQL run was awaited directly and passed.

Real QA: the prior accepted run on a3b635f14a41c8bc829e82a2557eaac71f9229ca covered genuine Windows Claude/Codex state created by a shipped baseline, its graceful upgrade, real replies, new guest chats, graceful guest restart, all original changed consumers, both UNC spellings, saved-owner preservation, terminal fallback, setup/CLI and authenticated paired boundaries. Original identities and settings survived; the unrelated idle distro stayed stopped. This evidence carries for unchanged flows across the subsequent main merges. On 471a901, the targeted audit run passed extended UNC Add for both shares with Linux case preserved, alternate-spelling identity reuse, linked-worktree reuse against the unchanged older guest, Windows-owned drive-folder Add, all-failed nested import, and useful Add error copy. Git Add opens the repo's default checkout, unchanged from main. Git Create under a drive-mount UNC parent exposed EPERM. The correction committed as 83ef724 passed its targeted real Windows rerun on final head ab664e4456e, ticket2666: one Create submission produced audit-drive-created-t2666, owned by Local Windows, with the original drive-mount UNC path retained. The physical Windows directory and .git exist; Git reports one parentless Initial commit and a clean working tree. The all-failed import real run showed no imported projects, a useful path-specific error and unchanged catalogs/groups. Its exact ordered-failure/zero-ensure, zero-RPC and zero-group contract is asserted by project-placement.test.ts:445–480; the coordinator accepted this combined evidence without a real rerun.

Known limits: uncertain group-create replies and simultaneous same-folder Add can still leave duplicate groups or projects; both are temporary and tracked in STA-12331. If the desktop’s saved distro list is out of date, re-adding a project can still race an earlier removal. Orca keeps the returned project and does not cancel a different owner’s pending removal. This temporary edge is also tracked in STA-12331. Mixed saved-Windows/new-WSL Group import refuses with import-separately guidance (#31417). New projects created on a distro’s server cannot be reached from phones yet (#28972, #33911); saved Windows-owned WSL projects remain reachable. With the rollout gates on, new WSL 1 folders are refused with guidance under the #33085 decision; saved projects continue to work. Inferred Clone remains Windows-owned. Broader alias discovery (STA-11388), expanded owner-create ordering (STA-11252) and the existing drive-route follow-up (#33090) are unchanged. Paired/unnamed callers reuse supported saved projects but cannot create desktop-private WSL owners.

Evidence limits: Add used the accepted one-call native-picker substitute; subsequent app actions completed through the real UI. OS picker interaction and physical drag/drop are not claimed as exercised. Folder-kind Create has no user entry point and has source-test coverage. The earlier authenticated paired run exercised real loopback handlers and verified catalogs/filesystem, without ensure-call instrumentation. The accepted a3 desktop used the explicitly accepted older official server payload, SHA256 b8f06708dd62bf8098d0c6793a31875bfd0b99dccccb4c9ef04ae5e538d487c2, preserving mixed-version evidence. The audit Add-error screenshot uses an explicitly accepted late-failure seam after real ensure/registration completed; it does not claim a naturally occurring transport failure. The wrappers were restored. The scan’s complete ordered IPC reply and process counters were not captured in the real run; the named source contract supplies those assertions. orcaqa launcher crashed mid-stop (factory fixed); stop not graceful, no row depends on it. The factory authorized ticket2570’s release and its next-launch cleanup owns the recorded leftovers. This adds no durability claim; the earlier accepted durability evidence carries. The final Git Create run used the same accepted one-call native-picker substitute, followed by the actual Create UI. Its native UI-stage receipt remained INCOMPLETE pending Git proof and guest comparison; the later independent filesystem/Git receipt supplied the former. The coordinator ruled the guest assertion not applicable because this is a Windows-owned project and the WSL host was disconnected by design. Supplemental saved-guest inspection is historical evidence, not a required live guest pass. The combined scoped result passed independent evidence review. Ticket2666 completed its stop through the factory route and supported descendant cleanup; all recorded app/helper identities and allocated listeners were absent, monitored config hashes were unchanged, and the unrelated idle distro stayed stopped. The slot was released and both owned terminals were closed.

For Brennan’s review — inspected screenshots:

Flow	Main/baseline	PR
Native Windows Claude
Native Windows Codex
UNC native-chat result		·
Both UNC Add spellings	baseline handler comparison; picker not exercised	·
Git Create
Folder/Open root	baseline handler comparison	·
Nested import		· ·
Selected guest Browse/Add	branch-only
Local-selected project setup		·
Guest graceful restart	branch-only	·
Implicit terminal fallback	branch-only
Paired refusal and gate exclusion	saved-project reuse compared on baseline	authenticated receipts and

Targeted audit screenshots (viewed after hash-verified retrieval):

Flow	PR result
Extended UNC Add	·
Linked checkout reuses the guest project
Windows-owned drive folder
All-failed nested import	·
Late Add failure, disclosed seam
Drive UNC Git Create	→

Review spots: Windows-owned Create filesystem access and nested import before provisioning. The source head is 2eaaf24152f; the final Git Create proof ran on ab664e4456e and carries across this reviewed main merge. Accepted QA carries across the main merge; the ordering correction is covered by tests under the coordinator ruling.

[coderabbitai]

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.

• Last reviewed commit: 73cd3a0
• Latest commit, not reviewed: 2eaaf24

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: Advanced
• Run ID: 3db4fae3-04ad-4f73-a9da-8734a0d132cf

📥 Commits

Reviewing files that changed from the base of the PR and between 15e7afa and 73cd3a0.

📒 Files selected for processing: 6

• src/cli/handlers/repo.ts
• src/renderer/src/components/new-workspace/SetProjectLocationDialog.test.tsx
• src/renderer/src/lib/agent-launch-caller-routing.test.ts
• src/renderer/src/lib/agent-launch-routing.test.ts
• src/renderer/src/lib/web-runtime-worktree-terminal-after-wake.ts
• src/renderer/src/store/project-groups/nested-repository-operations.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.

Walkthrough

The changes add WSL-host routing for repository registration, creation, existing-folder setup, and nested imports. Repository flows use returned execution-host IDs for readiness checks, worktree refreshes, and activation. Agent launch routing supports admission based on a verified workspace owner and reports whether fallback terminal creation opened an agent, shell, or no surface.

Priority: Normal

Merge Risk: Moderate · up to 73cd3

A structured agent launch that is declined can be reported as cancelled even though a terminal opens afterward. Running orca repo add . from a WSL share can time out during first-time distro setup. Fix both before merging; the PR is also still marked as a draft pending CI and Windows QA.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title clearly summarizes the primary change: routing new WSL projects to their distro server.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description is comprehensive and covers the required ELI5, What Changed, Why, maintainer issue exception, visual proof, testing evidence, AI boundary, known limits, and cross-platform consideratio…

Full details: Description check

Explanation

The description is comprehensive and covers the required ELI5, What Changed, Why, maintainer issue exception, visual proof, testing evidence, AI boundary, known limits, and cross-platform considerations. It does not include explicit Review or Checklist headings, but the missing sections are non-critical because the relevant review status, risks, and test checkboxes are documented elsewhere.

✨ Finishing Touches: 💡 2

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 6

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 199d61eb-743d-40b7-852d-abe02edea2f0

📥 Commits

Reviewing files that changed from the base of the PR and between 86ef00a and 8a96cbf.

📒 Files selected for processing: 74

• src/cli/handlers/repo.ts
• src/cli/index-project-setup.test.ts
• src/main/ipc/repos/local-repo-registration.ts
• src/main/ipc/repos/nested-repo-import-handler.ts
• src/main/ipc/repos/project-host-setup-handlers.ts
• src/main/ipc/repos/repo-clone-lifecycle.ts
• src/main/ipc/repos/repo-creation-handlers.ts
• src/main/ipc/wsl-host-handlers.ts
• src/main/runtime/rpc/methods/project-runtime-rpc-methods.ts
• src/main/runtime/rpc/methods/repo.ts
• src/main/runtime/runtime-nested-repo-import.ts
• src/main/runtime/runtime-project-host-setup-controller.ts
• src/main/runtime/runtime-repository-clone-controller.ts
• src/main/runtime/runtime-repository-registration-controller.ts
• src/main/runtime/runtime-store-contract.ts
• src/main/wsl/wsl-host-service-contract.ts
• src/main/wsl/wsl-host-service.test.ts
• src/main/wsl/wsl-host-service.ts
• src/main/wsl/wsl-nested-project-import.ts
• src/main/wsl/wsl-project-host-ensurer.ts
• src/main/wsl/wsl-project-host-setup.ts
• src/main/wsl/wsl-project-registration.test.ts
• src/main/wsl/wsl-project-registration.ts
• src/renderer/src/components/sidebar/AddProjectFromFolderDialog.tsx
• src/renderer/src/components/sidebar/AddRepoSteps.tsx
• src/renderer/src/components/sidebar/AddWslHostDialogBody.tsx
• src/renderer/src/components/sidebar/NonGitFolderDialog.tsx
• src/renderer/src/components/sidebar/add-repo-runtime-owner.ts
• src/renderer/src/components/sidebar/add-repo-store-upsert.ts
• src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts
• src/renderer/src/components/sidebar/useAddRepoCloneFlow.ts
• src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.ts
• src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.ts
• src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts
• src/renderer/src/components/sidebar/useAddRepoServerPathFlow.ts
• src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts
• src/renderer/src/components/sidebar/useCreateRepo.ts
• src/renderer/src/components/terminal/initial-terminal-admission-wait.test.tsx
• src/renderer/src/lib/agent-launch-caller-permissions.test.ts
• src/renderer/src/lib/agent-launch-caller-placement.test.ts
• src/renderer/src/lib/agent-launch-caller-prompt-transport.test.ts
• src/renderer/src/lib/agent-launch-caller-routing.test.ts
• src/renderer/src/lib/agent-launch-route-connection-fallback.test.ts
• src/renderer/src/lib/agent-launch-route-input.test.ts
• src/renderer/src/lib/agent-launch-route-input.ts
• src/renderer/src/lib/agent-launch-route-registered-agents.test.ts
• src/renderer/src/lib/agent-launch-routing.test.ts
• src/renderer/src/lib/agent-launch-routing.ts
• src/renderer/src/lib/empty-workspace-default-agent-chat.test.ts
• src/renderer/src/lib/empty-workspace-default-agent-chat.ts
• src/renderer/src/lib/launch-agent-in-new-tab-cwd.test.ts
• src/renderer/src/lib/launch-agent-in-new-tab-host-agents.test.ts
• src/renderer/src/lib/launch-agent-in-new-tab-host-agents.ts
• src/renderer/src/lib/launch-agent-in-new-tab-placement.test.ts
• src/renderer/src/lib/launch-agent-in-new-tab-structured-route.ts
• src/renderer/src/lib/launch-agent-in-new-tab-web-runtime.test.ts
• src/renderer/src/lib/launch-agent-in-new-tab.test.ts
• src/renderer/src/lib/launch-agent-in-new-tab.ts
• src/renderer/src/lib/launch-agent-structured-chat-guard.test.ts
• src/renderer/src/lib/launch-agent-web-host-tab.ts
• src/renderer/src/lib/structured-agent-session-launch-admission.test.ts
• src/renderer/src/lib/structured-agent-session-launch-admission.ts
• src/renderer/src/lib/web-runtime-worktree-terminal-after-wake.ts
• src/renderer/src/lib/worktree-activation-launch-awaiting-host.test.ts
• src/renderer/src/lib/worktree-creation-structured-session.ts
• src/renderer/src/store/project-groups/nested-repository-operations.ts
• src/renderer/src/store/projects/project-host-setup-actions.ts
• src/renderer/src/store/repos/repo-add-actions.ts
• src/renderer/src/store/repos/repo-owner-host-readiness.ts
• src/renderer/src/store/slices/repos-onboarding-folder-startup.test.ts
• src/renderer/src/store/slices/repos-project-groups.test.ts
• src/renderer/src/store/slices/repos-selected-owner-routing.test.ts
• src/shared/project-group-types.ts
• src/shared/structured-native-chat-launch-route.ts

💤 Files with no reviewable changes: 1

• src/renderer/src/lib/launch-agent-in-new-tab-host-agents.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.