feat: support worktrees in multi-repository project folders

apps/mobile/src/features/review/ReviewSheet.tsx

@@ -36,7 +36,7 @@ import {
   useAdaptiveWorkspaceLayout,
   useWorkspacePaneState,
 } from "../layout/AdaptiveWorkspaceLayout";
-import { useSelectedThreadWorktree } from "../../state/use-selected-thread-worktree";
+import { useSelectedThreadSourceControl } from "../../state/use-selected-thread-worktree";
 import { useReviewCacheForThread } from "./reviewState";
 import {
   isNativeReviewDiffDrawEvent,
@@ -354,7 +354,7 @@ export function ReviewSheet(props: ReviewSheetProps) {
   const isEnvironmentReady = environment.presentation?.connection.phase === "connected";
   const { draftMessage, draftContext } = useThreadDraftForThread({ environmentId, threadId });
   const reviewCache = useReviewCacheForThread({ environmentId, threadId });
-  const { selectedThreadCwd } = useSelectedThreadWorktree();
+  const { sourceControlCwd: selectedThreadCwd } = useSelectedThreadSourceControl();
   const topContentInset = useContentTopInset();
   const bottomContentInset = useSheetContentBottomInset();
 

apps/mobile/src/features/review/useReviewSections.ts

@@ -12,7 +12,7 @@ import { lastReviewGitSectionsAtom, reviewEnvironment } from "../../state/review
 import { lastReviewTurnDiffsAtom } from "../../state/reviewTurnDiffs";
 import { environmentSession } from "../../state/session";
 import { useSelectedThreadProjection } from "../../state/use-thread-detail";
-import { useSelectedThreadWorktree } from "../../state/use-selected-thread-worktree";
+import { useSelectedThreadSourceControl } from "../../state/use-selected-thread-worktree";
 import {
   buildReviewSectionItems,
   getReadyReviewCheckpoints,
@@ -52,7 +52,11 @@ export function useReviewSections(input: {
   });
   const { canReadFiles } = fileAccess;
   const selectedThread = useSelectedThreadProjection();
-  const { selectedThreadCwd } = useSelectedThreadWorktree();
+  // Changes come from the repository worktree chosen for Git; turn diffs cover all of them.
+  const { sourceControlCwd: selectedThreadCwd, repoWorktree } = useSelectedThreadSourceControl();
+  // Review comments carry the section title, so it names the repository their paths belong to.
+  const gitSectionSuffix =
+    repoWorktree === null ? "" : ` in ${repoWorktree.repository} · ${repoWorktree.branch}`;
   const diffPreview = useEnvironmentQuery(
     canReadFiles && enabled && environmentId !== undefined && selectedThreadCwd !== null
       ? reviewEnvironment.diffPreview({
@@ -81,10 +85,17 @@ export function useReviewSections(input: {
   );
   // Turns show their last answered diff; the active turn's live query below overrides it.
   // Section ids and the selection do not depend on the live query, so they are resolved first.
+  const gitSections =
+    canReadFiles || fileAccess.isPending ? (diffPreview.data?.sources ?? lastGitSections) : [];
   const cachedSections = buildReviewSectionItems({
     checkpoints: readyCheckpoints,
     gitSections:
-      canReadFiles || fileAccess.isPending ? (diffPreview.data?.sources ?? lastGitSections) : [],
+      gitSectionSuffix === ""
+        ? gitSections
+        : gitSections.map((section) => ({
+            ...section,
+            title: `${section.title}${gitSectionSuffix}`,
+          })),
     turnDiffById: reviewTurnDiffsBySectionId(readyCheckpoints, lastTurnDiffs),
     loadingGitSections: fileAccess.isPending || diffPreview.isPending,
   });

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

@@ -24,6 +24,7 @@ import {
 import { SettingsScreen } from "./components/SettingsScreen";
 import { useSettingsEnvironmentMenu } from "./components/SettingsEnvironmentFilterHeader";
 import { BranchNamingSettings } from "./components/BranchNamingSettings";
+import { RepoWorktreeSettings } from "./components/RepoWorktreeSettings";
 import { DatabaseStorageNotice } from "./components/DatabaseStorageNotice";
 import { ListChoiceRow as SettingsChoiceRow } from "../../components/ui/ListChoiceRow";
 import { SettingsSection } from "./components/SettingsSection";
@@ -67,6 +68,8 @@ const PAGE_PROJECT_KEYS: Record<SettingsPage, readonly ProjectScopedServerSettin
   "source-control": ["defaultAutoPull", "removeAgentCreditsOnMerge"],
   worktrees: [
     "newWorktreesStartFromOrigin",
+    "repoWorktrees",
+    "repoWorktreeInstructions",
     "worktreeSubmodules",
     "branchNamingMode",
     "branchNamePrefix",
@@ -486,6 +489,17 @@ function ServerSettingsDetail(props: { readonly page: SettingsPage }) {
                     disabled={disabledFor("newWorktreesStartFromOrigin")}
                     onValueChange={(value) => write({ newWorktreesStartFromOrigin: value })}
                   />
+                  <RepoWorktreeSettings
+                    key={targetsKey}
+                    enabled={uniform("repoWorktrees")}
+                    instructions={uniform("repoWorktreeInstructions")}
+                    disabled={{
+                      enabled: disabledFor("repoWorktrees"),
+                      instructions: disabledFor("repoWorktreeInstructions"),
+                    }}
+                    projectSelected={projectSelected}
+                    onChange={write}
+                  />
                 </SettingsSection>
                 <SettingsSection
                   title="Worktree submodules"

apps/mobile/src/features/settings/components/RepoWorktreeSettings.tsx

@@ -0,0 +1,79 @@
+import type { ServerSettingsPatch } from "@t3tools/contracts";
+import { useRef } from "react";
+import { View } from "react-native";
+
+import { AppText as Text, AppTextInput } from "../../../components/ui/AppText";
+import { SettingsSwitchRow } from "./SettingsSwitchRow";
+
+const GUIDANCE_HELP =
+  "Instructions for agents working in these repositories, such as base branches and submodule rules.";
+
+/** Rows inside an existing section. The first draws a top border, so another row must precede it. */
+export function RepoWorktreeSettings(props: {
+  enabled: boolean | null;
+  instructions: string | null;
+  /** Each setting can be managed by policy on its own. */
+  disabled: { readonly enabled: boolean; readonly instructions: boolean };
+  projectSelected: boolean;
+  onChange: (patch: ServerSettingsPatch) => void;
+}) {
+  const instructionsEdited = useRef(false);
+  return (
+    <>
+      <View className="border-t border-border-subtle">
+        <SettingsSwitchRow
+          icon="folder"
+          label="Multi-Repository Project Folder"
+          subtitle={
+            props.projectSelected
+              ? "Create or reuse separate worktrees for the Git repositories inside this project folder as needed."
+              : "Create or reuse separate worktrees for the Git repositories inside each project folder as needed. Projects can override it."
+          }
+          value={props.enabled}
+          disabled={props.disabled.enabled}
+          onValueChange={(value) => props.onChange({ repoWorktrees: value })}
+        />
+      </View>
+      {props.enabled !== false ? (
+        <View className="gap-2 border-t border-border-subtle px-4 py-3">
+          <View className="gap-1">
+            <Text textRole="body" className="text-foreground">
+              Repository Guidance
+            </Text>
+            <Text textRole="footnote" className="text-foreground-muted">
+              {GUIDANCE_HELP}
+            </Text>
+          </View>
+          <AppTextInput
+            key={props.instructions}
+            accessibilityLabel="Repository Guidance"
+            accessibilityHint={GUIDANCE_HELP}
+            onChangeText={() => {
+              instructionsEdited.current = true;
+            }}
+            defaultValue={props.instructions ?? ""}
+            placeholder={
+              props.instructions === null
+                ? "Mixed. Enter guidance for all selected targets."
+                : "Start api work from develop. Start shared/framework work from team-develop."
+            }
+            editable={!props.disabled.instructions}
+            multiline
+            autoCapitalize="sentences"
+            className="min-h-24 rounded-xl px-3 py-2 text-base text-foreground"
+            onEndEditing={(event) => {
+              const value = event.nativeEvent.text.trim();
+              if (
+                !props.disabled.instructions &&
+                instructionsEdited.current &&
+                (props.instructions === null || value !== props.instructions)
+              )
+                props.onChange({ repoWorktreeInstructions: value });
+              instructionsEdited.current = false;
+            }}
+          />
+        </View>
+      ) : null}
+    </>
+  );
+}

apps/mobile/src/features/settings/settings-search.ts

@@ -104,6 +104,8 @@ const SETTINGS_SEARCH_TERMS = {
     "branch prefix",
     "submodules",
     "start from remote",
+    "multi-repository project folder",
+    "repository guidance",
   ],
   SettingsLabs: [
     "beta",

apps/mobile/src/features/threads/ThreadRouteScreen.tsx

@@ -88,7 +88,10 @@ import { useAtomCommand } from "../../state/use-atom-command";
 import { useSelectedThreadGitActions } from "../../state/use-selected-thread-git-actions";
 import { useSelectedThreadGitState } from "../../state/use-selected-thread-git-state";
 import { useSelectedThreadRequests } from "../../state/use-selected-thread-requests";
-import { useSelectedThreadWorktree } from "../../state/use-selected-thread-worktree";
+import {
+  useSelectedThreadSourceControl,
+  useSelectedThreadWorktree,
+} from "../../state/use-selected-thread-worktree";
 import { useThreadComposerState } from "../../state/use-thread-composer-state";
 import { resolveMergeBackTargetThreadId } from "@t3tools/client-runtime/state/thread-relationships";
 import { resolveLatestMergeBackRun } from "@t3tools/client-runtime/state/thread-workflows";
@@ -538,11 +541,13 @@ function ThreadRouteContent(
   ]
     .filter(Boolean)
     .join(" · ");
+  // The Git menu follows the repository chosen for Git; files and terminals stay in the workspace.
+  const { sourceControlCwd } = useSelectedThreadSourceControl();
   const gitStatus = useEnvironmentQuery(
-    selectedThread !== null && selectedThreadCwd !== null
+    selectedThread !== null && sourceControlCwd !== null
       ? vcsEnvironment.status({
           environmentId: selectedThread.environmentId,
-          input: { cwd: selectedThreadCwd },
+          input: { cwd: sourceControlCwd },
         })
       : null,
   );
@@ -564,7 +569,7 @@ function ThreadRouteContent(
 
   const gitActionProgressTarget = {
     environmentId: selectedThread?.environmentId ?? null,
-    cwd: selectedThreadCwd,
+    cwd: sourceControlCwd,
   };
   const gitActionProgress = useGitActionProgress(gitActionProgressTarget);
 

apps/mobile/src/features/threads/git/GitCommitSheet.tsx

@@ -13,7 +13,7 @@ import { useEnvironmentQuery } from "../../../state/query";
 import { useThreadSelection } from "../../../state/use-thread-selection";
 import { useSelectedThreadGitActions } from "../../../state/use-selected-thread-git-actions";
 import { useSelectedThreadGitState } from "../../../state/use-selected-thread-git-state";
-import { useSelectedThreadWorktree } from "../../../state/use-selected-thread-worktree";
+import { useSelectedThreadSourceControl } from "../../../state/use-selected-thread-worktree";
 import { vcsEnvironment } from "../../../state/vcs";
 
 type GitCommitSheetProps = StaticScreenProps<{
@@ -24,10 +24,12 @@ type GitCommitSheetProps = StaticScreenProps<{
 export function GitCommitSheet(_props: GitCommitSheetProps) {
   const navigation = useNavigation();
   const { selectedThread } = useThreadSelection();
-  const { selectedThreadCwd } = useSelectedThreadWorktree();
+  const { sourceControlCwd: selectedThreadCwd, repoWorktree } = useSelectedThreadSourceControl();
   const gitState = useSelectedThreadGitState();
   const gitActions = useSelectedThreadGitActions();
   const { canWriteSourceControl, canChangeThreadBranch } = gitActions;
+  // A repository worktree's new branch is not the thread's, so it needs only source control.
+  const canCreateFeatureBranch = repoWorktree === null ? canChangeThreadBranch : true;
 
   const gitStatus = useEnvironmentQuery(
     selectedThread !== null && selectedThreadCwd !== null
@@ -52,7 +54,7 @@ export function GitCommitSheet(_props: GitCommitSheetProps) {
   const selectedDeletions = selectedFiles.reduce((sum, file) => sum + file.deletions, 0);
 
   const runCommitAction = async (featureBranch: boolean) => {
-    if (!canWriteSourceControl || (featureBranch && !canChangeThreadBranch)) return;
+    if (!canWriteSourceControl || (featureBranch && !canCreateFeatureBranch)) return;
     const commitMessage = dialogCommitMessage.trim();
     navigation.goBack();
     await gitActions.onRunSelectedThreadGitAction({
@@ -202,7 +204,7 @@ export function GitCommitSheet(_props: GitCommitSheetProps) {
           icon="arrow.branch"
           tone="text"
           fullWidth
-          disabled={!canWriteSourceControl || !canChangeThreadBranch || noneSelected || busy}
+          disabled={!canWriteSourceControl || !canCreateFeatureBranch || noneSelected || busy}
           onPress={() => void runCommitAction(true)}
         />
       </View>

apps/mobile/src/features/threads/git/GitConfirmSheet.tsx

@@ -12,6 +12,7 @@ import { FitSheet } from "../../../components/ui/FitSheet";
 import { SheetIntro } from "../../../components/ui/SheetIntro";
 import { useSelectedThreadGitActions } from "../../../state/use-selected-thread-git-actions";
 import { useSelectedThreadGitState } from "../../../state/use-selected-thread-git-state";
+import { useSelectedThreadSourceControl } from "../../../state/use-selected-thread-worktree";
 import { useThreadSelection } from "../../../state/use-thread-selection";
 import { SheetActionButton } from "./gitSheetComponents";
 
@@ -30,6 +31,7 @@ export function GitConfirmSheet(props: GitConfirmSheetProps) {
   const gitState = useSelectedThreadGitState();
   const gitActions = useSelectedThreadGitActions();
   const { canWriteSourceControl, canChangeThreadBranch } = gitActions;
+  const { repoWorktree } = useSelectedThreadSourceControl();
   const { selectedThreadProject } = useThreadSelection();
   const terminology = sourceControlClients.get(
     selectedThreadProject?.repositoryIdentity?.provider,
@@ -85,24 +87,28 @@ export function GitConfirmSheet(props: GitConfirmSheetProps) {
       return;
     }
 
+    // The new branch goes where the action runs, which may be a repository worktree.
     const branches =
-      gitState.selectedThreadBranches.length > 0
+      repoWorktree === null && gitState.selectedThreadBranches.length > 0
         ? gitState.selectedThreadBranches
-        : await gitActions.refreshSelectedThreadBranches();
+        : await gitActions.refreshSelectedThreadBranches({ sourceControl: true });
     if (branches === null) return;
     const newBranchName = resolveAutoFeatureBranchName(
       Arr.filterMap(branches, (branch) =>
         branch.isRemote ? Result.failVoid : Result.succeed(branch.name),
       ),
     );
-    const created = await gitActions.onCreateSelectedThreadBranch(newBranchName);
+    const created = await gitActions.onCreateSelectedThreadBranch(newBranchName, {
+      sourceControl: true,
+    });
     if (created === null) return;
     await gitActions.onRunSelectedThreadGitAction({ action: confirmAction });
   }, [
     canChangeThreadBranch,
     confirmAction,
     gitActions,
     gitState.selectedThreadBranches,
+    repoWorktree,
     includesCommit,
     params,
     navigation,