feat: support nested child repos in pane worktrees

Projects can contain child repos under the root repo. This adds pane-level support for selecting those child repos and carrying them through the same worktree lifecycle as the root repo, so create, reopen, resume, bootstrap, and cleanup keep the pane's related repos together.

Constraint: Preserve existing root-only behavior and keep child repo paths project-scoped and relative

Rejected: Treating child repos as separate panes | one task should keep root and child repo changes in the same pane lifecycle

Confidence: high

Scope-risk: moderate

Directive: Keep root and nested child repo lifecycle behavior aligned when changing pane creation, reopen/resume, bootstrap, or cleanup

Tested: pnpm run typecheck; pnpm vitest run __tests__/linkedRepoConfig.test.ts __tests__/worktreeMetadata.test.ts __tests__/reopenWorktree.test.ts __tests__/resumeBranches.test.ts __tests__/worktreeCleanupService.test.ts __tests__/integration/paneLifecycle.test.ts; pnpm vitest run

Author: xiao-do-do

__tests__/integration/paneLifecycle.test.ts

@@ -300,6 +300,7 @@ describe('Pane Lifecycle Integration Tests', () => {
           agent: 'claude',
           projectName: 'test-project',
           existingPanes: [],
+          slugBase: 'add-user',
         },
         ['claude']
       );
@@ -318,6 +319,60 @@ describe('Pane Lifecycle Integration Tests', () => {
       )).toBe(false);
     });
 
+    it('passes configured linked child repos into the pane bootstrap config', async () => {
+      fsMock.readFileSync.mockImplementation((target) => {
+        const value = String(target);
+        if (value.endsWith('/.dmux/settings.json')) {
+          return JSON.stringify({ linkedRepoPaths: 'packages/docs\nservices/api' });
+        }
+        if (value.endsWith('/.dmux/dmux.config.json')) {
+          return JSON.stringify({ controlPaneId: '%0' });
+        }
+        return JSON.stringify({});
+      });
+
+      const { createPane } = await import('../../src/utils/paneCreation.js');
+
+      await createPane(
+        {
+          prompt: 'open linked workspace',
+          agent: 'claude',
+          projectName: 'test-project',
+          existingPanes: [],
+          slugBase: 'linked-workspace',
+        },
+        ['claude']
+      );
+
+      const bootstrapConfig = getLatestBootstrapConfig();
+      expect(bootstrapConfig.metadata.linkedRepoPaths).toEqual([
+        'packages/docs',
+        'services/api',
+      ]);
+    });
+
+    it('passes explicit linked child repo selections into the pane bootstrap config', async () => {
+      const { createPane } = await import('../../src/utils/paneCreation.js');
+
+      await createPane(
+        {
+          prompt: 'open selected linked repos',
+          agent: 'claude',
+          projectName: 'test-project',
+          existingPanes: [],
+          slugBase: 'linked-selection',
+          linkedRepoPaths: ['external/infinite-canvas-web', 'backend/docs-ui'],
+        },
+        ['claude']
+      );
+
+      const bootstrapConfig = getLatestBootstrapConfig();
+      expect(bootstrapConfig.metadata.linkedRepoPaths).toEqual([
+        'external/infinite-canvas-web',
+        'backend/docs-ui',
+      ]);
+    });
+
     it('passes remote tracking baseBranch values to bootstrap without forcing refs/heads', async () => {
       fsMock.readFileSync.mockImplementation((target) => {
         const value = String(target);

__tests__/linkedRepoConfig.test.ts

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  discoverLinkedRepoPaths,
+  parseLinkedRepoPathsInput,
+  resolveLinkedRepoReferences,
+  validateLinkedRepoPathsSetting,
+} from '../src/utils/linkedRepoConfig.js';
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const tempDir = tempDirs.pop();
+    if (tempDir) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+});
+
+describe('linkedRepoConfig', () => {
+  it('parses newline and comma separated repo paths into a deduped list', () => {
+    expect(parseLinkedRepoPathsInput('packages/docs, services/api\npackages/docs')).toEqual([
+      'packages/docs',
+      'services/api',
+    ]);
+  });
+
+  it('rejects linked repo paths that escape the project root', () => {
+    expect(() => validateLinkedRepoPathsSetting('../outside')).toThrow(
+      'cannot escape the project root'
+    );
+  });
+
+  it('resolves configured child repositories relative to the project root', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'dmux-linked-repos-'));
+    tempDirs.push(projectRoot);
+
+    const childRepo = path.join(projectRoot, 'packages', 'docs');
+    fs.mkdirSync(path.join(childRepo, '.git'), { recursive: true });
+
+    expect(resolveLinkedRepoReferences(projectRoot, 'packages/docs')).toEqual([
+      {
+        relativePath: 'packages/docs',
+        repoPath: childRepo,
+      },
+    ]);
+  });
+
+  it('discovers nested child repositories while skipping generated directories', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'dmux-linked-repo-discovery-'));
+    tempDirs.push(projectRoot);
+
+    const childRepo = path.join(projectRoot, 'external', 'infinite-canvas-web');
+    const nestedRepo = path.join(projectRoot, 'tools', 'workspace-helper');
+    const ignoredRepo = path.join(projectRoot, 'node_modules', 'ignored-package');
+
+    fs.mkdirSync(path.join(childRepo, '.git'), { recursive: true });
+    fs.mkdirSync(path.join(nestedRepo, '.git'), { recursive: true });
+    fs.mkdirSync(path.join(ignoredRepo, '.git'), { recursive: true });
+
+    expect(discoverLinkedRepoPaths(projectRoot)).toEqual([
+      'external/infinite-canvas-web',
+      'tools/workspace-helper',
+    ]);
+  });
+});

__tests__/newPaneFieldNavigation.test.ts

@@ -16,4 +16,11 @@ describe('new pane field navigation', () => {
     expect(getPreviousNewPaneField('branchName')).toBe('baseBranch');
     expect(getPreviousNewPaneField('baseBranch')).toBe('prompt');
   });
+
+  it('includes linked repo selection in the cycle when child repos are available', () => {
+    expect(getNextNewPaneField('branchName', { hasLinkedRepos: true })).toBe('linkedRepos');
+    expect(getNextNewPaneField('linkedRepos', { hasLinkedRepos: true })).toBe('prompt');
+    expect(getPreviousNewPaneField('prompt', { hasLinkedRepos: true })).toBe('linkedRepos');
+    expect(getPreviousNewPaneField('linkedRepos', { hasLinkedRepos: true })).toBe('branchName');
+  });
 });

__tests__/popupManager.newPanePopup.test.ts

@@ -126,6 +126,25 @@ describe('PopupManager launchNewPanePopup', () => {
     });
   });
 
+  it('normalizes linked child repo selections from popup payloads', async () => {
+    const manager = createPopupManager({ promptForGitOptionsOnCreate: true }) as any;
+    manager.checkPopupSupport = vi.fn(() => true);
+    manager.launchPopup = vi.fn().mockResolvedValue({
+      success: true,
+      data: {
+        prompt: 'prompt',
+        linkedRepoPaths: [' external/web ', 'packages/docs', 'external/web'],
+      },
+    });
+
+    const result = await manager.launchNewPanePopup('/tmp/project');
+
+    expect(result).toEqual({
+      prompt: 'prompt',
+      linkedRepoPaths: ['external/web', 'packages/docs'],
+    });
+  });
+
   it('returns null for malformed popup payloads', async () => {
     const manager = createPopupManager({ promptForGitOptionsOnCreate: true }) as any;
     manager.checkPopupSupport = vi.fn(() => true);

__tests__/reopenWorktree.test.ts

@@ -22,6 +22,9 @@ const recalculateAndApplyLayoutMock = vi.hoisted(() => vi.fn(async () => {}));
 const getInstalledAgentsMock = vi.hoisted(() => vi.fn(async () => ['claude', 'codex']));
 const filterEnabledAgentsMock = vi.hoisted(() => vi.fn((agents: string[]) => agents));
 const destroyWelcomePaneCoordinatedMock = vi.hoisted(() => vi.fn());
+const ensureWorkspaceWorktreesMock = vi.hoisted(() => vi.fn(async () => []));
+const getConfiguredLinkedRepoPathsMock = vi.hoisted(() => vi.fn(() => []));
+const writeWorktreeMetadataMock = vi.hoisted(() => vi.fn());
 const readWorktreeMetadataMock = vi.hoisted(() => vi.fn(() => ({
   agent: 'codex',
   permissionMode: 'bypassPermissions',
@@ -74,6 +77,12 @@ vi.mock('../src/utils/agentDetection.js', () => ({
 
 vi.mock('../src/utils/worktreeMetadata.js', () => ({
   readWorktreeMetadata: readWorktreeMetadataMock,
+  writeWorktreeMetadata: writeWorktreeMetadataMock,
+}));
+
+vi.mock('../src/utils/linkedWorktrees.js', () => ({
+  ensureWorkspaceWorktrees: ensureWorkspaceWorktreesMock,
+  getConfiguredLinkedRepoPaths: getConfiguredLinkedRepoPathsMock,
 }));
 
 vi.mock('../src/utils/paneTitle.js', () => ({
@@ -105,6 +114,56 @@ describe('reopenWorktree', () => {
       permissionMode: 'bypassPermissions',
       branchName: 'feature/reopen-me',
     });
+    ensureWorkspaceWorktreesMock.mockResolvedValue([]);
+    getConfiguredLinkedRepoPathsMock.mockReturnValue([]);
+  });
+
+  it('ensures linked child worktrees before resuming an existing pane', async () => {
+    readWorktreeMetadataMock.mockReturnValue({
+      agent: 'codex',
+      permissionMode: 'bypassPermissions',
+      branchName: 'feature/reopen-me',
+      linkedRepoPaths: ['packages/docs'],
+    });
+    ensureWorkspaceWorktreesMock.mockResolvedValue([
+      {
+        isRoot: true,
+        repoPath: '/repo',
+        relativePath: '',
+        worktreePath: '/repo/.dmux/worktrees/reopen-me',
+        createdWorktree: false,
+      },
+      {
+        isRoot: false,
+        repoPath: '/repo/packages/docs',
+        relativePath: 'packages/docs',
+        worktreePath: '/repo/.dmux/worktrees/reopen-me/packages/docs',
+        createdWorktree: true,
+      },
+    ]);
+
+    const { reopenWorktree } = await import('../src/utils/reopenWorktree.js');
+
+    await reopenWorktree({
+      slug: 'reopen-me',
+      worktreePath: '/repo/.dmux/worktrees/reopen-me',
+      projectRoot: '/repo',
+      existingPanes: [],
+      sessionProjectRoot: '/repo',
+      sessionConfigPath: '/repo/.dmux/dmux.config.json',
+    });
+
+    expect(ensureWorkspaceWorktreesMock).toHaveBeenCalledWith({
+      projectRoot: '/repo',
+      rootWorktreePath: '/repo/.dmux/worktrees/reopen-me',
+      branchName: 'feature/reopen-me',
+      linkedRepoPaths: ['packages/docs'],
+      fallbackStartPointMode: 'current-head',
+    });
+    expect(writeWorktreeMetadataMock).toHaveBeenCalledWith(
+      '/repo/.dmux/worktrees/reopen-me/packages/docs',
+      { branchName: 'feature/reopen-me' }
+    );
   });
 
   it('uses stored agent metadata and permission mode for resume', async () => {

__tests__/resumeBranches.test.ts

@@ -30,6 +30,7 @@ vi.mock('../src/utils/settingsManager.js', () => ({
   SettingsManager: vi.fn(() => ({
     getSettings: vi.fn(() => ({
       permissionMode: 'plan',
+      linkedRepoPaths: 'child-repo',
     })),
   })),
 }));
@@ -421,6 +422,7 @@ describe('resumeBranches', () => {
       expect.objectContaining({
         agent: 'codex',
         permissionMode: 'plan',
+        linkedRepoPaths: ['child-repo'],
         branchName: 'feature/remote-shared',
       })
     );

__tests__/worktreeMetadata.test.ts

@@ -28,6 +28,7 @@ describe('worktree metadata persistence', () => {
       permissionMode: 'bypassPermissions',
       displayName: 'Review Queue',
       branchName: 'feat/child-worktree',
+      linkedRepoPaths: ['packages/design-system', 'services/api'],
       mergeTargetChain: [
         {
           displayName: 'Feature Parent',
@@ -48,6 +49,7 @@ describe('worktree metadata persistence', () => {
       permissionMode: 'bypassPermissions',
       displayName: 'Review Queue',
       branchName: 'feat/child-worktree',
+      linkedRepoPaths: ['packages/design-system', 'services/api'],
       mergeTargetChain: [
         {
           displayName: 'Feature Parent',
@@ -63,4 +65,17 @@ describe('worktree metadata persistence', () => {
       ],
     });
   });
+
+  it('preserves an explicit empty linked repo selection so reopen does not fall back to project defaults', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dmux-worktree-meta-empty-'));
+    tempDirs.push(tempDir);
+
+    writeWorktreeMetadata(tempDir, {
+      linkedRepoPaths: [],
+    });
+
+    expect(readWorktreeMetadata(tempDir)).toEqual({
+      linkedRepoPaths: [],
+    });
+  });
 });

src/components/popups/newPaneFieldNavigation.ts

@@ -4,16 +4,36 @@
  * Specifically, the 'prompt' -> 'base branch' -> 'new branch name' cycle.
  */
 
-export type NewPaneField = 'prompt' | 'baseBranch' | 'branchName';
+export type NewPaneField = 'prompt' | 'baseBranch' | 'branchName' | 'linkedRepos';
 
-export function getNextNewPaneField(current: NewPaneField): NewPaneField {
-  if (current === 'prompt') return 'baseBranch';
-  if (current === 'baseBranch') return 'branchName';
-  return 'prompt';
+function getFieldOrder(hasLinkedRepos: boolean): NewPaneField[] {
+  return hasLinkedRepos
+    ? ['prompt', 'baseBranch', 'branchName', 'linkedRepos']
+    : ['prompt', 'baseBranch', 'branchName'];
 }
 
-export function getPreviousNewPaneField(current: NewPaneField): NewPaneField {
-  if (current === 'prompt') return 'branchName';
-  if (current === 'baseBranch') return 'prompt';
-  return 'baseBranch';
+export function getNextNewPaneField(
+  current: NewPaneField,
+  options: { hasLinkedRepos?: boolean } = {}
+): NewPaneField {
+  const order = getFieldOrder(options.hasLinkedRepos ?? false);
+  const currentIndex = order.indexOf(current);
+  if (currentIndex === -1) {
+    return order[0];
+  }
+
+  return order[(currentIndex + 1) % order.length];
+}
+
+export function getPreviousNewPaneField(
+  current: NewPaneField,
+  options: { hasLinkedRepos?: boolean } = {}
+): NewPaneField {
+  const order = getFieldOrder(options.hasLinkedRepos ?? false);
+  const currentIndex = order.indexOf(current);
+  if (currentIndex === -1) {
+    return order[0];
+  }
+
+  return order[(currentIndex - 1 + order.length) % order.length];
 }