Research stale upstream guards for worktree branch creation

[IgorWarzocha]

Research question

How should Howcode prevent users from creating or continuing worktrees from stale local branches when the upstream branch is ahead?

Context

This came up while developing Howcode inside Howcode. A new automations worktree/branch was created from a local checkout that looked plausible in the sidebar, but the branch had actually forked from an old local dev lineage. The resulting branch was far ahead of current origin/main / origin/dev and behind upstream at the same time.

The current worktree flow appears to correctly use Git state. The risk is not that SQLite invents a branch; it is that the UI can make a stale local branch feel safe to branch from or continue from.

Deliverable

• Decide where Howcode should surface stale/diverged upstream state before branch/worktree creation.
• Propose the least annoying UX for warning or blocking risky worktree creation.
• Identify the code paths that need protection, especially:
  • creating a worktree from a branch row
  • starting work from an existing same-name local branch
  • switching/opening an existing worktree whose parent branch is behind upstream

Acceptance criteria

• The recommendation distinguishes stale local checkout state from stale DB/project metadata.
• The proposal covers both main/dev parent branches and arbitrary tracked branches.
• Same-name branch behavior is explicit: the UI should tell the user when it is reusing an existing local branch instead of creating a fresh branch.
• The chosen approach avoids noisy warnings for normal offline/local-only repos.
• Follow-up implementation issues can be split from the recommendation.

Notes

Possible directions:

• Fetch/compare before creating a worktree from a tracked branch.
• Show behind origin/dev by N / diverged indicators in the project/worktree sidebar.
• Warn when a new worktree would be based on a branch whose upstream is ahead.
• For same-name branches, show “Using existing local branch” vs “Creating new branch”.
• Add a safe “update parent first” affordance when appropriate.