Sync with Main

Merges the latest main branch into a workspace's feature branch. Uses git merge (not rebase) to avoid rewriting history, and delegates conflict resolution to the merge-agent specialist.

Usage

# CLI command
pan sync-main PAN-XXX

# Or via the dashboard API
curl -X POST http://localhost:3011/api/issues/PAN-XXX/sync-main

What It Does

1. Checks for uncommitted changes (blocks if any — must commit, explicitly discard, or surface to the operator first; agents never git stash)
2. Resolves the workspace's required git repos; monorepos produce one repo root
3. Cleans up stale git locks in each repo
4. Fetches and merges each repo's configured target branch sequentially in config order
5. Stops at the first failed or conflicted repo and marks later repos skipped
6. If clean: reports aggregate commit/file totals plus one result per repo
7. If conflicts remain: aborts that repo's merge and reports its conflict files

Outcomes

Result	Meaning
Already up to date	Main has no new commits since last sync
Success (N commits)	Clean merge or agent-resolved conflicts
Uncommitted changes	Commit or discard workspace changes first
Conflict (unresolvable)	The failing repo's merge is aborted and its conflict files are reported
Per-repo / skipped	Polyrepo output shows each repo's result; repos after the first failure are skipped

Design Decisions

• Merge, not rebase — Rebase rewrites SHAs and requires force-push. Merge commits serve as audit markers.
• No tests/builds — Feature branch is WIP. Running tests after sync would fail on pre-existing issues.
• No push to remote — This is a local workspace operation only.
• Sequential polyrepo sync — Required repos sync in config order. The first failure stops iteration; earlier merges remain, later repos are skipped, and output reports every repo's result.

Examples

# Sync PAN-123 workspace with latest main
pan sync-main PAN-123

# Output on success:
# ✓ Synced 3 commit(s) from main
#   Commits merged: 3
#   Changed files (5):
#     src/lib/auth.ts
#     src/lib/config.ts
#     ...

# Output when already current:
# ✓ PAN-123 is already up to date with main

# Output on uncommitted changes (blocks):
# ✗ Sync failed: Workspace has uncommitted changes. Commit or discard them before syncing with main.

Dashboard

The "Sync with Main" button appears in the workspace detail panel:

• In the Git Status section as a small "Sync" button next to the branch name (disabled if uncommitted changes)
• In the Actions section as a full "Sync with Main" button

Related Commands

• gh pr review <pr-number> --approve — Approve the PR (merge from the dashboard MERGE button)
• pan review request <id> — Trigger review pipeline
• pan tell <id> "<message>" — Send message to agent