Import existing Git worktrees when adding a project

[germanescobar]

Problem

When a Git repository is added as a Controller project, Controller registers only the main checkout. Existing linked worktrees reported by git worktree list are ignored.

For example, a repository may already have five active worktrees created through Git, another worktree manager, or an earlier development workflow. After adding the repository to Controller, none of those worktrees appear in the sidebar. The user must recreate them or manually modify Controller's worktrees.json registry.

This is a normal project-onboarding scenario, distinct from recovering Controller registry data after corruption or accidental loss.

Expected behavior

When adding a project that already has linked Git worktrees, Controller should detect them and offer to import all or selected worktrees.

Importing should register the existing worktree in Controller without:

• Running git worktree add.
• Moving or recreating its directory.
• Changing its branch or HEAD.
• Discarding uncommitted changes.
• Deleting or otherwise taking ownership of files during import.

After import, the worktree should appear in the project sidebar and support Controller sessions, terminals, scripts, and normal worktree management.

Proposed UX

After adding a project:

1. Run git worktree list --porcelain from the project repository.
2. Exclude the main checkout and worktrees already registered with Controller.
3. If unregistered worktrees exist, show an import step listing each worktree's:
   • Path
   • Branch or detached HEAD
   • Current commit
   • Working-tree status, if useful
4. Allow the user to import all or select individual worktrees.
5. Clearly explain that importing registers the existing worktree; it does not copy or recreate it.

The worktree menu should also expose an Import existing worktrees action so discovery can be run later.

A matching CLI surface would be useful for agent workflows, for example:

controller worktrees import [<project>] --all
controller worktrees import [<project>] --path <path>

Registration behavior

For each imported worktree, Controller should:

• Validate that Git reports it as belonging to the project's repository.
• Preserve its existing absolute path and branch/HEAD state.
• Generate a Controller worktree ID.
• Assign a non-conflicting port offset.
• Register it without automatically rerunning the project setup script, unless the user explicitly requests setup.
• Handle worktrees located outside Controller's managed worktree directory.
• Reject missing, prunable, or duplicate entries with a clear explanation.

Imported worktrees should use the same deletion safeguards as other worktrees. Because their directories may predate Controller, the UI should make the destructive effect of deletion especially clear.

Acceptance criteria

• Adding a project detects existing linked Git worktrees.
• The user can import all or selected worktrees.
• An import action is available after project creation.
• Import does not create, move, reset, or modify the underlying Git worktree.
• Imported worktrees retain their paths, branches, commits, and uncommitted changes.
• Imported worktrees receive unique Controller IDs and port offsets.
• Worktrees outside Controller's managed worktree directory are supported.
• Already registered, missing, and prunable worktrees are handled safely.
• Imported worktrees appear in the sidebar and can start sessions normally.
• Tests cover discovery, selective import, detached HEAD, duplicate registration, and paths containing spaces.

Related

• Prevent worktrees.json registry loss under concurrent reads and writes #332 concerns recovery after Controller registry loss. It mentions reconciliation as a safeguard, but this issue covers first-class onboarding of pre-existing Git worktrees during normal project setup.