//revive:disable:file-length-limit // Legacy lifecycle coordination remains in one file; replacement recovery lives in manager_replacement.go. package worktree import ( "context" "errors" "fmt" "os" "path/filepath" "strconv" "strings" "time" "github.com/google/uuid" "github.com/kandev/kandev/internal/common/gitref" "github.com/kandev/kandev/internal/system/storage" storageworkspaces "github.com/kandev/kandev/internal/system/storage/workspaces" "go.uber.org/zap" "github.com/kandev/kandev/internal/gitbootstrap" "github.com/kandev/kandev/internal/repoclone" "github.com/kandev/kandev/internal/worktree/copyfiles" ) // ResolveRemoteDefaultBranch returns the default branch advertised by the // origin remote. It reads the local symref first, then refreshes it once with // non-interactive Git when the local ref is absent. func (m *Manager) ResolveRemoteDefaultBranch(ctx context.Context, repoPath string) (string, error) { branch, err := readRemoteDefaultBranch(repoPath) if err != nil { return "", err } if branch != "" { return branch, nil } output, runErr := m.runBoundedGitInspect(ctx, repoPath, "remote", "set-head", "origin", "--auto") if runErr != nil { return "", classifyRemoteDefaultError(output, runErr) } branch, err = readRemoteDefaultBranch(repoPath) if err != nil { return "", err } if branch == "" { return "", ErrRemoteDefaultUnresolved } return branch, nil } func readRemoteDefaultBranch(repoPath string) (string, error) { gitDir, err := gitref.ResolveGitDir(repoPath) if err != nil { if errors.Is(err, os.ErrNotExist) { return "", nil } return "", fmt.Errorf("resolve git directory: %w", err) } commonDir := gitref.ResolveCommonGitDir(gitDir) path := filepath.Join(commonDir, "refs", "remotes", "origin", "HEAD") data, err := os.ReadFile(path) if err != nil { if errors.Is(err, os.ErrNotExist) { return "", nil } return "", fmt.Errorf("read origin default branch: %w", err) } line := strings.TrimSpace(string(data)) const prefix = "ref: refs/remotes/origin/" if !strings.HasPrefix(line, prefix) { return "", nil } branch := strings.TrimPrefix(line, prefix) if branch == "" || strings.ContainsAny(branch, "\r\n") { return "", nil } return branch, nil } func classifyRemoteDefaultError(output string, runErr error) error { if errors.Is(runErr, context.Canceled) || errors.Is(runErr, context.DeadlineExceeded) { return runErr } lowerOutput := strings.ToLower(output) switch { case containsAuthFailure(lowerOutput): return fmt.Errorf("%w: %s", ErrAuthFailed, strings.TrimSpace(output)) case strings.Contains(lowerOutput, "could not resolve host"), strings.Contains(lowerOutput, "connection timed out"), strings.Contains(lowerOutput, "network is unreachable"), strings.Contains(lowerOutput, "could not connect"): return fmt.Errorf("%w: %s", ErrRemoteDefaultNetwork, strings.TrimSpace(output)) case isRemoteRefMissingError(fmt.Errorf("%s", output)): return fmt.Errorf("%w: %s", ErrRemoteDefaultUnresolved, strings.TrimSpace(output)) default: return ClassifyGitError(output, runErr) } } // Create creates a new worktree for a session, or returns an existing one. // Each session gets its own worktree for isolation. Checks by SessionID first, // then by WorktreeID if provided (for session resumption). // Only creates a new worktree if none exists for the session. func (m *Manager) Create(ctx context.Context, req CreateRequest) (*Worktree, error) { if err := req.Validate(); err != nil { return nil, err } if req.ReuseRequired { return m.reuseRequiredWorktree(ctx, req) } // Reject invalid explicit slugs up-front. If either slug is non-empty but // normalizes to "", reuse/path lookup would silently target the wrong // worktree or fail later with a less obvious error. if req.BranchSlug != "" && SanitizeBranchSlug(req.BranchSlug) == "" { return nil, ErrInvalidBranchSlug } if req.BranchIdentitySlug != "" && SanitizeBranchSlug(req.BranchIdentitySlug) == "" { return nil, ErrInvalidBranchSlug } if wt, handled, err := m.tryReuseExisting(ctx, req); handled { if err == nil && wt != nil { err = m.configureContributionDestination(ctx, req.RepositoryPath, wt.Path, wt.Branch, req.ContributionDestination) } return wt, err } if err := m.refreshRepositoryForMaterialization(ctx, &req); err != nil { return nil, err } // Check repository is a git repo if !m.isGitRepo(req.RepositoryPath) { return nil, ErrRepoNotGit } // Get repository lock for safe concurrent access repoLock := m.getRepoLock(req.RepositoryPath) repoLock.Lock() lockAcquired := time.Now() defer func() { repoLock.Unlock() m.logger.Debug("released worktree repo lock", zap.String("repository_path", req.RepositoryPath), zap.Duration("held", time.Since(lockAcquired))) m.releaseRepoLock(req.RepositoryPath) }() baseRef, fallbackWarning, fallbackDetail, err := m.resolveBaseRefWithFallback(ctx, &req) if err != nil { return nil, err } // Worktrees are always placed under ~/.kandev/tasks/{taskDir}/{repo}/. // Callers must populate TaskDirName and RepoName; the legacy flat layout // has been removed, so a missing field is a programming error. if req.TaskDirName == "" || req.RepoName == "" { return nil, ErrTaskDirRequired } wt, err := m.createInTaskDir(ctx, req, baseRef, fallbackWarning, fallbackDetail) if err != nil { return nil, err } if err := m.configureContributionDestination(ctx, req.RepositoryPath, wt.Path, wt.Branch, req.ContributionDestination); err != nil { return nil, err } return wt, nil } // refreshRepositoryForMaterialization runs a provider-authenticated refresh // only when Create is going to materialize or recreate a worktree. Reuse is // checked by the caller first, so a valid existing worktree never refreshes // origin or incurs provider authentication work. func (m *Manager) refreshRepositoryForMaterialization(ctx context.Context, req *CreateRequest) error { if req == nil || req.RemoteSyncHandled { return nil } if req.RefreshRepositoryWithState != nil { state, err := req.RefreshRepositoryWithState(ctx) if err != nil { return m.handleProviderRefreshFailure(ctx, req, err) } req.RemoteRefState = state req.RemoteSyncHandled = true req.PullBeforeWorktree = false return nil } if req.RefreshRepository == nil { return nil } if err := req.RefreshRepository(ctx); err != nil { return m.handleProviderRefreshFailure(ctx, req, err) } req.RemoteSyncHandled = true req.PullBeforeWorktree = false return nil } // handleProviderRefreshFailure keeps host worktree creation local-first when // a provider refresh fails after a usable local base has been verified. An // explicit remote ref, a missing local base, and caller cancellation remain // strict because they require remote materialization or a terminal stop. func (m *Manager) handleProviderRefreshFailure(ctx context.Context, req *CreateRequest, refreshErr error) error { if ctxErr := ctx.Err(); ctxErr != nil || errors.Is(refreshErr, context.Canceled) { if ctxErr != nil { return ctxErr } return refreshErr } if req.PRNumber > 0 { return refreshErr } if isRemoteOnlyBaseRef(req.BaseBranch) { return refreshErr } localExists, err := m.branchExists(ctx, req.RepositoryPath, req.BaseBranch) if err != nil || !localExists { return refreshErr } if ctxErr := ctx.Err(); ctxErr != nil { return ctxErr } reason := classifyGitFallbackReason(refreshErr, refreshErr.Error(), nil) warning, detail := localBaseRefreshWarning(reason, req.BaseBranch) req.baseRefreshFallback = true req.baseRefreshFallbackWarning = warning req.baseRefreshFallbackDetail = detail m.logger.Warn("provider refresh was incomplete; using local base", zap.String("repository_path", req.RepositoryPath), zap.String("branch", req.BaseBranch), zap.String("reason", reason), zap.String("fallback_ref", req.BaseBranch)) m.reportSyncProgress(req.OnSyncProgress, SyncProgressEvent{ StepName: "Sync base branch", Status: SyncProgressCompleted, Output: fmt.Sprintf("Provider refresh incomplete (%s); using local base %s", reason, req.BaseBranch), Warning: warning, WarningDetail: detail, }) return nil } func isRemoteOnlyBaseRef(branch string) bool { branch = strings.TrimSpace(branch) return strings.HasPrefix(branch, "origin/") || strings.HasPrefix(branch, "refs/remotes/") } func (m *Manager) ensureEmptyRemoteBaseline(ctx context.Context, req *CreateRequest) (string, error) { if req == nil || req.RemoteRefState != repoclone.RemoteRefStateEmpty { return "", nil } baseline, err := gitbootstrap.Ensure(ctx, req.RepositoryPath, req.BaseBranch) if errors.Is(err, gitbootstrap.ErrBaselineConflict) { req.RemoteRefState = repoclone.RemoteRefStateHasRefs req.RemoteSyncHandled = false baseBranch := strings.TrimPrefix(strings.TrimSpace(req.BaseBranch), "origin/") return strings.TrimPrefix(baseBranch, "refs/heads/"), nil } if err != nil { return "", fmt.Errorf("seed empty-remote local baseline: %w", err) } req.RemoteSyncHandled = true req.PullBeforeWorktree = false return baseline.BaseRef, nil } // reuseRequiredWorktree resolves the exact canonical worktree for an // additional session. It intentionally performs no Git operation and does // not run contribution setup or repository scripts: another active session // may be using this checkout with uncommitted changes. func (m *Manager) reuseRequiredWorktree(ctx context.Context, req CreateRequest) (*Worktree, error) { if req.WorktreeID == "" || req.TaskEnvironmentID == "" { return nil, ErrReuseWorktreeUnavailable } requestedBranchSlug := requestBranchIdentitySlug(req) if (req.BranchSlug != "" || req.BranchIdentitySlug != "") && requestedBranchSlug == "" { return nil, ErrReuseWorktreeUnavailable } wt, err := m.GetByID(ctx, req.WorktreeID) if err != nil { return nil, fmt.Errorf("%w: %w", ErrReuseWorktreeUnavailable, err) } if wt == nil || wt.Status != StatusActive || wt.RepositoryID != req.RepositoryID || wt.TaskEnvironmentID != req.TaskEnvironmentID || (requestedBranchSlug != "" && SanitizeBranchSlug(wt.BranchSlug) != requestedBranchSlug) { return nil, ErrReuseWorktreeUnavailable } handle, valid, err := m.openReusableWorktreePath(wt.Path, wt) if err != nil { return nil, err } if handle != nil { defer func() { _ = handle.Close() }() } if !valid { if err := m.classifyUnavailableReusableWorktree(ctx, req, wt); err != nil { return nil, err } return nil, ErrReuseWorktreeUnavailable } return wt, nil } // classifyUnavailableReusableWorktree distinguishes a missing checkout from a // branch that no longer exists in either the local repository or its // remote-tracking refs. Attach-only reuse must not recreate a checkout, but a // confirmed missing branch still needs the typed recovery signal used by the // explicit new-branch action. func (m *Manager) classifyUnavailableReusableWorktree( ctx context.Context, req CreateRequest, wt *Worktree, ) error { if wt == nil || wt.Branch == "" || !m.isGitRepo(req.RepositoryPath) { return nil } localExists, err := m.branchExists(ctx, req.RepositoryPath, wt.Branch) if err != nil { return fmt.Errorf("%w: verify saved branch %q: %w", ErrReuseWorktreeUnavailable, wt.Branch, err) } if localExists { return nil } branch := normalizeOriginBranchName(wt.Branch) remoteExists, err := m.branchExists(ctx, req.RepositoryPath, "refs/remotes/origin/"+branch) if err != nil { return fmt.Errorf("%w: verify saved remote branch %q: %w", ErrReuseWorktreeUnavailable, wt.Branch, err) } if remoteExists { return nil } remoteExists, err = m.remoteBranchExists(ctx, req.RepositoryPath, branch) if err != nil { return fmt.Errorf("%w: verify authoritative remote branch %q: %w", ErrReuseWorktreeUnavailable, wt.Branch, err) } if remoteExists { return nil } return fmt.Errorf("%w: %w", ErrReuseWorktreeUnavailable, &BranchUnrecoverableError{Branch: wt.Branch}) } // tryReuseExisting looks for an existing worktree to reuse, recreating it if // the on-disk directory is missing. Returns (wt, true, err) when fully handled // (caller should return immediately). Returns (nil, false, nil) when no reuse // candidate matched and the caller should proceed to create a new worktree. func (m *Manager) tryReuseExisting(ctx context.Context, req CreateRequest) (*Worktree, bool, error) { // First, check if a worktree already exists for this // (session, repository, branchSlug) triple. Multi-repo + multi-branch // sessions can host multiple worktrees concurrently, so we must scope the // lookup by RepositoryID AND BranchSlug — otherwise the second branch's // Create would return the first branch's worktree, silently collapsing // two distinct worktrees into one on-disk directory. reuseSlug := requestBranchIdentitySlug(req) if req.SessionID != "" { existing, err := m.GetBySessionAndRepo(ctx, req.SessionID, req.RepositoryID, reuseSlug) if err == nil && existing != nil { handle, valid, err := m.openReusableWorktreePath(existing.Path, existing) if err != nil { return nil, true, err } if handle != nil { defer func() { _ = handle.Close() }() } if valid { if err := m.validateReusableContribution(ctx, req, existing); err != nil { return nil, true, err } m.logger.Debug("reusing existing worktree by session+repo", zap.String("worktree_id", existing.ID), zap.String("session_id", req.SessionID), zap.String("repository_id", req.RepositoryID), zap.String("task_id", req.TaskID), zap.String("path", existing.Path)) return existing, true, nil } m.logger.Warn("worktree directory invalid, recreating", zap.String("worktree_id", existing.ID), zap.String("session_id", req.SessionID), zap.String("repository_id", req.RepositoryID), zap.String("task_id", req.TaskID)) wt, err := m.recreate(ctx, existing, req) return wt, true, err } } // If WorktreeID is provided, try to reuse that specific worktree (session resumption) if req.WorktreeID != "" { existing, err := m.GetByID(ctx, req.WorktreeID) if err == nil && existing != nil { handle, valid, err := m.openReusableWorktreePath(existing.Path, existing) if err != nil { return nil, true, err } if handle != nil { defer func() { _ = handle.Close() }() } if valid { if err := m.validateReusableContribution(ctx, req, existing); err != nil { return nil, true, err } m.logger.Info("reusing existing worktree by ID", zap.String("worktree_id", req.WorktreeID), zap.String("session_id", req.SessionID), zap.String("task_id", req.TaskID), zap.String("path", existing.Path)) return existing, true, nil } m.logger.Warn("worktree directory invalid, recreating", zap.String("worktree_id", req.WorktreeID), zap.String("session_id", req.SessionID), zap.String("task_id", req.TaskID)) wt, err := m.recreate(ctx, existing, req) return wt, true, err } // WorktreeID provided but not found - fall through to create new m.logger.Warn("worktree ID not found, creating new worktree", zap.String("worktree_id", req.WorktreeID), zap.String("session_id", req.SessionID), zap.String("task_id", req.TaskID)) } return nil, false, nil } // validateWorktreePathSafe opens a persisted worktree path through no-follow // directory handles. The handle is returned to the caller so the same // directory identity is used for ownership and reuse decisions. Missing paths // remain eligible for the normal recreate flow, while symlinked components // fail closed. func (m *Manager) validateWorktreePathSafe(worktreePath string) (storageworkspaces.DirectoryHandle, error) { if worktreePath == "" { return nil, nil } tasksBase, err := m.config.ExpandedTasksBasePath() if err != nil { return nil, fmt.Errorf("resolve tasks base path: %w", err) } tasksBase = filepath.Clean(tasksBase) // Paths outside the tasks base use the legacy flat layout. They do not have // a task-root ownership marker, but still get a no-follow handle so reuse // cannot follow a replacement link while checking the checkout. relativePath, err := filepath.Rel(tasksBase, worktreePath) if err != nil || relativePath == "." || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) { // Legacy paths are not below tasksBase, but they still get a pinned // no-follow handle so IsValid cannot be redirected by a symlink race. return m.openNoFollowWorktreePath(worktreePath) } if _, err := os.Lstat(tasksBase); errors.Is(err, os.ErrNotExist) { // A removed task base has no components to follow. Normal reuse will // recreate the persisted managed root before adding the worktree; // attach-only reuse still rejects the missing checkout via IsValid. return nil, nil } else if err != nil { return nil, fmt.Errorf("inspect tasks base path: %w", err) } return m.openNoFollowWorktreePath(worktreePath) } func (m *Manager) openNoFollowWorktreePath(worktreePath string) (storageworkspaces.DirectoryHandle, error) { cleanPath := filepath.Clean(worktreePath) if !filepath.IsAbs(cleanPath) { return nil, nil } handle, err := storageworkspaces.OpenDirectoryNoFollow(filepath.Dir(cleanPath), cleanPath) if err != nil { if errors.Is(err, os.ErrNotExist) { return nil, nil } return nil, fmt.Errorf("unsafe worktree path %s: %w", cleanPath, err) } if err := handle.VerifyPath(cleanPath); err != nil { _ = handle.Close() return nil, fmt.Errorf("worktree path changed during validation: %w", err) } return handle, nil } func (m *Manager) openReusableWorktreePath(worktreePath string, wt *Worktree) (storageworkspaces.DirectoryHandle, bool, error) { handle, err := m.validateWorktreePathSafe(worktreePath) if err != nil { return nil, false, err } if err := m.validateExistingWorktreePathOwner(worktreePath, wt); err != nil { if handle != nil { _ = handle.Close() } return nil, false, err } if handle == nil || !handle.IsValidWorktree() { if handle != nil { _ = handle.Close() } return nil, false, nil } if err := handle.VerifyPath(filepath.Clean(worktreePath)); err != nil { _ = handle.Close() return nil, false, fmt.Errorf("worktree path changed during reuse validation: %w", err) } return handle, true, nil } func worktreeOwnershipIdentity(wt *Worktree) (string, bool) { if wt != nil && wt.TaskDirName != "" { return wt.TaskDirName, true } if wt != nil { // Older in-memory and persisted records may not project TaskDirName. // Keep their existing ownership check until they are refreshed. return wt.TaskID, false } return "", false } // validateExistingWorktreePathOwner rejects a stale record whose stored path // now lies under another task's marked root. It deliberately runs before both // reuse and recreate: recreate removes the recorded path before adding a new // worktree, so checking only the reusable path could delete a live checkout. // Paths outside Kandev's task root and legacy unmarked task roots remain // eligible for their existing compatibility behavior. func (m *Manager) validateExistingWorktreePathOwner(worktreePath string, wt *Worktree) error { if worktreePath == "" { return nil } tasksBase, err := m.config.ExpandedTasksBasePath() if err != nil { return fmt.Errorf("resolve tasks base path: %w", err) } // Normalize: ExpandedTasksBasePath returns the configured value verbatim // (incl. trailing slashes or doubled separators), while filepath.Dir // always yields a cleaned form. Without this, the path computation below // may miscompute the task-root segment. tasksBase = filepath.Clean(tasksBase) relativePath, err := filepath.Rel(tasksBase, worktreePath) if err != nil || relativePath == "." || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) { return nil } recordIdentity, stableTaskDirName := worktreeOwnershipIdentity(wt) if recordIdentity == "" { return nil } // The task-root ownership marker always lives at the first path segment // below tasksBase (i.e. //). Walking all levels // up from worktreePath is wrong: a descendant repository that legitimately // contains its own .kandev-workspace.json (e.g. a nested project) would be // mistaken for the task-root marker. Derive the task root from the // relative path and inspect only that one directory. taskRoot := filepath.Join(tasksBase, strings.SplitN(relativePath, string(filepath.Separator), 2)[0]) owner, found, err := storageworkspaces.ReadOwnershipMarker(taskRoot) if err != nil { return fmt.Errorf("inspect worktree task root ownership: %w", err) } // Validate against the environment's stable task directory name, not the // mutable task ID. Shared environments can transfer ownership while their // physical task root and marker remain unchanged. Older records without the // projected directory name retain the task-ID compatibility check. ownerMatches := owner.TaskDirName == recordIdentity if !stableTaskDirName { ownerMatches = owner.TaskID == recordIdentity } if found && !ownerMatches { return fmt.Errorf("%w: path %q belongs to task %q", ErrWorktreePathOwnedByAnotherTask, worktreePath, owner.TaskID) } return nil } func (m *Manager) validateReusableContribution(ctx context.Context, req CreateRequest, existing *Worktree) error { if req.RemoteContribution == nil { return nil } remoteName, remoteRef, err := m.materializeRemoteContribution(ctx, req.RepositoryPath, req.RemoteContribution) if err != nil { return err } if err := m.validateContributionAncestor(ctx, existing.Path, req.RemoteContribution.HeadSHA, "HEAD"); err != nil { return fmt.Errorf("existing contribution worktree is not based on the validated source: %w", err) } if err := m.setUpstreamIfExistsRemote(ctx, existing.Path, existing.Branch, remoteName, req.RemoteContribution.HeadBranch); err != nil { return err } _ = remoteRef return nil } func requestBranchIdentitySlug(req CreateRequest) string { if req.BranchIdentitySlug != "" { return SanitizeBranchSlug(req.BranchIdentitySlug) } return SanitizeBranchSlug(req.BranchSlug) } func recreateSourceBranch(existingBranch, checkoutBranch string) string { if checkoutBranch != "" { return checkoutBranch } return existingBranch } // resolveBaseRefWithFallback resolves the base ref for a new worktree, optionally // pulling from origin first, and falling back to req.FallbackBaseBranch when the // requested base branch is missing. When the fallback path is taken, req.BaseBranch // is updated to reflect the resolved name and a non-empty warning/detail pair is // returned for surfacing on the resulting worktree record. func (m *Manager) resolveBaseRefWithFallback(ctx context.Context, req *CreateRequest) (baseRef, warning, detail string, err error) { baseRef = req.BaseBranch warning = req.baseRefreshFallbackWarning detail = req.baseRefreshFallbackDetail resolvedFallback := "" switch { case req.baseRefreshFallback: // The provider refresh already failed after verifying the local base. // Keep PullBeforeWorktree true so a requested checkout branch still // follows its own materialization policy, but do not refresh the base a // second time through the unauthenticated Git path. case req.RemoteRefState == repoclone.RemoteRefStateEmpty: baselineRef, baselineErr := m.ensureEmptyRemoteBaseline(ctx, req) if baselineErr != nil { return "", "", "", baselineErr } switch { case baselineRef != "": baseRef = baselineRef case req.RemoteSyncHandled: baseRef, warning, detail, resolvedFallback, err = m.resolveRefreshedBaseRefWithFallback( ctx, req.RepositoryPath, req.BaseBranch, req.FallbackBaseBranch, ) case req.PullBeforeWorktree: if req.PRNumber > 0 { baseRef, resolvedFallback, err = m.pullBaseBranchWithFallback( ctx, req.RepositoryPath, req.BaseBranch, req.FallbackBaseBranch, req.OnSyncProgress, ) } else { baseRef, err = m.pullBaseBranch(ctx, req.RepositoryPath, req.BaseBranch, req.OnSyncProgress) } } case req.RemoteSyncHandled: baseRef, warning, detail, resolvedFallback, err = m.resolveRefreshedBaseRefWithFallback( ctx, req.RepositoryPath, req.BaseBranch, req.FallbackBaseBranch, ) case req.PullBeforeWorktree: if req.PRNumber > 0 { baseRef, resolvedFallback, err = m.pullBaseBranchWithFallback( ctx, req.RepositoryPath, req.BaseBranch, req.FallbackBaseBranch, req.OnSyncProgress, ) } else { baseRef, err = m.pullBaseBranch(ctx, req.RepositoryPath, req.BaseBranch, req.OnSyncProgress) } } if err != nil { return "", "", "", err } if resolvedFallback != "" { return m.finishMissingRemoteBaseFallback(req, resolvedFallback, baseRef) } baseExists, baseErr := m.branchExists(ctx, req.RepositoryPath, baseRef) if baseErr != nil { // Could not determine existence (timeout / fs stall). Surface the // real cause instead of pretending the branch is missing. return "", "", "", fmt.Errorf("could not verify base branch %q: %w", baseRef, baseErr) } if baseExists { return baseRef, warning, detail, nil } fallback := strings.TrimSpace(req.FallbackBaseBranch) if fallback != "" && fallback != baseRef { resolvedFallback, err = m.resolveFallbackRef(ctx, req, fallback) if err != nil { return "", "", "", err } fallbackExists, fallbackErr := m.branchExists(ctx, req.RepositoryPath, resolvedFallback) if fallbackErr != nil { return "", "", "", fmt.Errorf("could not verify fallback base branch %q: %w", resolvedFallback, fallbackErr) } if fallbackExists { return m.finishBaseFallback(req, baseRef, fallback, resolvedFallback) } } // The persisted repository default can be stale or absent. Resolve the // live remote default only after the requested branch and stored fallback // have both failed. liveFallback, liveErr := m.ResolveRemoteDefaultBranch(ctx, req.RepositoryPath) if liveErr != nil { if errors.Is(liveErr, ErrRemoteDefaultUnresolved) { return "", "", "", fmt.Errorf("%w: %s (fallback %q also not found)", ErrInvalidBaseBranch, baseRef, fallback) } return "", "", "", liveErr } if liveFallback == baseRef { return "", "", "", fmt.Errorf("%w: %s", ErrInvalidBaseBranch, baseRef) } resolvedFallback, err = m.resolveFallbackRef(ctx, req, liveFallback) if err != nil { return "", "", "", err } fallbackExists, fallbackErr := m.branchExists(ctx, req.RepositoryPath, resolvedFallback) if fallbackErr != nil { return "", "", "", fmt.Errorf("could not verify live fallback base branch %q: %w", resolvedFallback, fallbackErr) } if !fallbackExists { return "", "", "", fmt.Errorf("%w: %s (fallback %q also not found)", ErrInvalidBaseBranch, baseRef, liveFallback) } fallback = liveFallback return m.finishBaseFallback(req, baseRef, fallback, resolvedFallback) } func (m *Manager) resolveFallbackRef(ctx context.Context, req *CreateRequest, fallback string) (string, error) { if req.RemoteSyncHandled { resolved, _, _, _, err := m.resolveRefreshedBaseRefWithFallback(ctx, req.RepositoryPath, fallback, "") return resolved, err } if req.PullBeforeWorktree { return m.pullBaseBranch(ctx, req.RepositoryPath, fallback, nil) } return fallback, nil } func (m *Manager) finishBaseFallback(req *CreateRequest, baseRef, fallback, resolvedFallback string) (string, string, string, error) { m.logger.Warn("requested base branch not found, falling back", zap.String("repository_path", req.RepositoryPath), zap.String("requested_branch", baseRef), zap.String("fallback_branch", fallback)) // Use req.BaseBranch (the user-supplied name) in the user-facing warning // rather than baseRef, which may carry an internal "origin/" form // produced by pullBaseBranch when PullBeforeWorktree is set. warning := fmt.Sprintf("Requested base branch %q not found, used %q instead", req.BaseBranch, fallback) detail := fmt.Sprintf("git rev-parse --verify %s failed; recovered using fallback branch %q (typically the repository's default_branch)", baseRef, fallback) // Reflect the resolved branch in the persisted worktree record so // downstream consumers (UI, queries, debug logs) see the actual base // rather than the requested-but-missing one. req.BaseBranch = fallback return resolvedFallback, warning, detail, nil } func (m *Manager) finishMissingRemoteBaseFallback( req *CreateRequest, fallback, resolvedFallback string, ) (string, string, string, error) { m.logger.Warn("requested base branch no longer exists on origin, falling back", zap.String("repository_path", req.RepositoryPath), zap.String("requested_branch", req.BaseBranch), zap.String("fallback_branch", fallback)) warning := fmt.Sprintf("Base branch %q no longer exists on origin; using %q instead.", req.BaseBranch, fallback) detail := fmt.Sprintf("Required refresh could not find remote ref %q; fallback branch %q refreshed successfully", req.BaseBranch, fallback) req.BaseBranch = fallback return resolvedFallback, warning, detail, nil } // createInTaskDir creates a worktree inside the task directory structure: // ~/.kandev/tasks/{taskDirName}/{repoName}/ // // RepoName is sanitized to a single path segment so display names like // "owner/repo" don't produce a nested subdirectory — that would push the // worktree one level below the task root and break agentctl's sibling-based // multi-repo detection. func (m *Manager) createInTaskDir(ctx context.Context, req CreateRequest, baseRef, fallbackWarning, fallbackDetail string) (*Worktree, error) { worktreePath, err := m.prepareTaskWorktreePath(req) if err != nil { return nil, err } _, branchName := m.buildWorktreeNames(req) startPoint := baseRef var fetchResult *FetchBranchResult checkoutMode := req if req.RemoteContribution != nil { return m.createContributionInTaskDir(ctx, req, worktreePath, fallbackWarning, fallbackDetail) } if req.CheckoutBranch != "" { if req.RemoteSyncHandled { selectedRef, prepareErr := m.prepareBranchFromRefreshedOrigin( ctx, req.RepositoryPath, req.CheckoutBranch, req.CheckoutBranch, req.PRNumber, ) if prepareErr != nil { return nil, prepareErr } if selectedRef == "" { if req.PRNumber > 0 { err := &BranchUnrecoverableError{Branch: req.CheckoutBranch} return nil, fmt.Errorf("%w: refreshed pull request head %d was not materialized", err, req.PRNumber) } branchName = req.CheckoutBranch checkoutMode.CheckoutBranch = "" } else { // A refreshed remote that contains the old local checkout branch // must be the actual worktree start point. Passing it only to the // preparation probe would still let git worktree add check out the // stale local branch. startPoint = selectedRef } } else { // PRNumber != 0 means the caller wants the refs/pull//head ref; // fork PR branches don't exist as plain refs locally or under // origin/, so the existence probe must be skipped and the // fetch path always runs. // // When PRNumber == 0 and the named branch is absent locally and on // origin, the caller's intent is "create a new branch with this // name" rather than "fetch this existing ref" — the historical // fetch-then-check-out path errored ("not found locally or on // remote") in that case and rolled back. We keep that behavior for // ordinary branch creation, but a provider refresh fallback must // still materialize the requested checkout branch or fail. The // provider may have been the only route to the remote ref. if req.PRNumber == 0 && !req.baseRefreshFallback && !m.checkoutBranchExistsAnywhere(ctx, req.RepositoryPath, req.CheckoutBranch) { m.logger.Info("checkout branch missing locally and on origin; creating new branch with this name", zap.String("repository_path", req.RepositoryPath), zap.String("requested_branch", req.CheckoutBranch), zap.String("base_ref", baseRef)) branchName = req.CheckoutBranch checkoutMode.CheckoutBranch = "" } else { checkoutRefreshRequired := req.PullBeforeWorktree if req.baseRefreshFallback && req.PRNumber == 0 { // A provider refresh failure does not make an existing local // checkout branch remote-only. Let the fetch helper verify and // reuse that local branch when its refresh also fails. If the // branch is absent locally, the helper still returns an error. checkoutRefreshRequired = false } fetchResult, err = m.fetchBranchToLocalWithPolicy( ctx, req.RepositoryPath, req.CheckoutBranch, req.PRNumber, checkoutRefreshRequired, ) if err != nil { return nil, err } if fetchResult.StartPoint != "" { startPoint = fetchResult.StartPoint } else { startPoint = req.CheckoutBranch } if req.baseRefreshFallback && fetchResult.Warning != "" { fetchResult.WarningDetail = localCheckoutBranchRefreshDetail(req.CheckoutBranch) } } } } worktreeID, branchName, err := m.addWorktreeForBranch(ctx, checkoutMode, worktreePath, branchName, startPoint, baseRef) if err != nil { return nil, err } wt := m.buildWorktreeRecord(worktreeID, req, worktreePath, branchName) if fetchResult != nil { wt.FetchWarning = fetchResult.Warning wt.FetchWarningDetail = fetchResult.WarningDetail } if err := m.persistAndCacheWorktree(ctx, wt, req, worktreePath); err != nil { return nil, err } // Surface any base-branch fallback before signaling readiness so the // "Create worktree" step can show the warning when completed early. if fallbackWarning != "" { wt.BaseBranchFallbackWarning = fallbackWarning wt.BaseBranchFallbackDetail = fallbackDetail } // The worktree directory now exists and is persisted. Signal readiness // before running the per-repo setup script so the env preparer can complete // the "Create worktree" UI step and render the setup script as a distinct, // subsequent step rather than overlapping it. if req.OnWorktreeCreated != nil { req.OnWorktreeCreated(wt) } m.copyConfiguredFiles(ctx, req, wt) // Setup script failures are non-fatal — runWorktreeSetupScript records a // warning on wt and keeps the worktree so the agent can still launch. m.runWorktreeSetupScript(ctx, wt, req.ScriptEnv) m.logger.Info("created worktree in task directory", zap.String("session_id", req.SessionID), zap.String("task_id", req.TaskID), zap.String("task_dir", req.TaskDirName), zap.String("repo_name", req.RepoName), zap.String("path", worktreePath), zap.String("branch", wt.Branch)) return wt, nil } func (m *Manager) createContributionInTaskDir( ctx context.Context, req CreateRequest, worktreePath, fallbackWarning, fallbackDetail string, ) (*Worktree, error) { remoteName, contributionRef, err := m.materializeRemoteContribution(ctx, req.RepositoryPath, req.RemoteContribution) if err != nil { return nil, err } worktreeID, branchName, err := m.addContributionWorktree(ctx, req, worktreePath, contributionRef, remoteName) if err != nil { return nil, err } wt := m.buildWorktreeRecord(worktreeID, req, worktreePath, branchName) if err := m.persistAndCacheWorktree(ctx, wt, req, worktreePath); err != nil { return nil, err } if fallbackWarning != "" { wt.BaseBranchFallbackWarning = fallbackWarning wt.BaseBranchFallbackDetail = fallbackDetail } if req.OnWorktreeCreated != nil { req.OnWorktreeCreated(wt) } m.copyConfiguredFiles(ctx, req, wt) m.runWorktreeSetupScript(ctx, wt, req.ScriptEnv) return wt, nil } func (m *Manager) prepareTaskWorktreePath(req CreateRequest) (string, error) { repoDir := SanitizeRepoDirName(req.RepoName) if repoDir == "" { return "", ErrInvalidRepoName } branchSlug := SanitizeBranchSlug(req.BranchSlug) if req.BranchSlug != "" && branchSlug == "" { return "", ErrInvalidBranchSlug } worktreePath, err := m.config.TaskWorktreePath(req.TaskDirName, repoDir, branchSlug) if err != nil { return "", fmt.Errorf("failed to get task worktree path: %w", err) } taskDir := filepath.Dir(worktreePath) if err := m.validateTaskDir(taskDir); err != nil { return "", err } if err := os.MkdirAll(taskDir, 0755); err != nil { return "", fmt.Errorf("failed to create task directory: %w", err) } if err := storageworkspaces.WriteOwnershipMarker(taskDir, storageworkspaces.OwnershipMarker{ TaskID: req.TaskID, WorkspaceID: req.WorkspaceID, TaskDirName: req.TaskDirName, LayoutVersion: storageworkspaces.LayoutVersionSemantic, }); err != nil { return "", m.describeOwnershipMarkerFailure(taskDir, req.TaskID, err) } return worktreePath, nil } // describeOwnershipMarkerFailure enriches a WriteOwnershipMarker failure with // the conflicting owner's task id when one can be read back from disk. This // is the on-disk symptom of an inherit_parent child whose original owner // task (the parent it inherited a workspace from) was archived: the child's // session then has no bound environment, falls through to creating a fresh // worktree here, and finds the shared task directory still marked for the // now-archived owner. This package sits below internal/task and cannot look // up whether that owner is actually archived, so the message can only name // the conflicting task id and point at the workaround rather than confirm // the cause. func (m *Manager) describeOwnershipMarkerFailure(taskDir, requestedTaskID string, cause error) error { existing, found, readErr := storageworkspaces.ReadOwnershipMarker(taskDir) if readErr == nil && found && existing.TaskID != "" && existing.TaskID != requestedTaskID { return fmt.Errorf( "mark task directory ownership: %w (task directory is already owned by task %s; if that task was archived, this task can no longer reuse its workspace and needs workspace_mode=new_workspace)", cause, existing.TaskID, ) } return fmt.Errorf("mark task directory ownership: %w", cause) } func (m *Manager) validateTaskDir(taskDir string) error { tasksBase, err := m.config.ExpandedTasksBasePath() if err != nil { return fmt.Errorf("failed to resolve tasks base path: %w", err) } absTasksBase, err := filepath.Abs(tasksBase) if err != nil { return fmt.Errorf("failed to resolve tasks base path: %w", err) } absTaskDir, err := filepath.Abs(taskDir) if err != nil { return fmt.Errorf("failed to resolve task directory: %w", err) } if err := storage.ValidateNoSymlinkPath(absTasksBase, absTaskDir); err != nil { return fmt.Errorf("unsafe task directory: %w", err) } return nil } // addWorktreeForBranch creates the git worktree, trying the checkout branch directly first // and falling back to a suffixed branch if the checkout branch is already in use. // When a checkout branch is specified, it sets the upstream tracking branch to // origin/ when that ref points to the worktree's start point. func (m *Manager) addWorktreeForBranch(ctx context.Context, req CreateRequest, worktreePath, fallbackBranch, startPoint, baseRef string) (string, string, error) { if req.CheckoutBranch == "" { id, err := m.gitAddWorktree(ctx, req.RepositoryPath, fallbackBranch, worktreePath, baseRef) return id, fallbackBranch, err } // A pull request head is an immutable remote ref for this launch. Never // update or reset a local branch with the same name as the PR head: that // branch may belong to another task and may contain unpushed work. if req.PRNumber > 0 { branchName := req.CheckoutBranch exists, probeErr := m.branchExists(ctx, req.RepositoryPath, branchName) if probeErr != nil { return "", "", fmt.Errorf("verify PR checkout branch %q: %w: %w", branchName, ErrWorkspaceCheckoutFailed, probeErr) } if exists { return m.addPRWorktreeWithUniqueBranch(ctx, req, worktreePath, startPoint) } id, addErr := m.gitAddWorktree(ctx, req.RepositoryPath, branchName, worktreePath, startPoint) if addErr == nil { m.setUpstreamIfMatchesStartPoint(ctx, worktreePath, branchName, req.CheckoutBranch, startPoint) return id, branchName, nil } if !errors.Is(addErr, ErrBranchExists) { return "", "", fmt.Errorf("materialize PR checkout branch %q: %w: %w", branchName, ErrWorkspaceCheckoutFailed, addErr) } return m.addPRWorktreeWithUniqueBranch(ctx, req, worktreePath, startPoint) } // Try checking out the PR branch directly (common case: single task per PR). var id string var err error if req.RemoteSyncHandled && startPoint != req.CheckoutBranch { id, err = m.gitAddWorktreeExistingAtRef(ctx, req.RepositoryPath, req.CheckoutBranch, worktreePath, startPoint) } else { id, err = m.gitAddWorktreeExisting(ctx, req.RepositoryPath, req.CheckoutBranch, worktreePath) } if err == nil { m.setUpstreamIfExists(ctx, worktreePath, req.CheckoutBranch, req.CheckoutBranch) return id, req.CheckoutBranch, nil } if !errors.Is(err, ErrBranchCheckedOut) { return "", "", err } // Branch is in use by another worktree — create a unique fallback branch // using the original branch name with a random suffix. suffixed := req.CheckoutBranch + "-" + SmallSuffix(3) id, err = m.gitAddWorktree(ctx, req.RepositoryPath, suffixed, worktreePath, startPoint) if err == nil { m.setUpstreamIfExists(ctx, worktreePath, suffixed, req.CheckoutBranch) } return id, suffixed, err } const prCheckoutBranchAttempts = 20 func prCheckoutBranchCandidates(checkoutBranch, taskID string) []string { suffix := TaskDirSuffix(taskID) if suffix == "" { suffix = SmallSuffix(3) } candidates := make([]string, 0, prCheckoutBranchAttempts) for attempt := 0; attempt < prCheckoutBranchAttempts; attempt++ { candidate := checkoutBranch + "-" + suffix if attempt > 0 { candidate += "-" + strconv.Itoa(attempt) } candidates = append(candidates, candidate) } return candidates } func (m *Manager) addPRWorktreeWithUniqueBranch(ctx context.Context, req CreateRequest, worktreePath, startPoint string) (string, string, error) { for _, branchName := range prCheckoutBranchCandidates(req.CheckoutBranch, req.TaskID) { exists, probeErr := m.branchExists(ctx, req.RepositoryPath, branchName) if probeErr != nil { return "", "", fmt.Errorf("verify PR checkout branch %q: %w: %w", branchName, ErrWorkspaceCheckoutFailed, probeErr) } if exists { continue } id, addErr := m.gitAddWorktree(ctx, req.RepositoryPath, branchName, worktreePath, startPoint) if addErr == nil { m.setUpstreamIfMatchesStartPoint(ctx, worktreePath, branchName, req.CheckoutBranch, startPoint) return id, branchName, nil } if !errors.Is(addErr, ErrBranchExists) { return "", "", fmt.Errorf("materialize PR checkout branch %q: %w: %w", branchName, ErrWorkspaceCheckoutFailed, addErr) } } return "", "", fmt.Errorf( "materialize PR checkout branch %q after %d candidates: %w: %w", req.CheckoutBranch, prCheckoutBranchAttempts, ErrWorkspaceCheckoutFailed, ErrBranchExists, ) } // setUpstreamIfExists sets the upstream tracking branch for a worktree branch // to origin/ if the remote-tracking ref exists. Non-fatal on failure. func (m *Manager) setUpstreamIfExists(ctx context.Context, worktreePath, localBranch, remoteBranch string) { upstream := "origin/" + remoteBranch // Verify the remote-tracking ref exists. Use the non-interactive helper so // this cannot hang on a credential prompt while Create holds repoLock. verifyCmd := m.newNonInteractiveGitCmd(ctx, worktreePath, "rev-parse", "--verify", upstream) if err := runGitCmd(ctx, verifyCmd); err != nil { return } cmd := m.newNonInteractiveGitCmd(ctx, worktreePath, "branch", "--set-upstream-to="+upstream, localBranch) if out, err := runGitCmdCombinedOutput(ctx, cmd); err != nil { m.logger.Debug("failed to set upstream (non-fatal)", zap.String("branch", localBranch), zap.String("upstream", upstream), zap.String("output", string(out)), zap.Error(err)) } } func (m *Manager) setUpstreamIfMatchesStartPoint( ctx context.Context, worktreePath, localBranch, remoteBranch, startPoint string, ) { upstream := "origin/" + remoteBranch upstreamOID, upstreamErr := m.refCommitOID(ctx, worktreePath, upstream) startOID, startErr := m.refCommitOID(ctx, worktreePath, startPoint) if upstreamErr != nil || startErr != nil || upstreamOID != startOID { return } m.setUpstreamIfExists(ctx, worktreePath, localBranch, remoteBranch) } func (m *Manager) refCommitOID(ctx context.Context, worktreePath, ref string) (string, error) { cmd := m.newNonInteractiveGitCmd(ctx, worktreePath, "rev-parse", "--verify", ref+"^{commit}") output, err := runGitCmdCombinedOutput(ctx, cmd) return strings.TrimSpace(string(output)), err } // FetchBranchResult holds the outcome of a fetchBranchToLocal call. type FetchBranchResult struct { StartPoint string // Ref to use as worktree start point (e.g., "origin/branch"); empty = use local branch Warning string // User-friendly warning (non-empty when fell back to local) WarningDetail string // Raw git command output for debugging, or the probe that produced the warning when no git command failed } // fetchBranchToLocal ensures a branch exists locally and is up-to-date. // It first tries to fetch from origin to get the latest commits. If the fetch // fails (no remote, auth issue, offline), it falls back to the local branch. // Returns a FetchBranchResult with warning info and an error if the branch // doesn't exist anywhere. // // When prNumber > 0, the fetch uses the refs/pull//head refspec instead of // fetching the branch by name. GitHub mirrors every PR head under that ref on // the base repo, so this is the only way to materialize a fork PR's head // without adding the fork as a remote. func (m *Manager) fetchBranchToLocal(ctx context.Context, repoPath, branch string, prNumber int) (*FetchBranchResult, error) { return m.fetchBranchToLocalWithPolicy(ctx, repoPath, branch, prNumber, false) } func (m *Manager) fetchBranchToLocalWithPolicy( ctx context.Context, repoPath, branch string, prNumber int, required bool, ) (*FetchBranchResult, error) { m.logger.Info("syncing checkout branch", zap.String("branch", branch), zap.Int("pr_number", prNumber), zap.Bool("required", required), zap.String("repo_path", repoPath)) // Acquire the throttle slot FIRST, then build fetchCtx with the // full m.fetchTimeout budget. The previous shape (build fetchCtx, // then call runGitCmdCombinedOutput which Acquires internally) let // throttle queue time burn the fetch budget — same failure mode as // the manager_git.go probes fixed in PR #1216 (70s lock-held trace, // signal:killed). With this ordering the budget only counts actual // git execution time. if prNumber > 0 { remoteRef := pullRequestSnapshotRef(prNumber) refspec := fmt.Sprintf("+refs/pull/%d/head:%s", prNumber, remoteRef) output, err, fetchCtxErr := m.runGitCombinedAfterAcquire(ctx, m.fetchTimeout, repoPath, "fetch", gitNoTags, "origin", refspec) if err != nil { outputStr := string(output) if isRemoteBranchMissingError(outputStr) || isRemoteRefMissingError(errors.New(outputStr)) { return nil, fmt.Errorf( "fetch pull request head %d found no remote ref: %w: %w", prNumber, ErrWorkspaceCheckoutFailed, newConfirmedRemoteRefMissingError(outputStr), ) } reason := classifyGitFallbackReason(err, outputStr, fetchCtxErr) return nil, fmt.Errorf( "fetch pull request head %d failed (%s): %w: %w", prNumber, reason, ErrWorkspaceCheckoutFailed, syncFailureCause(reason, err, fetchCtxErr), ) } exists, verifyErr := m.branchExists(ctx, repoPath, remoteRef) if verifyErr != nil { return nil, fmt.Errorf("verify fetched pull request head %d: %w: %w", prNumber, ErrWorkspaceCheckoutFailed, verifyErr) } if !exists { return nil, fmt.Errorf("verify fetched pull request head %d: %w", prNumber, ErrWorkspaceCheckoutFailed) } return &FetchBranchResult{StartPoint: remoteRef}, nil } refspec := branch + ":" + branch output, err, fetchCtxErr := m.runGitCombinedAfterAcquire(ctx, m.fetchTimeout, repoPath, "fetch", gitNoTags, "origin", refspec) if err == nil { return &FetchBranchResult{}, nil } outputStr := string(output) // If the branch is checked out in another worktree, git refuses to update // the local ref. Retry by fetching only the remote-tracking ref (origin/branch), // which is always safe regardless of worktree state. if isFetchRefusedCheckedOut(outputStr) { if result := m.retryFetchAsRemoteTrackingRef(ctx, repoPath, branch, prNumber, required); result != nil { if required && result.Warning != "" { return nil, fmt.Errorf( "required refresh of checkout branch %q could not verify the refreshed ref: %w", branch, ErrGitCommandFailed, ) } return result, nil } } if required { if isRemoteBranchMissingError(outputStr) || isRemoteRefMissingError(errors.New(outputStr)) { return nil, fmt.Errorf( "required refresh of checkout branch %q found no remote ref: %w", branch, newConfirmedRemoteRefMissingError(outputStr), ) } reason := classifyGitFallbackReason(err, outputStr, fetchCtxErr) return nil, fmt.Errorf( "required refresh of checkout branch %q failed (%s): %w", branch, reason, syncFailureCause(reason, err, fetchCtxErr), ) } m.logger.Warn("fetch from origin failed, checking local branch", zap.String("branch", branch), zap.String("output", outputStr), zap.Error(err)) // Fall back to local branch if it exists. exists, existsErr := m.branchExists(ctx, repoPath, branch) if existsErr != nil { return nil, fmt.Errorf("could not verify local branch %q after fetch failure (%s): %w", branch, strings.TrimSpace(outputStr), existsErr) } if !exists { if isRemoteRefMissingError(errors.New(outputStr)) { return nil, fmt.Errorf( "branch %q not found locally or on remote: %w", branch, newConfirmedRemoteRefMissingError(outputStr), ) } reason := classifyGitFallbackReason(err, outputStr, fetchCtxErr) return nil, fmt.Errorf( "could not fetch branch %q and no local branch is available (%s): %w", branch, reason, syncFailureCause(reason, err, fetchCtxErr), ) } reason := classifyGitFallbackReason(err, outputStr, fetchCtxErr) warning := fmt.Sprintf("Could not fetch latest from origin (%s). Using local version of branch %q which may be outdated.", reason, branch) m.logger.Info("using local branch (fetch failed)", zap.String("branch", branch), zap.String("warning", warning)) return &FetchBranchResult{ Warning: warning, WarningDetail: strings.TrimSpace(outputStr), }, nil } // retryFetchAsRemoteTrackingRef retries the fetch with just the remote-tracking // ref (or pull/N/head) so it doesn't try to update the local branch ref, which // fails when that branch is already checked out in another worktree. Returns // nil if the retry also failed and the caller should fall back to the local // branch path. // // Uses ctx (not the original fetchCtx) and a fresh m.fetchTimeout budget via // runGitCombinedAfterAcquire — the parent's fetchCtx is already consumed by // the first attempt, so reusing it would leave no room for the retry. func (m *Manager) retryFetchAsRemoteTrackingRef( ctx context.Context, repoPath, branch string, prNumber int, required bool, ) *FetchBranchResult { retryRef := branch if prNumber > 0 { retryRef = fmt.Sprintf("pull/%d/head", prNumber) } if _, retryErr, _ := m.runGitCombinedAfterAcquire(ctx, m.fetchTimeout, repoPath, "fetch", gitNoTags, "origin", retryRef); retryErr != nil { return nil } m.logger.Info("fetched via remote-tracking ref (branch checked out elsewhere)", zap.String("branch", branch)) if prNumber > 0 { if required { // A fork PR has no origin/ ref. FETCH_HEAD is the only // ref produced by the successful pull//head retry, and is // therefore the safe start point for a required refresh. return &FetchBranchResult{StartPoint: "FETCH_HEAD"} } // Fork PRs have no origin/ ref — the bare // pull//head retry only updates FETCH_HEAD, so the local // `branch` (already populated by the prior worktree) is the // only valid start point. Empty StartPoint signals the // caller to fall back to req.CheckoutBranch. return &FetchBranchResult{} } return m.resolveRetryStartPoint(ctx, repoPath, branch) } // resolveRetryStartPoint picks the start point after the remote-tracking retry // succeeded. The retry refreshed origin/ but deliberately left the // local branch alone — that is the whole point of dropping the // `:` refspec — so origin/ is the better start point // only while it already contains every local commit. // // The first fetch is refused whenever the branch is checked out, which for a // user's own repository is the normal state of the branch they work on. If it // carries commits they have not pushed, adopting the remote ref drops them from // the new worktree, and Create still succeeds so nothing surfaces the loss. // Being slightly stale is recoverable; losing unpushed work is not. A probe // that cannot answer keeps the local branch for the same reason. // // This also matches the sibling fallbacks: the direct-checkout path in // addWorktreeForBranch checks out the local branch, and so do // handleFetchFallback and the non-current-branch path in resolveLocalBaseRef. func (m *Manager) resolveRetryStartPoint(ctx context.Context, repoPath, branch string) *FetchBranchResult { remoteRef := "origin/" + branch remoteContainsLocal, remoteErr := m.refContains(ctx, repoPath, remoteRef, branch) if remoteErr == nil && remoteContainsLocal { return &FetchBranchResult{StartPoint: remoteRef} } m.logger.Info("using local branch (remote-tracking ref does not contain all local commits)", zap.String("branch", branch), zap.String("remote_ref", remoteRef)) // Being ahead of the remote ref costs the worktree nothing — the local // branch is then a strict superset, so there is nothing to warn about. // Every other shape does: the refs have diverged, or the probe could not // answer (origin/ absent because the remote has no standard fetch // refspec, or the probe itself was bounded). In those cases the worktree // really may miss commits that are on origin, so the existing FetchWarning // surface has to say so rather than report a clean success. The wording // covers both, because this branch cannot tell them apart. localContainsRemote, localErr := m.refContains(ctx, repoPath, branch, remoteRef) if localErr == nil && localContainsRemote { return &FetchBranchResult{} } warningDetail := fmt.Sprintf("git merge-base --is-ancestor %s %s reported non-zero", branch, remoteRef) if remoteErr != nil || localErr != nil { warningDetail = "git merge-base ancestry could not be verified" } return &FetchBranchResult{ Warning: fmt.Sprintf( "Could not confirm that %s contains every commit on local branch %q. Using the local version so unpushed commits are kept; it may not include the latest changes from origin.", remoteRef, branch), // No git command failed here, so there is no raw output to carry: the // probe ran and answered "no" (or could not answer). Name the probe // rather than inventing a fake error string. WarningDetail: warningDetail, } } // gitAddWorktreeExisting creates a worktree that checks out an existing local branch. // If the branch is already checked out in a stale worktree (directory no longer exists), // it automatically prunes and retries. If the repository uses git-crypt, it creates // the worktree without checkout, then unlocks git-crypt and performs the checkout. func (m *Manager) gitAddWorktreeExisting(ctx context.Context, repoPath, branchName, worktreePath string) (string, error) { return m.gitAddWorktreeExistingAtRef(ctx, repoPath, branchName, worktreePath, "") } // gitAddWorktreeExistingAtRef creates a worktree for an existing branch at a // selected start point. A non-empty start point resets the branch with git's // -B worktree option, which is safe here because the caller has already proved // that the refreshed remote contains the old local branch. func (m *Manager) gitAddWorktreeExistingAtRef(ctx context.Context, repoPath, branchName, worktreePath, startPoint string) (string, error) { release, err := acquireWorktreeTargetPath(ctx, worktreePath) if err != nil { return "", fmt.Errorf("acquire worktree target path: %w", err) } defer release() return m.gitAddWorktreeExistingLocked(ctx, repoPath, branchName, worktreePath, startPoint) } func (m *Manager) gitAddWorktreeExistingLocked(ctx context.Context, repoPath, branchName, worktreePath, startPoint string) (string, error) { worktreeID := uuid.New().String() usesGitCrypt := m.usesGitCrypt(repoPath) // Build worktree add command args := []string{"worktree", "add"} if startPoint != "" { args = append(args, "-B", branchName) } if usesGitCrypt { args = append(args, "--no-checkout") } args = append(args, worktreePath) if startPoint == "" { args = append(args, branchName) } else { args = append(args, startPoint) } cmd := newGitCommand(ctx, args...) cmd.Dir = repoPath output, err := runGitCmdCombinedOutput(ctx, cmd) if err == nil { if usesGitCrypt { if unlockErr := m.unlockGitCryptAndCheckout(ctx, worktreePath); unlockErr != nil { _ = m.removeWorktreeDir(ctx, worktreePath, repoPath) return "", unlockErr } } else { m.initSubmodules(ctx, worktreePath) } return worktreeID, nil } outStr := string(output) // Check for git-crypt smudge error and retry with --no-checkout if isGitCryptSmudgeError(outStr) && !usesGitCrypt { m.logger.Warn("git-crypt smudge error detected, retrying with --no-checkout", zap.String("output", outStr)) return m.gitAddWorktreeExistingWithGitCrypt(ctx, repoPath, branchName, worktreePath, startPoint) } if !isBranchCheckedOutError(outStr) { m.logger.Error("git worktree add (existing branch) failed", zap.String("output", outStr), zap.Error(err)) return "", ClassifyGitError(outStr, err) } if recoveryErr := m.tryRecoverCheckedOutBranch(ctx, repoPath, branchName, outStr); recoveryErr != nil { m.logger.Warn("branch is checked out in active worktree", zap.String("branch", branchName), zap.Error(recoveryErr)) return "", ErrBranchCheckedOut } // Retry after pruning stale worktree return m.retryWorktreeExisting(ctx, repoPath, branchName, worktreePath, usesGitCrypt, startPoint) } // retryWorktreeExisting retries worktree creation after pruning stale worktrees. func (m *Manager) retryWorktreeExisting(ctx context.Context, repoPath, branchName, worktreePath string, usesGitCrypt bool, startPoint string) (string, error) { worktreeID := uuid.New().String() args := []string{"worktree", "add"} if startPoint != "" { args = append(args, "-B", branchName) } if usesGitCrypt { args = append(args, "--no-checkout") } args = append(args, worktreePath) if startPoint == "" { args = append(args, branchName) } else { args = append(args, startPoint) } retryCmd := newGitCommand(ctx, args...) retryCmd.Dir = repoPath retryOutput, retryErr := runGitCmdCombinedOutput(ctx, retryCmd) if retryErr != nil { retryOutStr := string(retryOutput) if isBranchCheckedOutError(retryOutStr) { return "", ErrBranchCheckedOut } m.logger.Error("git worktree add retry failed", zap.String("output", retryOutStr), zap.Error(retryErr)) return "", ClassifyGitError(retryOutStr, retryErr) } if usesGitCrypt { if err := m.unlockGitCryptAndCheckout(ctx, worktreePath); err != nil { _ = m.removeWorktreeDir(ctx, worktreePath, repoPath) return "", err } } else { m.initSubmodules(ctx, worktreePath) } m.logger.Info("recovered from stale worktree checkout", zap.String("branch", branchName)) return worktreeID, nil } // gitAddWorktreeExistingWithGitCrypt creates a worktree for an existing branch // using --no-checkout, then unlocks git-crypt. Used as fallback when smudge error detected. func (m *Manager) gitAddWorktreeExistingWithGitCrypt(ctx context.Context, repoPath, branchName, worktreePath, startPoint string) (string, error) { worktreeID := uuid.New().String() args := []string{"worktree", "add"} if startPoint != "" { args = append(args, "-B", branchName) } args = append(args, "--no-checkout", worktreePath) if startPoint == "" { args = append(args, branchName) } else { args = append(args, startPoint) } cmd := newGitCommand(ctx, args...) cmd.Dir = repoPath output, err := runGitCmdCombinedOutput(ctx, cmd) if err != nil { outStr := string(output) if isBranchCheckedOutError(outStr) { return "", ErrBranchCheckedOut } m.logger.Error("git worktree add (--no-checkout, existing) failed", zap.String("output", outStr), zap.Error(err)) return "", ClassifyGitError(outStr, err) } if err := m.unlockGitCryptAndCheckout(ctx, worktreePath); err != nil { _ = m.removeWorktreeDir(ctx, worktreePath, repoPath) return "", err } return worktreeID, nil } // tryRecoverCheckedOutBranch attempts to recover from "branch is already checked out" // by pruning stale worktrees. Returns nil if recovery succeeded, error otherwise. func (m *Manager) tryRecoverCheckedOutBranch(ctx context.Context, repoPath, branchName, gitOutput string) error { // Parse the path from git output: "fatal: 'branch' is already checked out at '/path/to/worktree'" checkedOutPath := parseCheckedOutPath(gitOutput) if checkedOutPath == "" { return fmt.Errorf("could not parse worktree path from git output") } // Check if the worktree directory still exists on disk. if _, err := os.Stat(checkedOutPath); err == nil { // Directory exists — worktree is genuinely in use, can't recover. m.logger.Warn("branch checked out in active worktree, cannot recover", zap.String("branch", branchName), zap.String("worktree_path", checkedOutPath)) return fmt.Errorf("worktree at %s is still active", checkedOutPath) } // Directory is gone — prune stale worktree references. m.logger.Info("pruning stale worktree reference", zap.String("branch", branchName), zap.String("stale_path", checkedOutPath)) pruneCmd := newGitCommand(ctx, "worktree", "prune") pruneCmd.Dir = repoPath if output, err := runGitCmdCombinedOutput(ctx, pruneCmd); err != nil { m.logger.Error("git worktree prune failed", zap.String("output", string(output)), zap.Error(err)) return fmt.Errorf("worktree prune failed: %w", err) } return nil } // parseCheckedOutPath extracts the worktree path from git's error message. // Handles both "is already checked out at '/path'" and "is already used by worktree at '/path'". func parseCheckedOutPath(gitOutput string) string { for _, marker := range []string{"checked out at '", "used by worktree at '"} { _, after, found := strings.Cut(gitOutput, marker) if found { path, _, ok := strings.Cut(after, "'") if ok { return path } } } return "" } // buildWorktreeNames derives the filesystem directory name and git branch name for a new worktree. func (m *Manager) buildWorktreeNames(req CreateRequest) (dirName, branchName string) { dirSuffix := uuid.New().String()[:8] // Use first 8 chars of UUID for worktree dir uniqueness branchSuffix := SmallSuffix(3) if req.TaskTitle != "" { // Use semantic naming: {sanitized-title}_{suffix} dirName = SemanticWorktreeName(req.TaskTitle, dirSuffix) } else { // Fallback to task ID based naming dirName = req.TaskID + "_" + dirSuffix } branchName = TaskBranchNameWithSuffix(req.TaskTitle, req.TaskID, req.WorktreeBranchPrefix, branchSuffix) if req.WorktreeBranchTemplate != "" { if rendered, err := RenderTaskBranchName(BranchNameTemplateInput{ Template: req.WorktreeBranchTemplate, TaskID: req.TaskID, Title: req.TaskTitle, Ticket: req.WorktreeBranchTicket, Suffix: branchSuffix, }); err == nil { branchName = rendered } else { m.logger.Warn("worktree branch template render failed; using fallback branch name", zap.String("task_id", req.TaskID), zap.String("template", req.WorktreeBranchTemplate), zap.Error(err)) } } return dirName, branchName } type newBranchAddSnapshot struct { branchRef string branchOID string } func (m *Manager) createNewBranchRef( ctx context.Context, repoPath, branchName, baseRef string, ) (newBranchAddSnapshot, error) { resolveCmd := newGitCommand(ctx, "rev-parse", "--verify", baseRef+"^{commit}") resolveCmd.Dir = repoPath output, err := runGitCmdOutput(ctx, resolveCmd) if err != nil { return newBranchAddSnapshot{}, ClassifyGitError(string(output), err) } oid := strings.TrimSpace(string(output)) if oid == "" { return newBranchAddSnapshot{}, fmt.Errorf("%w: base ref %q resolved to an empty object ID", ErrGitCommandFailed, baseRef) } ownership := newBranchAddSnapshot{branchRef: "refs/heads/" + branchName} zeroOID := strings.Repeat("0", len(oid)) createCmd := newGitCommand(ctx, "update-ref", ownership.branchRef, oid, zeroOID) createCmd.Dir = repoPath createOutput, createErr := runGitCmdCombinedOutput(ctx, createCmd) if createErr != nil { if strings.Contains(strings.ToLower(string(createOutput)), "reference already exists") { return newBranchAddSnapshot{}, fmt.Errorf("%w: %s", ErrBranchExists, strings.TrimSpace(string(createOutput))) } return newBranchAddSnapshot{}, ClassifyGitError(string(createOutput), createErr) } ownership.branchOID = oid return ownership, nil } func deleteBranchRefIfOwned(ctx context.Context, repoPath string, snapshot newBranchAddSnapshot) ([]byte, error) { cmd := newGitCommand(ctx, "update-ref", "-d", snapshot.branchRef, snapshot.branchOID) cmd.Dir = repoPath return runGitCmdCombinedOutput(ctx, cmd) } func restoreBranchRefIfDeleted(ctx context.Context, repoPath string, snapshot newBranchAddSnapshot) ([]byte, error) { cmd := newGitCommand(ctx, "update-ref", snapshot.branchRef, snapshot.branchOID, strings.Repeat("0", len(snapshot.branchOID))) cmd.Dir = repoPath return runGitCmdCombinedOutput(ctx, cmd) } func (m *Manager) rollbackFailedNewBranchAdd( ctx context.Context, repoPath, branchName, worktreePath string, snapshot newBranchAddSnapshot, ) { if snapshot.branchRef == "" || snapshot.branchOID == "" { return } cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), m.inspectTimeout) defer cancel() registrationOwnership, inspectErr := inspectWorktreeRegistrationOwnership( cleanupCtx, repoPath, worktreePath, snapshot.branchRef, snapshot.branchOID, ) if inspectErr != nil { m.logger.Warn("failed to verify partial worktree ownership; leaving path untouched", zap.String("path", worktreePath), zap.Error(inspectErr)) return } switch registrationOwnership { case worktreeRegistrationAbsent: // git may fail before it registers a worktree (for example when the // target is non-empty). The branch was created with a zero-OID CAS, so // this matching delete only removes our still-unmodified ref. Never // touch the target path: it was not registered as ours. if output, err := deleteBranchRefIfOwned(cleanupCtx, repoPath, snapshot); err != nil { m.logger.Warn("failed to roll back unregistered worktree branch", zap.String("branch", branchName), zap.String("output", string(output)), zap.Error(err)) } return case worktreeRegistrationCompeting: return case worktreeRegistrationOwned: // Continue below. default: return } // Delete the exact ref while the owned worktree registration still blocks // ordinary competing checkouts. The expected old OID preserves an advanced // or replaced ref; failure leaves both the ref and worktree untouched. if output, err := deleteBranchRefIfOwned(cleanupCtx, repoPath, snapshot); err != nil { m.logger.Warn("failed to roll back worktree branch", zap.String("branch", branchName), zap.String("output", string(output)), zap.Error(err)) return } removeErr := m.removeWorktreeDir(cleanupCtx, worktreePath, repoPath) registrationOwnership, inspectErr = inspectWorktreeRegistrationOwnership( cleanupCtx, repoPath, worktreePath, snapshot.branchRef, snapshot.branchOID, ) // Git's removal command can report an error even when its filesystem/prune // fallback completed the registration cleanup. The post-cleanup ownership // inspection is authoritative for whether deleting the ref remains safe. if inspectErr == nil && registrationOwnership == worktreeRegistrationAbsent { return } if removeErr != nil { m.logger.Warn("failed to roll back partial worktree", zap.String("path", worktreePath), zap.Error(removeErr)) } if inspectErr != nil { m.logger.Warn("failed to verify worktree registration after partial cleanup", zap.String("path", worktreePath), zap.Error(inspectErr)) } else { m.logger.Warn("partial worktree registration remains after cleanup", zap.String("path", worktreePath), zap.Uint8("registration_ownership", uint8(registrationOwnership))) } // A branch registration prevents ordinary worktree creation from adopting // this ref while cleanup runs. If cleanup did not prove that registration // is gone, restore the exact OID with a zero-OID CAS before returning so a // registered worktree can never be left pointing at a missing branch. if output, err := restoreBranchRefIfDeleted(cleanupCtx, repoPath, snapshot); err != nil { m.logger.Warn("failed to restore branch after partial worktree cleanup", zap.String("branch", branchName), zap.String("output", string(output)), zap.Error(err)) } } // gitAddWorktree runs "git worktree add" and returns the new worktree UUID. // If the repository uses git-crypt, it creates the worktree without checkout, // then unlocks git-crypt and performs the checkout separately. func (m *Manager) gitAddWorktree(ctx context.Context, repoPath, branchName, worktreePath, baseRef string) (string, error) { release, err := acquireWorktreeTargetPath(ctx, worktreePath) if err != nil { return "", fmt.Errorf("acquire worktree target path: %w", err) } defer release() return m.gitAddWorktreeLocked(ctx, repoPath, branchName, worktreePath, baseRef) } func (m *Manager) gitAddWorktreeLocked(ctx context.Context, repoPath, branchName, worktreePath, baseRef string) (string, error) { worktreeID := uuid.New().String() usesGitCrypt := m.usesGitCrypt(repoPath) addSnapshot, err := m.createNewBranchRef(ctx, repoPath, branchName, baseRef) if err != nil { return "", err } args := []string{"worktree", "add"} if usesGitCrypt { args = append(args, "--no-checkout") } args = append(args, worktreePath, branchName) cmd := newGitCommand(ctx, args...) cmd.Dir = repoPath output, err := runGitCmdCombinedOutput(ctx, cmd) if err != nil { outStr := string(output) m.rollbackFailedNewBranchAdd(ctx, repoPath, branchName, worktreePath, addSnapshot) // Check if this is a git-crypt error we didn't anticipate if isGitCryptSmudgeError(outStr) { m.logger.Warn("git-crypt smudge error detected, retrying with --no-checkout", zap.String("output", outStr)) return m.gitAddWorktreeWithGitCryptLocked(ctx, repoPath, branchName, worktreePath, baseRef) } m.logger.Error("git worktree add failed", zap.String("output", outStr), zap.Error(err)) return "", ClassifyGitError(outStr, err) } // If we used --no-checkout, we need to unlock git-crypt and checkout if usesGitCrypt { if err := m.unlockGitCryptAndCheckout(ctx, worktreePath); err != nil { m.rollbackFailedNewBranchAdd(ctx, repoPath, branchName, worktreePath, addSnapshot) return "", err } } else { m.initSubmodules(ctx, worktreePath) } return worktreeID, nil } // gitAddWorktreeWithGitCrypt creates a worktree using --no-checkout and then // unlocks git-crypt. This is used as a fallback when we detect a git-crypt // smudge filter error. func (m *Manager) gitAddWorktreeWithGitCryptLocked(ctx context.Context, repoPath, branchName, worktreePath, baseRef string) (string, error) { worktreeID := uuid.New().String() addSnapshot, err := m.createNewBranchRef(ctx, repoPath, branchName, baseRef) if err != nil { return "", err } cmd := newGitCommand(ctx, "worktree", "add", "--no-checkout", worktreePath, branchName) cmd.Dir = repoPath output, err := runGitCmdCombinedOutput(ctx, cmd) if err != nil { m.rollbackFailedNewBranchAdd(ctx, repoPath, branchName, worktreePath, addSnapshot) m.logger.Error("git worktree add (--no-checkout) failed", zap.String("output", string(output)), zap.Error(err)) return "", ClassifyGitError(string(output), err) } // Unlock git-crypt and checkout if err := m.unlockGitCryptAndCheckout(ctx, worktreePath); err != nil { m.rollbackFailedNewBranchAdd(ctx, repoPath, branchName, worktreePath, addSnapshot) return "", err } return worktreeID, nil } // gitAddWorktreeForRecreate runs "git worktree add" against an existing branch // for the recreate path, retrying with --no-checkout when a git-crypt smudge // error is detected. Returns the effective usesGitCrypt flag (forced to true // if the retry path was taken so the caller knows to unlock+checkout). func (m *Manager) gitAddWorktreeForRecreate(ctx context.Context, repoPath, branch, worktreePath, startPoint string) (bool, error) { release, err := acquireWorktreeTargetPath(ctx, worktreePath) if err != nil { return false, fmt.Errorf("acquire worktree target path: %w", err) } defer release() return m.gitAddWorktreeForRecreateLocked(ctx, repoPath, branch, worktreePath, startPoint) } func (m *Manager) gitAddWorktreeForRecreateLocked(ctx context.Context, repoPath, branch, worktreePath, startPoint string) (bool, error) { usesGitCrypt := m.usesGitCrypt(repoPath) args := []string{"worktree", "add"} if startPoint != "" { args = append(args, "-B", branch) } if usesGitCrypt { args = append(args, "--no-checkout") } args = append(args, worktreePath) if startPoint == "" { args = append(args, branch) } else { args = append(args, startPoint) } cmd := newGitCommand(ctx, args...) cmd.Dir = repoPath output, err := runGitCmdCombinedOutput(ctx, cmd) if err == nil { return usesGitCrypt, nil } outStr := string(output) if isGitCryptSmudgeError(outStr) && !usesGitCrypt { m.logger.Warn("git-crypt smudge error during recreate, retrying with --no-checkout", zap.String("output", outStr)) retryArgs := []string{"worktree", "add"} if startPoint != "" { retryArgs = append(retryArgs, "-B", branch) } retryArgs = append(retryArgs, "--no-checkout", worktreePath) if startPoint == "" { retryArgs = append(retryArgs, branch) } else { retryArgs = append(retryArgs, startPoint) } retryCmd := newGitCommand(ctx, retryArgs...) retryCmd.Dir = repoPath if retryOutput, retryErr := runGitCmdCombinedOutput(ctx, retryCmd); retryErr != nil { m.logger.Error("failed to recreate worktree (--no-checkout)", zap.String("output", string(retryOutput)), zap.Error(retryErr)) return false, ClassifyGitError(string(retryOutput), retryErr) } return true, nil // Force unlock/checkout } m.logger.Error("failed to recreate worktree", zap.String("output", outStr), zap.Error(err)) return false, ClassifyGitError(outStr, err) } // copyConfiguredFiles copies user-specified files from the source repo into // the freshly created worktree, recording the resulting file list and // warnings on wt for the env preparer to surface. Failures are logged but // never propagated — worktree creation must succeed even if file seeding // partially fails. func (m *Manager) copyConfiguredFiles(ctx context.Context, req CreateRequest, wt *Worktree) { if m.repoProvider == nil || req.RepositoryID == "" { return } repo, err := m.repoProvider.GetRepository(ctx, req.RepositoryID) if err != nil { m.logger.Warn("copy-files: failed to fetch repository", zap.String("repository_id", req.RepositoryID), zap.Error(err)) return } if repo == nil || repo.CopyFiles == "" { return } specs := copyfiles.ParseSpecs(repo.CopyFiles) if len(specs) == 0 { return } copied, warnings, err := copyfiles.Copy(ctx, req.RepositoryPath, wt.Path, specs, m.logger.Zap()) if err != nil { m.logger.Warn("worktree copy-files failed", zap.String("session_id", req.SessionID), zap.String("repo_id", req.RepositoryID), zap.Error(err)) } for _, w := range warnings { m.logger.Warn("worktree copy-files warning", zap.String("repo_id", req.RepositoryID), zap.String("path", wt.Path), zap.String("warning", w)) } wt.CopiedFiles = copied wt.CopyFilesWarnings = warnings } // removeRecreatedWorktreePath deletes only a managed worktree path through // no-follow directory handles. Legacy paths outside tasksBase retain their // existing behavior because they are not controlled by the managed root. func (m *Manager) removeRecreatedWorktreePath(ctx context.Context, worktreePath string) error { tasksBase, err := m.config.ExpandedTasksBasePath() if err != nil { return fmt.Errorf("resolve tasks base path for recreate removal: %w", err) } tasksBase = filepath.Clean(tasksBase) relativePath, err := filepath.Rel(tasksBase, worktreePath) if err != nil || relativePath == "." || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) { if err := os.RemoveAll(worktreePath); err != nil { return fmt.Errorf("remove existing worktree path: %w", err) } return nil } if err := storageworkspaces.RemoveDirectoryNoFollow(ctx, tasksBase, worktreePath); err != nil && !errors.Is(err, os.ErrNotExist) { return fmt.Errorf("remove existing worktree path without following links: %w", err) } return nil } // restoreMissingTasksBaseForRecreate rebuilds the task-root directory only when // the configured managed base disappeared. The persisted task directory name // fixes the root identity, while a fresh symlink validation protects the newly // created path before Git is allowed to populate it. func (m *Manager) restoreMissingTasksBaseForRecreate(worktreePath string, existing *Worktree) error { tasksBase, err := m.config.ExpandedTasksBasePath() if err != nil { return fmt.Errorf("resolve tasks base path for recreate: %w", err) } tasksBase = filepath.Clean(tasksBase) relativePath, err := filepath.Rel(tasksBase, worktreePath) if err != nil || relativePath == "." || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) { return nil } if _, err := os.Lstat(tasksBase); !errors.Is(err, os.ErrNotExist) { if err != nil { return fmt.Errorf("inspect tasks base path for recreate: %w", err) } return nil } taskDirName := strings.SplitN(relativePath, string(filepath.Separator), 2)[0] if existing.TaskDirName != "" && existing.TaskDirName != taskDirName { return fmt.Errorf("cannot recreate worktree: persisted task root %q does not match path root %q", existing.TaskDirName, taskDirName) } taskRoot := filepath.Join(tasksBase, taskDirName) // Build the missing base and task root through no-follow directory handles. // This keeps a concurrent replacement of tasksBase from redirecting marker // creation into an external directory. taskRootHandle, err := storageworkspaces.CreateDirectoryNoFollow(tasksBase, taskRoot, 0o755) if err != nil { return fmt.Errorf("recreate missing tasks base: %w", err) } defer func() { _ = taskRootHandle.Close() }() if err := taskRootHandle.VerifyPath(taskRoot); err != nil { return fmt.Errorf("recreated task root changed during recovery: %w", err) } markerTaskDirName := taskDirName if err := storageworkspaces.WriteOwnershipMarkerNoFollow(taskRootHandle, storageworkspaces.OwnershipMarker{ TaskID: existing.TaskID, TaskDirName: markerTaskDirName, LayoutVersion: storageworkspaces.LayoutVersionSemantic, }); err != nil { return fmt.Errorf("mark recreated task directory ownership: %w", err) } return nil } // recreate recreates a worktree from stored metadata. func (m *Manager) recreate(ctx context.Context, existing *Worktree, req CreateRequest) (*Worktree, error) { if err := m.refreshRepositoryForMaterialization(ctx, &req); err != nil { return nil, err } fallbackWarning := req.baseRefreshFallbackWarning fallbackDetail := req.baseRefreshFallbackDetail // Recreate bypasses the new-worktree path, so perform the same required // base refresh before touching the existing worktree path. A failed refresh // must leave the retryable on-disk state intact. if req.PullBeforeWorktree && !req.RemoteSyncHandled { refreshReq := req _, warning, detail, err := m.resolveBaseRefWithFallback(ctx, &refreshReq) if err != nil { return nil, err } if warning != "" { fallbackWarning = warning fallbackDetail = detail } } // Clean up the recorded directory through no-follow descriptors. Reuse // validation can race with a local rename, so path-based RemoveAll here // could otherwise be redirected into another task root. if existing.Path != "" { if err := m.removeRecreatedWorktreePath(ctx, existing.Path); err != nil { return nil, err } } // Remove from git worktree list cmd := newGitCommand(ctx, "worktree", "prune") cmd.Dir = req.RepositoryPath if err := runGitCmd(ctx, cmd); err != nil { m.logger.Debug("git worktree prune failed", zap.Error(err)) } // Get repository lock repoLock := m.getRepoLock(req.RepositoryPath) repoLock.Lock() defer func() { repoLock.Unlock() m.releaseRepoLock(req.RepositoryPath) }() emptyRemoteBaseRef, err := m.ensureEmptyRemoteBaseline(ctx, &req) if err != nil { return nil, err } // Reuse the original on-disk path so the worktree is recreated in the // same task-dir slot it was first created in. worktreePath := existing.Path if worktreePath == "" { return nil, fmt.Errorf("cannot recreate worktree: existing record has no path") } if err := m.restoreMissingTasksBaseForRecreate(worktreePath, existing); err != nil { return nil, err } // Archive deletes the local branch (removeWorktree runs `git branch -D`), // so a recreate after unarchive must restore it first. fetchBranchToLocal // fetches origin : — or pull//head for fork PRs, whose // head branch never exists on origin by name — and only errors when the // branch exists neither locally nor on the remote. exists, probeErr := m.branchExists(ctx, req.RepositoryPath, existing.Branch) if probeErr != nil { // "Could not tell" (timeout / fs stall) is not "missing" — reporting // ErrBranchUnrecoverable here would misclassify recoverable work as // gone. Propagate so the caller can retry the recreate. return nil, fmt.Errorf("cannot verify worktree branch %q: %w", existing.Branch, probeErr) } contributionRemote := "" contributionRef := "" if req.RemoteContribution != nil { var materializeErr error contributionRemote, contributionRef, materializeErr = m.materializeRemoteContribution(ctx, req.RepositoryPath, req.RemoteContribution) if materializeErr != nil { return nil, materializeErr } } refreshedStartPoint := "" if req.RemoteSyncHandled && req.RemoteContribution == nil && emptyRemoteBaseRef == "" { sourceBranch := recreateSourceBranch(existing.Branch, req.CheckoutBranch) selectedRef, prepareErr := m.prepareBranchFromRefreshedOrigin( ctx, req.RepositoryPath, existing.Branch, sourceBranch, req.PRNumber, ) if prepareErr != nil { return nil, prepareErr } if selectedRef == "" && !req.AllowBranchReplacement { err := &BranchUnrecoverableError{Branch: sourceBranch} return nil, fmt.Errorf("%w: refreshed branch %q was not materialized", err, sourceBranch) } if selectedRef == "" { return m.replaceUnrecoverableWorktree( ctx, existing, req, &BranchUnrecoverableError{Branch: sourceBranch}, ) } if selectedRef != existing.Branch { refreshedStartPoint = selectedRef } exists = true } if !exists { if req.RemoteContribution != nil { branchCmd := m.newNonInteractiveGitCmd(ctx, req.RepositoryPath, "branch", existing.Branch, contributionRef) if output, branchErr := runGitCmdCombinedOutput(ctx, branchCmd); branchErr != nil { return nil, fmt.Errorf("restore contribution branch: %s: %w", strings.TrimSpace(string(output)), branchErr) } } else if emptyRemoteBaseRef != "" { branchCmd := m.newNonInteractiveGitCmd(ctx, req.RepositoryPath, "branch", existing.Branch, emptyRemoteBaseRef) if output, branchErr := runGitCmdCombinedOutput(ctx, branchCmd); branchErr != nil { return nil, fmt.Errorf("restore empty-remote worktree branch: %s: %w", strings.TrimSpace(string(output)), branchErr) } } else { fetchResult, fetchErr := m.fetchBranchToLocalWithPolicy( ctx, req.RepositoryPath, existing.Branch, req.PRNumber, req.PullBeforeWorktree && !req.RemoteSyncHandled, ) if fetchErr != nil { m.logger.Warn("failed to restore worktree branch during recreate", zap.String("worktree_id", existing.ID), zap.String("branch", existing.Branch), zap.Error(fetchErr)) // Only a confirmed-missing remote ref means the work is gone; // transient fetch failures (network, auth) keep their own error // so callers don't treat a reachable branch as unrecoverable. if errors.Is(fetchErr, ErrRemoteRefMissing) || isRemoteRefMissingError(fetchErr) { err := &BranchUnrecoverableError{Branch: existing.Branch} if req.AllowBranchReplacement { return m.replaceUnrecoverableWorktree(ctx, existing, req, err) } return nil, err } return nil, fetchErr } if fetchResult != nil && fetchResult.StartPoint != "" { branchCmd := m.newNonInteractiveGitCmd(ctx, req.RepositoryPath, "branch", existing.Branch, fetchResult.StartPoint) if output, branchErr := runGitCmdCombinedOutput(ctx, branchCmd); branchErr != nil { return nil, fmt.Errorf("restore worktree branch from refreshed ref: %s: %w", strings.TrimSpace(string(output)), branchErr) } exists = true } } } if exists && req.RemoteContribution != nil { branchRef := "refs/heads/" + existing.Branch if err := m.validateContributionAncestor(ctx, req.RepositoryPath, req.RemoteContribution.HeadSHA, branchRef); err != nil { return nil, fmt.Errorf("existing contribution branch is not based on the validated source: %w", err) } } // Try to add worktree using existing branch usesGitCrypt, err := m.gitAddWorktreeForRecreate(ctx, req.RepositoryPath, existing.Branch, worktreePath, refreshedStartPoint) if err != nil { return nil, err } // If using git-crypt, unlock and checkout if usesGitCrypt { if err := m.unlockGitCryptAndCheckout(ctx, worktreePath); err != nil { _ = m.removeWorktreeDir(ctx, worktreePath, req.RepositoryPath) return nil, err } } else { m.initSubmodules(ctx, worktreePath) } if contributionRemote != "" { if err := m.setUpstreamIfExistsRemote(ctx, worktreePath, existing.Branch, contributionRemote, req.RemoteContribution.HeadBranch); err != nil { _ = m.removeWorktreeDir(ctx, worktreePath, req.RepositoryPath) return nil, err } } // Update record. DeletedAt must be cleared alongside the status: archive // cleanup releases the reference (status=deleted + deleted_at), and // UpdateWorktree persists deleted_at verbatim — leaving it set would keep // the freshly recreated worktree invisible to every lookup that filters on // `deleted_at IS NULL`, so the next launch would mint a brand-new worktree // beside the one we just restored. now := time.Now() existing.Path = worktreePath existing.Status = StatusActive existing.DeletedAt = nil existing.UpdatedAt = now existing.BaseBranchFallbackWarning = fallbackWarning existing.BaseBranchFallbackDetail = fallbackDetail if m.store != nil { if err := m.store.UpdateWorktree(ctx, existing); err != nil { return nil, fmt.Errorf("failed to update worktree record: %w", err) } } // Update cache keyed by (sessionID, repositoryID, branchSlug). if req.SessionID != "" { m.mu.Lock() m.worktrees[cacheKey(req.SessionID, req.RepositoryID, existing.BranchSlug)] = existing m.mu.Unlock() } m.logger.Info("recreated worktree", zap.String("session_id", req.SessionID), zap.String("task_id", req.TaskID), zap.String("path", worktreePath)) return existing, nil }