feat(server): configure worktree directory

[mamoreau-devolutions]

New worktrees can now be created under a configurable environment-level directory instead of only the default T3 home location.

Adds the General settings field, resolves configured paths when creating worktrees, and preserves recognition of both configured and historical default roots for review and project scanning.

Validated with focused worktree-directory, settings, review, scanner, and Git worktree tests.

Model: GPT-5.6 Terra
Harness: GitHub Copilot CLI

Summary by CodeRabbit

• New Features

  • Added a server-level Worktrees directory setting for choosing where new Git worktrees are created.
  • Supports custom paths, home-directory shortcuts, and restoring the default environment data directory.
  • The setting is searchable and can be edited or reset from General settings.

• Bug Fixes

  • Existing and newly configured worktrees are recognized consistently when scanning projects, reviewing changes, and validating worktree paths.
  • Preserved access to worktrees created under the previous default location.

• Documentation

  • Updated project settings documentation to describe worktree location configuration and related settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 1b75b54f-8c38-429c-b898-f1b05d5c482e

📥 Commits

Reviewing files that changed from the base of the PR and between 8c18b5b and eff6291.

📒 Files selected for processing (13)

• apps/server/src/project/AgentSessionScanner.test.ts
• apps/server/src/project/AgentSessionScanner.ts
• apps/server/src/review/ReviewService.test.ts
• apps/server/src/review/ReviewService.ts
• apps/server/src/vcs/GitVcsDriverCore.test.ts
• apps/server/src/vcs/GitVcsDriverCore.ts
• apps/server/src/worktreesDirectory.test.ts
• apps/server/src/worktreesDirectory.ts
• apps/web/src/components/settings/SettingsPanels.tsx
• apps/web/src/components/settings/settingsSearch.ts
• docs/user/project-settings.md
• packages/contracts/src/settings.test.ts
• packages/contracts/src/settings.ts

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

---

📝 Walkthrough

Walkthrough

Changes

Configurable worktree directories

Layer / File(s)	Summary
Settings contract and path resolution packages/contracts/src/settings.ts, packages/contracts/src/settings.test.ts, apps/server/src/worktreesDirectory.ts, apps/server/src/worktreesDirectory.test.ts	Adds the machine-local worktreesDirectory setting. Empty values use the default root. Configured paths support trimming and ~ expansion. Both configured and previous default roots remain managed when they differ.
Settings UI and documentation apps/web/src/components/settings/SettingsPanels.tsx, apps/web/src/components/settings/settingsSearch.ts, docs/user/project-settings.md	Adds the server-scoped setting, search entry, mixed-state handling, reset behavior, and documentation.
Configured worktree creation apps/server/src/vcs/GitVcsDriverCore.ts, apps/server/src/vcs/GitVcsDriverCore.test.ts	Uses the configured directory for worktrees created without an explicit path. Explicit paths remain unchanged.
Managed-root validation apps/server/src/review/ReviewService.ts, apps/server/src/review/ReviewService.test.ts	Allows diff-preview working directories inside the configured root and the previous default root.
Managed-root session scanning apps/server/src/project/AgentSessionScanner.ts, apps/server/src/project/AgentSessionScanner.test.ts	Excludes scanned sessions under any managed worktrees root for recorded and realpath-resolved paths.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant SettingsPanel
  participant ServerSettingsService
  participant GitVcsDriverCore
  SettingsPanel->>ServerSettingsService: save worktreesDirectory
  GitVcsDriverCore->>ServerSettingsService: getSettings
  ServerSettingsService-->>GitVcsDriverCore: configured directory
  GitVcsDriverCore->>GitVcsDriverCore: resolve worktree path
  GitVcsDriverCore->>GitVcsDriverCore: create worktree

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to eff62

The configurable worktree directory is wired through creation, managed-root validation, scanning, settings, and focused tests without an identified merge-blocking issue.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description summarizes the main change and validation, but it does not use the required sections or include the required checklist. It also changes the UI without providing before/after screenshot…	Add the required What Changed, Why, UI Changes, and Checklist sections. Include before/after screenshots for the new Worktrees directory setting, and complete the checklist items.
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 12 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: configuring the server worktree directory.
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.

Full details: Description check

Explanation

The description summarizes the main change and validation, but it does not use the required sections or include the required checklist. It also changes the UI without providing before/after screenshots.

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 12 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[juliusmarminge]

Note

This comment is posted by Julius' dot

The new General settings field has no before/after UI evidence attached. The verification rule requires it. Please show the environment-scoped directory setting, including saving and resetting it, and report the observed worktree location after each change, then request reconsideration.