Sandbox Existing Branches Design

Enable bb sandbox:start to use existing local or remote branches, not just create new ones.

Goals

Sandbox any existing branch (local or remote) for exploration or continued work
Smart detection: auto-find branches matching the provided name
Interactive confirmation showing commit context before proceeding
Full write access to the branch (not read-only)

Behavior

Detection Flow

bb sandbox:start <name>
       │
       ▼
  git fetch origin
       │
       ▼
  Worktree exists at .worktrees/<name>?
       │ yes                    │ no
       ▼                        ▼
  Reuse worktree          Check for branches:
  Start containers        - local <name>
                          - remote origin/<name>
                                  │
                                  ▼
                          Classify result:
                          NONE / LOCAL_ONLY / REMOTE_ONLY /
                          BOTH_SAME / BOTH_DIVERGED
                                  │
                                  ▼
                          Show confirmation with commit info
                                  │
                                  ▼
                          Create worktree, start containers

Branch Classification

Classification	Meaning
NONE	No branch found locally or on remote
LOCAL_ONLY	Only local branch exists
REMOTE_ONLY	Only `origin/<name>` exists
BOTH_SAME	Local and remote exist, same commit
BOTH_DIVERGED	Local and remote exist, different commits

Confirmation Prompts

NONE:

No branch 'foo' found.
Create new branch 'foo' from master? [Y/n]

LOCAL_ONLY:

Found local branch 'feature/bar':
  abc123f - Fix document parsing (you, 2 days ago)
Use this branch? [Y/n]

REMOTE_ONLY:

Found remote branch 'origin/feature/bar':
  abc123f - Fix document parsing (John, 2 days ago)
Create local branch 'feature/bar' tracking remote? [Y/n]

BOTH_SAME:

Found branch 'feature/bar' (synced with remote):
  abc123f - Fix document parsing (John, 2 days ago)
Use this branch? [Y/n]

BOTH_DIVERGED:

Branch 'feature/bar' has diverged from remote:

  Local:  def456a - Your local changes (you, 1 hour ago)
  Remote: abc123f - Fix document parsing (John, 2 days ago)

Which version?
  1) Local (keep your changes)
  2) Remote (discard local, reset to remote)
  3) Cancel

Choice [1/2/3]:

Actions After Confirmation

Classification	Action
NONE (confirmed)	`git branch <name> master` then create worktree
LOCAL_ONLY	Create worktree from existing local branch
REMOTE_ONLY	`git branch <name> origin/<name>` then create worktree
BOTH_SAME	Create worktree from local branch
BOTH_DIVERGED (choice 1)	Create worktree from local branch
BOTH_DIVERGED (choice 2)	`git branch -f <name> origin/<name>` then create worktree

Worktree Path

Worktree path matches branch name exactly (stripping origin/ for remote branches):

Branch foo → .worktrees/foo
Branch feature/bar → .worktrees/feature/bar
Remote origin/feature/bar → local feature/bar → .worktrees/feature/bar

Changes to Existing Code

Additions

find-branch — Detection logic returning classification + commit info
prompt-confirm — Y/n prompt with context
prompt-choice — Multiple choice prompt for diverged branches
get-commit-info — Fetch short hash, message, author, relative date

Modifications

start — Insert detection/confirmation before worktree creation
clean — Handle arbitrary branch names (drop feature/ prefix assumption)
worktree-base — Change from .worktrees/feature to .worktrees

Unchanged

Port hashing logic
Docker compose invocation
stop, list commands
Container/volume naming scheme