Enable cross-worktree rebase and sync

[skarim]

Enables gh stack rebase and gh stack sync to update branches checked out in different worktrees. Building on shared tracking from #528, each change runs in the checkout that holds the branch, so users no longer need to move the whole stack into one directory.

Functionality and user impact

• Check affected worktrees for uncommitted files or unfinished Git operations before rewriting branches. Branches not checked out anywhere use the starting worktree, which returns to its original branch afterward. Other worktrees keep their branch selections.
• Name the checkout where conflicts must be resolved and staged. --continue and --abort can run from any worktree because a shared recovery file records where the operation ran and what it changed. If recovery cannot finish, keep that file for another attempt.
• Fast-forward the trunk in its checkout when safe; otherwise use the fetched remote trunk without changing the local one. Pruning skips branches checked out elsewhere. If a stack rebase fails during sync, restore its changes before pushing; a failed restore also stops the push.

Boundary: rollback covers the stack rebases, not earlier fetches or completed fast-forwards. Requires Git 2.36+, with no automatic stashing or worktree creation/removal. Distributed modify follows in #521. Operations paused on the earlier origin-only version must finish with that matching build.

Key areas to review

• cmd/rebase.go / cmd/sync.go: runRebase and runSync identify the worktrees needed before changing branches. Follow sync's error handling to ensure it does not push partial results or prune a branch still checked out elsewhere.
• cmd/utils.go: planFastForwardBranches, fastForwardBranches, and resolveTrunkTarget choose which branches can advance. rebaseStep / cascadeRebase choose the commits to replay and save progress before invoking Git.
• cmd/rebase_worktree.go: continueWorktreeRebase, rollbackWorktreeRebase, and publishCompletedRebase resume or undo the recorded work, then save the catalog before removing the recovery file. Incompatible recovery records are rejected in cmd/rebase.go before reaching these functions.
• internal/worktree/context.go: Prepare, Start, Record, and Restore track the branch commits before and after each change. Abort uses these records rather than blindly resetting every branch in the stack.
• internal/git/git.go: rebaseArgs disables automatic maintenance for rebase commands so background rerere gc cannot race conflict handling. Repository settings and unrelated Git commands are unchanged.

Related issues

• Github stack does not persist across worktrees #459
• gh stack rebase silently succeeds when git rebase --onto fails to start (in branch checked out in another worktree) #35
• sync might not work with worktree #87

Part 4 of the 4-PR split of #520

[Copilot]

Copilot review overview

🟡 Changes recommended

Legacy recovery can clear journals after partial restoration, and ambiguous stack selection can lose the caller’s original checkout.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Retain journal when reference restoration fails · New
• Preserve original checkout before mutating stack selection · New
• Restore phase validation for legacy rebase journals · New

What changed in this PR

Enables rebase and sync to safely operate across multiple Git worktrees with shared recovery state.

Changes:

• Adds owner-scoped rebase execution, continuation, rollback, and pruning.
• Pins trunk targets and disables automatic Git maintenance during rebases.
• Updates tests and documentation for distributed workflows.

File	Description
cmd/​rebase.go	Routes distributed rebase and recovery.
cmd/​rebase_worktree.go	Implements worktree-aware recovery.
cmd/​rebase_test.go	Tests distributed rebase behavior.
cmd/​sync.go	Adds cross-worktree sync and pruning.
cmd/​sync_test.go	Tests distributed sync and rollback.
cmd/​utils.go	Adds scoped fast-forward and cascade helpers.
cmd/​trunk_target_test.go	Updates trunk and rollback tests.
cmd/​worktree_utils.go	Validates shared recovery journals.
internal/​worktree/​context.go	Supports owner-scoped operations.
internal/​git/​git.go	Disables maintenance during rebases.
internal/​git/​gitops_test.go	Verifies maintenance isolation.
internal/​git/​worktree_test.go	Updates rebase argument expectations.
internal/​stack/​lock.go	Clarifies operation-lock behavior.
internal/​config/​config.go	Simplifies mutation context.
README.md	Documents cross-worktree operation.
docs/​src/​content/​docs/​reference/​cli.md	Updates CLI recovery guidance.
docs/​src/​content/​docs/​guides/​workflows.md	Documents distributed workflows.
docs/​src/​content/​docs/​getting-started/​quick-start.md	Updates quick-start constraints.
skills/​gh-stack/​SKILL.md	Updates skill constraints.
skills/​gh-stack/​references/​commands.md	Documents command behavior.
skills/​gh-stack/​references/​troubleshooting.md	Updates worktree troubleshooting.
AGENTS.md	Updates repository architecture guidance.
.github/​copilot-instructions.md	Updates contributor instructions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.