@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/scripts/sync.sh

@@ -0,0 +1,2871 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# REPO ROOT DETECTION - Navigate to git root before any operations
+# ============================================================================
+# This allows the script to be called from any directory within the repo
+# without requiring the caller to cd first.
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO_ROOT" ]; then
+    echo "  Error: not inside a git repository"
+    exit 1
+fi
+cd "$REPO_ROOT"
+
+# ============================================================================
+# This script is invoked by `build sync` or as a legacy fallback engine.
+#
+# It commits, merges, and pushes across environments, so review the script and
+# the current repository state before running it.
+# ============================================================================
+
+# Commit, Merge & Sync - Multi-environment git workflow automation
+# Usage: ./sync.sh [commit-message] [options]
+#
+# Options:
+#   --sync              Sync mode (pull + push-if-ahead, no commit)
+#   --sync-only         Sync only (skip PR phase)
+#   --pr-only           PR status/ensure only (skip sync + commit)
+#   --no-sync-push      In sync mode, never push after pull (alias: --pull-only)
+#   --pull-only         Alias for --no-sync-push (backward compat)
+#   --ensure-pr         Create PR if missing (default is show-only)
+#   --route-main        Route main commits via deterministic PR branch
+#   --no-route-main     Disable route-main for this run (overrides config)
+#   --stay-on-main      (deprecated, now default) Return to main after routing
+#   --publish           Force publishing new branches (push -u) when no upstream exists
+#   --no-publish        Disable publishing new branches for this run (overrides auto-publish)
+#   --push-all-branches With --all-branches, also push branches that are ahead
+#   --status            Preflight-only status (no changes)
+#   --rebase            Use rebase strategy (default)
+#   --merge             Use merge strategy
+#   --all-branches      Sync all tracked branches
+#   --dry-run           Preview without making changes
+#   --pr                Create a PR instead of pushing directly (enables CI/auto-fix flow)
+#   --no-pr             Force direct push even on protected branches
+#   --allow-protected   Allow commits to main/master/release branches (legacy)
+#   --no-protect-main   Bypass protected branch prompt for this run
+#   --no-orphan-warn    Suppress orphan branch warnings (Guardrail 2)
+#   --force             Skip ALL guardrails (nuclear option, use sparingly)
+#   --verbose           Show detailed output
+#   -h, --help          Print usage and exit
+#
+# Exit codes:
+#   0  Journey completed (sync and/or commit/push succeeded; warnings may appear above)
+#   1  Failure — an operation did not complete (commit/push/merge/guard refusal, etc.)
+#
+# Recovery checkpoints: before the first mutating operation a checkpoint branch
+#   backup/pre-sync-<epoch> is created. Failed runs keep theirs and print its name;
+#   successful runs remove their own and also prune checkpoints orphaned by prior
+#   failed runs once they are older than the retention window AND provably preserved
+#   in HEAD (ancestor, or patch-equivalent linear range). Checkpoints with unique
+#   commits are always kept and named. BUILD_SYNC_BACKUP_RETENTION_DAYS: integer
+#   days (0 = no age gate), or "off" to disable pruning; default 7.
+#
+# Guardrails:
+#   1. Protected branch check: Confirms before committing to main/master
+#      - Modes: off (no message), warn (print warning, proceed), confirm (prompt y/N), block (always block)
+#      - Precedence (highest to lowest):
+#        1. --no-protect-main or --force flag → bypass entirely
+#        2. BUILD_PROTECT_MAIN env var → sets mode
+#        3. build config get --scope user sync.protectMain → sets mode
+#        4. Default: confirm
+#      - In confirm mode: BUILD_ALLOW_MAIN_COMMIT=1 allows non-TTY commits (ignored in other modes)
+#   2. Orphaned work detection: Warns about recent branches with unpushed commits (when committing)
+#      - Only checks branches with activity in last 7 days to reduce noise
+#      - Suppress with --no-orphan-warn (does NOT affect Guardrail 1)
+#   3. Large commit preview: Shows summary when staging >10 files
+
+# Colors for output (severity-based: 4 levels)
+RED='\033[0;31m'      # Errors that stop execution
+YELLOW='\033[0;33m'   # Warnings (non-bold)
+GREEN='\033[0;32m'    # Positive outcomes
+DIM='\033[2m'         # De-emphasized secondary info
+NC='\033[0m'
+
+if [ "${NO_COLOR:-}" != "" ] || [ "${FORCE_COLOR:-}" = "0" ]; then
+    RED=''
+    YELLOW=''
+    GREEN=''
+    DIM=''
+    NC=''
+fi
+
+# Parse arguments
+ORIGINAL_ARGS=("$@")
+COMMIT_MESSAGE=""
+DRY_RUN=false
+USER_DRY_RUN=false
+SYNC_MODE=false
+SYNC_ONLY=false
+PR_ONLY=false
+STATUS_ONLY=false
+NO_SYNC_PUSH=false
+PUBLISH=false
+NO_PUBLISH=false
+PUSH_ALL_BRANCHES=false
+ENSURE_PR=false
+ROUTE_MAIN_FORCE=false
+NO_ROUTE_MAIN=false
+STAY_ON_MAIN=false
+REBASE=true  # Default to rebase for cleaner history
+ALL_BRANCHES=false
+SKIP_TESTS=false
+VERBOSE=false
+ALLOW_PROTECTED=false  # Guardrail: require explicit flag for protected branches (legacy)
+NO_PROTECT_MAIN=false  # Guardrail 1: bypass protected branch prompt for this run
+NO_ORPHAN_WARN=false   # Guardrail 2: suppress orphan branch warnings
+FORCE=false            # Guardrail: skip ALL safety checks (nuclear option)
+CREATE_PR=false        # Create PR instead of direct push (enables CI/auto-fix)
+NO_PR=false            # Force direct push even on protected branches
+IS_PROTECTED=false     # Guardrail 1: whether current branch is protected (set in guard block)
+
+# State tracking variables (Phase 1 improvements)
+UPSTREAM_EXISTS=false
+UPSTREAM_BRANCH=""
+PUSH_SUCCESS=false
+SYNC_SUCCESS=true
+HAS_WARNINGS=false
+HAS_FAILURE=false
+STASHED=false  # Track whether we actually stashed changes
+AUTO_STASH_MSG=""  # Unique message of the stash this run created
+ROUTE_MAIN_NEEDED=false
+ROUTE_MAIN_AHEAD_COUNT=0
+ROUTE_MAIN_MODE_ACTIVE=false
+ROUTE_MAIN_WIP_BRANCH=""
+CREATED_PR_URL=""  # Track PR URL to show helpful note when switching back to main
+CREATED_COMMIT_SHA=""  # Commit owned by this invocation (if Step 3 created one)
+CREATED_COMMIT_PARENT_SHA=""
+
+print_sync_usage() {
+    cat <<'EOF'
+Commit, Merge & Sync - Multi-environment git workflow automation
+Usage: ./sync.sh [commit-message] [options]
+
+Options:
+  --sync              Sync mode (pull + push-if-ahead, no commit)
+  --sync-only         Sync only (skip PR phase)
+  --pr-only           PR status/ensure only (skip sync + commit)
+  --no-sync-push      In sync mode, never push after pull (alias: --pull-only)
+  --pull-only         Alias for --no-sync-push (backward compat)
+  --ensure-pr         Create PR if missing (default is show-only)
+  --route-main        Route main commits via deterministic PR branch
+  --no-route-main     Disable route-main for this run (overrides config)
+  --stay-on-main      (deprecated, now default) Return to main after routing
+  --publish           Force publishing new branches (push -u) when no upstream exists
+  --no-publish        Disable publishing new branches for this run (overrides auto-publish)
+  --push-all-branches With --all-branches, also push branches that are ahead
+  --status            Preflight-only status (no changes)
+  --rebase            Use rebase strategy (default)
+  --merge             Use merge strategy
+  --all-branches      Sync all tracked branches
+  --dry-run           Preview without making changes
+  --pr                Create a PR instead of pushing directly (enables CI/auto-fix flow)
+  --no-pr             Force direct push even on protected branches
+  --allow-protected   Allow commits to main/master/release branches (legacy)
+  --no-protect-main   Bypass protected branch prompt for this run
+  --no-orphan-warn    Suppress orphan branch warnings (Guardrail 2)
+  --force             Skip ALL guardrails (nuclear option, use sparingly)
+  --verbose           Show detailed output
+  -h, --help          Print usage and exit
+
+Commit semantics:
+  When committing staged changes, the local commit is created before any push
+  attempt (--sync and --sync-only do not commit). If the push fails, the commit
+  remains on your current branch. Before the first mutating step, a checkpoint
+  branch backup/pre-sync-<epoch> is created for recovery; failed runs keep theirs.
+  Stale checkpoints are pruned per BUILD_SYNC_BACKUP_RETENTION_DAYS (see script header).
+
+Exit codes:
+  0  Journey completed (sync and/or commit/push succeeded; warnings may appear above)
+  1  Failure — an operation did not complete (commit/push/merge/guard refusal, etc.)
+EOF
+}
+
+for arg in "$@"; do
+    case $arg in
+        -h|--help)
+            print_sync_usage
+            exit 0
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            USER_DRY_RUN=true
+            ;;
+        --status)
+            STATUS_ONLY=true
+            ;;
+        --sync)
+            SYNC_MODE=true
+            ;;
+        --sync-only)
+            SYNC_MODE=true
+            SYNC_ONLY=true
+            ;;
+        --pr-only)
+            PR_ONLY=true
+            ;;
+        --rebase)
+            REBASE=true
+            ;;
+        --merge)
+            REBASE=false
+            ;;
+        --all-branches)
+            ALL_BRANCHES=true
+            ;;
+        --push-all-branches)
+            PUSH_ALL_BRANCHES=true
+            ;;
+        --no-sync-push)
+            NO_SYNC_PUSH=true
+            ;;
+        --pull-only)
+            NO_SYNC_PUSH=true
+            ;;
+        --publish)
+            PUBLISH=true
+            ;;
+        --no-publish)
+            NO_PUBLISH=true
+            ;;
+        --ensure-pr)
+            ENSURE_PR=true
+            ;;
+        --route-main)
+            ROUTE_MAIN_FORCE=true
+            ;;
+        --no-route-main)
+            NO_ROUTE_MAIN=true
+            ;;
+        --stay-on-main)
+            # Deprecated: return-to-main is now the default behavior.
+            # Kept for backward compatibility; flag is a no-op.
+            STAY_ON_MAIN=true
+            ;;
+        --skip-tests)
+            SKIP_TESTS=true
+            ;;
+        --verbose)
+            VERBOSE=true
+            ;;
+        --allow-protected)
+            ALLOW_PROTECTED=true
+            NO_PROTECT_MAIN=true  # --allow-protected implies --no-protect-main
+            ;;
+        --no-protect-main)
+            NO_PROTECT_MAIN=true
+            # Log bypass to stderr for visibility
+            printf "  ${YELLOW}%-16s %s${NC}\n" "Protect-main" "bypassed (--no-protect-main)" >&2
+            ;;
+        --no-orphan-warn)
+            NO_ORPHAN_WARN=true
+            ;;
+        --force)
+            FORCE=true
+            ALLOW_PROTECTED=true   # --force implies --allow-protected
+            NO_PROTECT_MAIN=true   # --force implies --no-protect-main
+            NO_ORPHAN_WARN=true    # --force implies --no-orphan-warn
+            ;;
+        --pr)
+            CREATE_PR=true
+            ;;
+        --no-pr)
+            NO_PR=true
+            ;;
+        --message=*|-m=*)
+            printf "  ${RED}%-16s %s${NC}\n" "Error" "unknown option: $arg"
+            printf "  %-16s %s\n" "Hint" 'Use positional form: build sync "your message" (not --message)'
+            exit 1
+            ;;
+        --message|-m)
+            printf "  ${RED}%-16s %s${NC}\n" "Error" "unknown option: $arg"
+            printf "  %-16s %s\n" "Hint" 'Use positional form: build sync "your message" (not --message)'
+            exit 1
+            ;;
+        --*)
+            printf "  ${RED}%-16s %s${NC}\n" "Error" "unknown option: $arg"
+            exit 1
+            ;;
+        *)
+            COMMIT_MESSAGE="$arg"
+            ;;
+    esac
+done
+
+if [ "$PUBLISH" = true ] && [ "$NO_PUBLISH" = true ]; then
+    printf "  ${RED}%-16s %s${NC}\n" "Error" "conflicting flags: --publish and --no-publish"
+    exit 1
+fi
+
+# Header
+echo ""
+echo "  sync — $(basename "$REPO_ROOT")"
+printf '  %0.s' $(seq 1 40); echo ""
+echo ""
+
+# Helper functions — 2-space indent, 16-char left-aligned label column
+log_ok()   { printf "  %-16s ${GREEN}%s${NC}\n" "$1" "$2"; }
+log_warn() { printf "  %-16s ${YELLOW}%s${NC}\n" "$1" "$2"; }
+log_err()  { printf "  ${RED}%-16s %s${NC}\n" "$1" "$2"; }
+log_dim()  { printf "  ${DIM}%-16s %s${NC}\n" "$1" "$2"; }
+
+LAST_GIT_PUSH_ERROR=""
+
+run_git_push() {
+    LAST_GIT_PUSH_ERROR=""
+
+    local err_file
+    err_file=$(mktemp 2>/dev/null) || true
+    if [ -z "${err_file:-}" ]; then
+        git push "$@" >/dev/null 2>&1
+        return $?
+    fi
+
+    if git push "$@" >/dev/null 2>"$err_file"; then
+        rm -f "$err_file"
+        return 0
+    fi
+
+    local filtered_error
+    filtered_error=$(
+        {
+            grep -Eiv '^(To |remote: (Resolving deltas|Compressing objects|Counting objects))' "$err_file" || true
+        } | sed 's/^remote: //' | sed '/^[[:space:]]*$/d'
+    )
+    LAST_GIT_PUSH_ERROR=$(printf '%s\n' "$filtered_error" | grep -Eiv '^hint:' | tail -n 3 || true)
+    if [ -z "$LAST_GIT_PUSH_ERROR" ]; then
+        LAST_GIT_PUSH_ERROR=$(printf '%s\n' "$filtered_error" | tail -n 3)
+    fi
+    rm -f "$err_file"
+    return 1
+}
+
+log_git_push_reason() {
+    if [ -z "$LAST_GIT_PUSH_ERROR" ]; then
+        return 0
+    fi
+
+    local line
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        log_warn "Reason" "$line"
+    done <<< "$LAST_GIT_PUSH_ERROR"
+}
+
+move_lock_blocked_route_ref() {
+    local branch="$1"
+
+    case "$branch" in
+        wip/route-main/*) ;;
+        *) return 1 ;;
+    esac
+    if ! git check-ref-format --branch "$branch" >/dev/null 2>&1; then
+        return 1
+    fi
+
+    local current_branch
+    current_branch=$(git branch --show-current 2>/dev/null || true)
+    if [ "$branch" = "$current_branch" ]; then
+        return 1
+    fi
+
+    local ref_path
+    ref_path=$(git rev-parse --git-path "refs/heads/$branch" 2>/dev/null || true)
+    if [ -z "$ref_path" ] || [ ! -f "$ref_path" ]; then
+        return 1
+    fi
+
+    local archive_root archive_path safe_name
+    archive_root="${TMPDIR:-/tmp}/build-merged-refs"
+    safe_name=$(echo "$branch" | sed 's#[^A-Za-z0-9._-]#_#g')
+    archive_path="$archive_root/$safe_name-$(date +%s)"
+
+    mkdir -p "$archive_root" 2>/dev/null || return 1
+    if mv "$ref_path" "$archive_path" 2>/dev/null; then
+        log_warn "Cleanup" "local ref lock blocked; moved merged $branch"
+        log_dim "Ref backup" "$archive_path"
+        return 0
+    fi
+
+    return 1
+}
+
+delete_local_route_branch() {
+    local branch="$1"
+    local err_file
+    err_file=$(mktemp 2>/dev/null) || true
+
+    if [ -z "${err_file:-}" ]; then
+        git branch -D "$branch" >/dev/null 2>&1
+        return $?
+    fi
+
+    if git branch -D "$branch" >/dev/null 2>"$err_file"; then
+        rm -f "$err_file"
+        return 0
+    fi
+
+    local delete_error
+    delete_error=$(cat "$err_file" 2>/dev/null || true)
+    rm -f "$err_file"
+
+    if echo "$delete_error" | grep -qi 'cannot lock ref' && \
+       echo "$delete_error" | grep -qi 'Operation not permitted'; then
+        move_lock_blocked_route_ref "$branch"
+        return $?
+    fi
+
+    return 1
+}
+
+# Extract Build backlog IDs from arbitrary text.
+# Format: <YYYYMMDDTHHMMSSZ>-<uuidHex12>
+extract_build_backlog_ids() {
+    local text="${1:-}"
+    if [ -z "$text" ]; then
+        return 0
+    fi
+    echo "$text" | grep -Eo '[0-9]{8}T[0-9]{6}Z-[0-9a-f]{12}' 2>/dev/null | sort -u || true
+}
+
+is_generated_sync_artifact_path() {
+    local file="$1"
+    case "$file" in
+        schemas/build.config.schema.json|schemas/judge-scoring.schema.json|providers/pricing.json|providers/registry.json|.build-project/providers/pricing.json|.build-project/providers/registry.json)
+            return 0
+            ;;
+        src/core/providers/generated/*|src/core/providers/routing/generated/*)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+filter_generated_sync_artifacts() {
+    local file
+    while IFS= read -r file; do
+        [ -n "$file" ] || continue
+        if is_generated_sync_artifact_path "$file"; then
+            echo "$file"
+        fi
+    done
+}
+
+get_staged_generated_artifacts() {
+    git diff --cached --name-only 2>/dev/null | filter_generated_sync_artifacts
+}
+
+get_last_commit_generated_artifacts() {
+    git diff-tree --no-commit-id --name-only -r HEAD 2>/dev/null | filter_generated_sync_artifacts
+}
+
+get_last_commit_subject() {
+    git log -1 --pretty=%s 2>/dev/null || echo ""
+}
+
+get_last_commit_sha_short() {
+    git rev-parse --short=12 HEAD 2>/dev/null || echo ""
+}
+
+# Basic PR body template for sync-created PRs.
+# Goals:
+# - Human skimmable (Summary/Verification)
+# - Agent parseable (stable Build key/value lines)
+build_sync_pr_body() {
+    local mode="${1:-}"
+    local head_branch="${2:-}"
+    local base_branch="${3:-}"
+
+    local subject="${COMMIT_MESSAGE:-}"
+    if [ -z "$subject" ]; then
+        subject=$(get_last_commit_subject)
+    fi
+
+    local sha
+    sha=$(get_last_commit_sha_short)
+
+    local summary_line_1
+    case "$mode" in
+        route-main)
+            summary_line_1="Route protected-branch updates via PR"
+            ;;
+        ensure-pr)
+            summary_line_1="Open PR for branch updates"
+            ;;
+        pr)
+            summary_line_1="Run CI/auto-fix via PR workflow"
+            ;;
+        *)
+            summary_line_1="Update"
+            ;;
+    esac
+
+    local summary_line_2=""
+    if [ -n "$subject" ]; then
+        summary_line_2="Commit: $subject"
+        if [ -n "$sha" ]; then
+            summary_line_2="$summary_line_2 ($sha)"
+        fi
+    fi
+
+    local backlog_ids
+    backlog_ids=$(extract_build_backlog_ids "$subject" | tr '\n' ' ' | sed 's/[[:space:]]*$//') || true
+
+    echo "Summary:"
+    echo "- $summary_line_1"
+    if [ -n "$summary_line_2" ]; then
+        echo "- $summary_line_2"
+    fi
+    echo ""
+
+    if [ "$mode" = "route-main" ]; then
+        echo "Why:"
+        echo "- Avoid direct commits to protected branches"
+        echo ""
+    fi
+
+    echo "Verification:"
+    echo "- not run (created by build sync; rely on CI)"
+
+    local generated_artifacts
+    generated_artifacts=$(get_last_commit_generated_artifacts)
+    if [ -n "$generated_artifacts" ]; then
+        echo ""
+        echo "Generated artifacts:"
+        echo "- Sync/build hooks updated committed generated files"
+        echo "$generated_artifacts" | sed 's/^/- /'
+    fi
+
+    if [ -n "$backlog_ids" ]; then
+        echo ""
+        echo "Links:"
+        echo "- Backlog: $backlog_ids"
+    fi
+
+    echo ""
+    echo "Build:"
+    echo "- Mode: $mode"
+    echo "- Branch: $head_branch"
+    echo "- Base: $base_branch"
+
+    # Include Refs: and Build-Sync: lines from commit message for task linkage
+    # This enables `build sync reconcile` to find merged PRs by task ID
+    local commit_body
+    commit_body=$(git log -1 --pretty=%B 2>/dev/null || true)
+    local refs_line build_sync_line
+    refs_line=$(echo "$commit_body" | grep -E '^Refs: task/' || true)
+    build_sync_line=$(echo "$commit_body" | grep -E '^Build-Sync:' || true)
+    if [ -n "$refs_line" ] || [ -n "$build_sync_line" ]; then
+        echo ""
+        [ -n "$refs_line" ] && echo "$refs_line"
+        [ -n "$build_sync_line" ] && echo "$build_sync_line"
+    fi
+}
+
+
+# Project-local post-sync hooks (optional extension points):
+# - $REPO_ROOT/.claude/hooks/post-sync.sh
+# - $REPO_ROOT/.claude/hooks/post-sync-cleanup.sh
+# Notes:
+# - Hooks are skipped in --dry-run mode.
+# - Hook failures never fail the main sync run.
+run_post_sync_hooks() {
+    if [ "${CLAUDE_SYNC_HOOKS_DISABLED:-}" = "1" ]; then
+        if [ "${VERBOSE}" = true ]; then
+            log_dim "Hooks" "disabled (CLAUDE_SYNC_HOOKS_DISABLED=1)"
+        fi
+        return 0
+    fi
+
+    local hook_paths=(
+        "$REPO_ROOT/.claude/hooks/post-sync.sh"
+        "$REPO_ROOT/.claude/hooks/post-sync-cleanup.sh"
+    )
+
+    local found_any=false
+    local seen_hooks=$'\n'
+    for hook in "${hook_paths[@]}"; do
+        if [ ! -f "$hook" ]; then
+            continue
+        fi
+        if [[ "$seen_hooks" == *$'\n'"$hook"$'\n'* ]]; then
+            continue
+        fi
+        seen_hooks+=$'\n'"${hook}"$'\n'
+
+        found_any=true
+        if [ ! -x "$hook" ]; then
+            log_warn "Hook" "not executable: $hook"
+            continue
+        fi
+
+        log_dim "Hook" "${hook#$REPO_ROOT/}"
+        if CLAUDE_SYNC_REPO_ROOT="$REPO_ROOT" \
+            CLAUDE_SYNC_DRY_RUN="$DRY_RUN" \
+            CLAUDE_SYNC_MODE="$SYNC_MODE" \
+            CLAUDE_SYNC_ONLY="$SYNC_ONLY" \
+            CLAUDE_SYNC_PR_ONLY="$PR_ONLY" \
+            CLAUDE_SYNC_STATUS_ONLY="$STATUS_ONLY" \
+            CLAUDE_SYNC_PUSH_SUCCESS="$PUSH_SUCCESS" \
+            CLAUDE_SYNC_HAS_WARNINGS="$HAS_WARNINGS" \
+            CLAUDE_SYNC_ALREADY_FETCHED="${SYNC_FETCH_DONE:-false}" \
+            CLAUDE_SYNC_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")" \
+            bash "$hook" ${ORIGINAL_ARGS[@]+"${ORIGINAL_ARGS[@]}"}; then
+            :
+        else
+            log_warn "Hook" "failed: ${hook#$REPO_ROOT/}"
+            HAS_WARNINGS=true
+        fi
+    done
+
+    if [ "$found_any" = false ] && [ "${VERBOSE}" = true ]; then
+        log_dim "Hooks" "none found"
+    fi
+}
+
+# Normalize common truthy values to bash-friendly true/false
+is_truthy() {
+    case "${1:-}" in
+        1|true|TRUE|yes|YES|on|ON) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+has_tracked_changes() {
+    local tracked
+    tracked=$(git status --porcelain | grep -Ev "^[\\?!]" || true)
+    [ -n "$tracked" ]
+}
+
+# ============================================================================
+# CONFIG CACHE - load all sync settings once at startup (avoids repeated CLI spawns)
+# ============================================================================
+# Priority per key: 1. env var (highest)  2. build config --scope user (routeMain: project scope first)  3. default
+#
+# Cache is populated lazily on first access. Uses `build config get --scope user --json`
+# which returns {"path":"...","scope":"user","value":...} when set, or omits "value" when not.
+_SYNC_CONFIG_LOADED=false
+_CFG_ROUTE_MAIN=""
+_CFG_AUTO_PUBLISH=""
+_CFG_PROTECT_MAIN=""
+_CFG_CHECKOUT_MAIN=""
+
+_load_sync_config() {
+    if [ "$_SYNC_CONFIG_LOADED" = true ]; then
+        return
+    fi
+    _SYNC_CONFIG_LOADED=true
+
+    # Only attempt CLI reads if build is available
+    if ! command -v build >/dev/null 2>&1; then
+        return
+    fi
+
+    # Batch-read all 4 sync keys via `build config get` (portable; no tsx/source dependency).
+    local batch_json
+    batch_json=$(
+        build config get sync --scope user --json 2>/dev/null | node -e '
+let s = "";
+process.stdin.on("data", d => s += d);
+process.stdin.on("end", () => {
+  try {
+    const parsed = JSON.parse(s);
+    process.stdout.write(JSON.stringify(parsed.value ?? {}));
+  } catch {
+    process.stdout.write("{}");
+  }
+});
+' 2>/dev/null || echo "{}"
+    )
+
+    # Project scope wins over user scope for routeMain (env var still wins over both)
+    local project_route
+    project_route=$(build config get sync.routeMain --scope project --json 2>/dev/null \
+        | tr -d '\n' | sed -n 's/.*"found"[[:space:]]*:[[:space:]]*true.*"value"[[:space:]]*:[[:space:]]*\([a-z]*\).*/\1/p' || true)
+
+    # Parse batch result (single jq-free parse via grep)
+    if [ -n "$batch_json" ] && [ "$batch_json" != "{}" ]; then
+        if [ -z "${BUILD_PR_ROUTE_MAIN:-}" ]; then
+            _CFG_ROUTE_MAIN=$(echo "$batch_json" | sed -n 's/.*"routeMain"[[:space:]]*:[[:space:]]*\([^,}]*\).*/\1/p' | tr -d '"' || true)
+        fi
+        if [ -z "${BUILD_SYNC_AUTO_PUBLISH:-}" ]; then
+            _CFG_AUTO_PUBLISH=$(echo "$batch_json" | sed -n 's/.*"autoPublish"[[:space:]]*:[[:space:]]*\([^,}]*\).*/\1/p' | tr -d '"' || true)
+        fi
+        if [ -z "${BUILD_PROTECT_MAIN:-}" ]; then
+            _CFG_PROTECT_MAIN=$(echo "$batch_json" | sed -n 's/.*"protectMain"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' || true)
+        fi
+        if [ -z "${BUILD_SYNC_CHECKOUT_MAIN:-}" ]; then
+            _CFG_CHECKOUT_MAIN=$(echo "$batch_json" | sed -n 's/.*"checkoutMain"[[:space:]]*:[[:space:]]*\([^,}]*\).*/\1/p' | tr -d '"' || true)
+        fi
+    fi
+    if [ -z "${BUILD_PR_ROUTE_MAIN:-}" ] && [ -n "$project_route" ]; then
+        _CFG_ROUTE_MAIN="$project_route"
+    fi
+}
+
+# Get route-main default from config or environment
+# Priority: 1. BUILD_PR_ROUTE_MAIN env var  2. build config  3. default false
+# Default is false: direct-to-main push. Enable via config for PR-centric CI workflows.
+get_route_main_default() {
+    if [ -n "${BUILD_PR_ROUTE_MAIN:-}" ]; then
+        echo "${BUILD_PR_ROUTE_MAIN}"
+        return
+    fi
+    _load_sync_config
+    if [ -n "$_CFG_ROUTE_MAIN" ]; then
+        echo "$_CFG_ROUTE_MAIN"
+        return
+    fi
+    echo "false"
+}
+
+# Get sync auto-publish default from config or environment
+# Priority: 1. BUILD_SYNC_AUTO_PUBLISH env var  2. build config  3. default false
+get_sync_auto_publish_default() {
+    if [ -n "${BUILD_SYNC_AUTO_PUBLISH:-}" ]; then
+        echo "${BUILD_SYNC_AUTO_PUBLISH}"
+        return
+    fi
+    _load_sync_config
+    if [ -n "$_CFG_AUTO_PUBLISH" ]; then
+        echo "$_CFG_AUTO_PUBLISH"
+        return
+    fi
+    echo "false"
+}
+
+# Get sync checkout-main default from config or environment
+# Priority: 1. BUILD_SYNC_CHECKOUT_MAIN env var  2. build config  3. default false
+get_sync_checkout_main_default() {
+    if [ -n "${BUILD_SYNC_CHECKOUT_MAIN:-}" ]; then
+        echo "${BUILD_SYNC_CHECKOUT_MAIN}"
+        return
+    fi
+    _load_sync_config
+    if [ -n "$_CFG_CHECKOUT_MAIN" ]; then
+        echo "$_CFG_CHECKOUT_MAIN"
+        return
+    fi
+    echo "false"
+}
+
+is_wip_named_branch() {
+    local branch="$1"
+    case "$branch" in
+        local/*|wip/*|tmp/*|scratch/*|throwaway/*|validation/*) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+should_publish_new_branch() {
+    local branch="$1"
+
+    if [ "$NO_PUBLISH" = true ]; then
+        return 1
+    fi
+    if [ "$PUBLISH" = true ]; then
+        return 0
+    fi
+    if is_wip_named_branch "$branch"; then
+        return 1
+    fi
+
+    local auto_publish_default
+    auto_publish_default=$(get_sync_auto_publish_default)
+    if is_truthy "$auto_publish_default"; then
+        return 0
+    fi
+
+    return 1
+}
+
+# Get protect-main mode from config or environment
+# Priority: 1. BUILD_PROTECT_MAIN env var  2. build config  3. default "confirm"
+get_protect_main_mode() {
+    if [ -n "${BUILD_PROTECT_MAIN:-}" ]; then
+        echo "${BUILD_PROTECT_MAIN}"
+        return
+    fi
+    _load_sync_config
+    if [ -n "$_CFG_PROTECT_MAIN" ]; then
+        echo "$_CFG_PROTECT_MAIN"
+        return
+    fi
+    echo "confirm"
+}
+
+# Generate commit message from staged changes
+# Format: type(scope): subject
+# Types: feat, fix, chore, docs, refactor, test
+# Research: based on the task-sync design recommendations
+generate_commit_message() {
+    # If Build repo with build CLI, try intelligent task-aware generation first
+    # Contract: build sync message reads --cached, returns message on stdout, exits 0
+    #           On failure, exits non-zero and we fall back to diff-based generation
+    if [ -d ".build-project" ] && command -v build >/dev/null 2>&1; then
+        local build_msg
+        local build_status=0
+        local force_flag=""
+        if [ "$FORCE" = true ]; then force_flag="--force"; fi
+        build_msg=$(build sync message $force_flag 2>/dev/null) || build_status=$?
+        if [ "$build_status" -eq 0 ] && [ -n "$build_msg" ]; then
+            echo "$build_msg"
+            return
+        fi
+        if [ "$build_status" -eq 2 ]; then
+            return 2
+        fi
+    fi
+
+    local staged_files
+    staged_files=$(git diff --cached --name-only 2>/dev/null)
+
+    if [ -z "$staged_files" ]; then
+        # Fallback to timestamp if no staged files
+        echo "chore: checkpoint $(date '+%Y-%m-%d %H:%M')"
+        return
+    fi
+
+    local file_count
+    file_count=$(echo "$staged_files" | wc -l | tr -d ' ')
+
+    # Analyze file types and changes
+    local has_src=false has_test=false has_config=false has_docs=false has_build=false
+    local src_count=0 test_count=0 doc_count=0 config_count=0
+    local scope="" commit_type=""
+
+    while IFS= read -r file; do
+        case "$file" in
+            src/*|lib/*|app/*|components/*|utils/*|services/*|core/*|modules/*)
+                has_src=true
+                src_count=$((src_count + 1))
+                # Extract scope from path (first directory after src/)
+                if [ -z "$scope" ]; then
+                    scope=$(echo "$file" | sed 's|^[^/]*/||' | cut -d'/' -f1)
+                fi
+                ;;
+            test/*|tests/*|__tests__/*|*.test.*|*.spec.*|*_test.*|*_spec.*)
+                has_test=true
+                test_count=$((test_count + 1))
+                ;;
+            *.md|docs/*|README*|CHANGELOG*|CONTRIBUTING*)
+                has_docs=true
+                doc_count=$((doc_count + 1))
+                ;;
+            package.json|package-lock.json|*.config.js|*.config.ts|tsconfig.json|.gitignore|.npmignore)
+                has_config=true
+                config_count=$((config_count + 1))
+                ;;
+            scripts/*|build/*|Makefile|Dockerfile|*.sh)
+                has_build=true
+                ;;
+        esac
+    done <<< "$staged_files"
+
+    # Detect change type (add/modify/delete)
+    local primary_action="update"
+    local added_count deleted_count modified_count
+    added_count=$(git diff --cached --name-only --diff-filter=A | wc -l | tr -d ' ')
+    deleted_count=$(git diff --cached --name-only --diff-filter=D | wc -l | tr -d ' ')
+    modified_count=$(git diff --cached --name-only --diff-filter=M | wc -l | tr -d ' ')
+
+    if [ "$added_count" -gt "$deleted_count" ] && [ "$added_count" -gt "$modified_count" ]; then
+        primary_action="add"
+    elif [ "$deleted_count" -gt "$added_count" ] && [ "$deleted_count" -gt "$modified_count" ]; then
+        primary_action="remove"
+    fi
+
+    # Classify commit type using rule-based heuristics.
+    # Source changes take precedence over test majorities so mixed implementation
+    # commits do not get mislabeled as test-only work.
+    if [ "$has_docs" = true ] && [ "$doc_count" -ge "$((file_count * 70 / 100))" ]; then
+        # 70%+ docs files
+        commit_type="docs"
+        scope=""
+    elif [ "$has_test" = true ] && \
+         [ "$has_src" = false ] && \
+         [ "$has_build" = false ] && \
+         [ "$has_config" = false ] && \
+         [ "$test_count" -ge "$((file_count * 70 / 100))" ]; then
+        # 70%+ test files with no implementation/build/config changes
+        commit_type="test"
+    elif [ "$has_config" = true ] && [ "$config_count" -ge "$((file_count * 50 / 100))" ]; then
+        # 50%+ config files
+        commit_type="chore"
+        scope="config"
+    elif [ "$has_build" = true ] && [ "$file_count" -le 5 ]; then
+        # Build/script changes (when small batches)
+        commit_type="chore"
+        scope="build"
+    elif [ "$has_src" = true ]; then
+        # Source code changes - detect feat vs fix vs refactor
+        local diff_content
+        diff_content=$(git diff --cached 2>/dev/null)
+
+        # Heuristic: look for patterns in diff to classify feat/fix/refactor
+        if echo "$diff_content" | grep -qiE "^[+].*\b(bug|fix|issue|error|crash|fail)\b" || \
+           echo "$diff_content" | grep -qiE "^[+].*\b(correct|repair|resolve)\b"; then
+            commit_type="fix"
+        elif echo "$diff_content" | grep -qiE "^[+].*\b(refactor|rename|restructure|reorganize)\b" || \
+             [ "$added_count" -gt 0 ] && [ "$deleted_count" -gt 0 ] && [ "$added_count" -eq "$deleted_count" ]; then
+            commit_type="refactor"
+        elif [ "$primary_action" = "add" ] || echo "$diff_content" | grep -qE "^\+[^+].*\b(new|add|create|implement)\b"; then
+            commit_type="feat"
+        else
+            # Default for src changes
+            commit_type="feat"
+        fi
+    else
+        # Uncertain classification - fallback to chore
+        commit_type="chore"
+    fi
+
+    # Generate human-readable summary
+    local summary=""
+
+    if [ "$file_count" -eq 1 ]; then
+        # Single file - use filename
+        local filename
+        filename=$(basename "$(echo "$staged_files" | head -1)" | sed 's/\.[^.]*$//')
+        summary="${primary_action} ${filename}"
+    elif [ "$has_docs" = true ] && [ "$doc_count" = "$file_count" ]; then
+        # All docs
+        if [ "$file_count" -eq 1 ]; then
+            summary="update documentation"
+        else
+            summary="update documentation (${file_count} files)"
+        fi
+    elif [ "$has_test" = true ] && [ "$test_count" = "$file_count" ]; then
+        # All tests
+        summary="${primary_action} tests for ${scope:-components}"
+    elif [ "$has_config" = true ] && [ "$config_count" = "$file_count" ]; then
+        # All config
+        summary="update configuration"
+    else
+        # Mixed changes - summarize by dominant type
+        local parts=""
+        if [ "$src_count" -gt 0 ]; then
+            parts="source"
+            if [ -n "$scope" ] && [ "$src_count" -le 3 ]; then
+                parts="${scope}"
+            fi
+        fi
+        if [ "$test_count" -gt 0 ]; then
+            [ -n "$parts" ] && parts="${parts} + tests" || parts="tests"
+        fi
+        if [ "$doc_count" -gt 0 ]; then
+            [ -n "$parts" ] && parts="${parts} + docs" || parts="docs"
+        fi
+        if [ "$config_count" -gt 0 ]; then
+            [ -n "$parts" ] && parts="${parts} + config" || parts="config"
+        fi
+
+        if [ -z "$parts" ]; then
+            parts="${file_count} files"
+        fi
+
+        summary="${primary_action} ${parts}"
+    fi
+
+    # Build final message in conventional commit format
+    local message
+    if [ -n "$scope" ] && [ "$commit_type" != "docs" ]; then
+        message="${commit_type}(${scope}): ${summary}"
+    else
+        message="${commit_type}: ${summary}"
+    fi
+
+    # Truncate if too long (git recommends <72 chars for subject, we target 50-60)
+    if [ ${#message} -gt 72 ]; then
+        # Keep type and scope, truncate summary
+        local prefix
+        if [ -n "$scope" ] && [ "$commit_type" != "docs" ]; then
+            prefix="${commit_type}(${scope}): "
+        else
+            prefix="${commit_type}: "
+        fi
+        local max_summary_len=$((72 - ${#prefix} - 3))  # -3 for "..."
+        summary="${summary:0:$max_summary_len}..."
+        message="${prefix}${summary}"
+    fi
+
+    echo "$message"
+}
+
+staged_has_mixed_system_and_code() {
+    local staged_files
+    staged_files=$(git diff --cached --name-only 2>/dev/null || true)
+
+    local has_system=false
+    local has_code=false
+
+    while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        case "$file" in
+            task/*|sprint/*|backlog/*)
+                has_system=true
+                ;;
+            *)
+                has_code=true
+                ;;
+        esac
+
+        if [ "$has_system" = true ] && [ "$has_code" = true ]; then
+            return 0
+        fi
+    done <<EOF
+$staged_files
+EOF
+
+    return 1
+}
+
+# Authoritative mixed planning/code stage-set check.
+#
+# The shell heuristic above (staged_has_mixed_system_and_code) only recognizes
+# task/sprint/backlog as system paths and only fires when the shell's own
+# IS_PROTECTED (main/master/release/*) is set. The TypeScript validator
+# (validateSyncStageSet -> isSystemWritePath, src/core/utils/repo-path-classifier.ts)
+# is broader on both axes: it also treats .build-project/planning, .build-project/plans, .build-project/tmp
+# and other managed/runtime paths as system writes, and its protected-branch set
+# (isProtectedPipelineBranch) covers develop/staging/production, hotfix/*, origin/*
+# and BUILD_PROTECTED_BRANCHES. `build sync message` runs that same validator and
+# exits 2 exactly when the staged set mixes system-write and code paths on a protected
+# branch, so it is the single source of truth and needs no shell IS_PROTECTED gate.
+#
+# The auto-generated-message path already runs this validator inside
+# generate_commit_message (its exit 2 aborts under set -e). The gap this closes is
+# `build sync "explicit message"`, which skips message generation; the caller invokes
+# this only when an explicit COMMIT_MESSAGE was supplied, so bare syncs pay no extra
+# CLI call. --force is honored by the caller.
+#
+# Best-effort limitation: when `build` is not on PATH this returns non-zero and the
+# guard falls back to staged_has_mixed_system_and_code, which is narrower on both axes
+# (only task/sprint/backlog paths, only the main/master/release/* branch set). sync.sh
+# is normally invoked by `build sync`, so the CLI is present and authoritative; a
+# direct `./scripts/sync.sh "message"` invocation without build installed on a branch
+# outside the shell-protected set is the only path that stays best-effort. Fully closing
+# it would require duplicating the TS path classifier and protected-branch set in shell
+# (a drift risk), so it is intentionally left to the authoritative CLI check.
+cli_refuses_mixed_stage_set() {
+    [ -d ".build-project" ] || return 1
+    command -v build >/dev/null 2>&1 || return 1
+    local rc=0
+    build sync message >/dev/null 2>&1 || rc=$?
+    [ "$rc" -eq 2 ]
+}
+
+# Print "<commit> stash@{N}" for the stash this run created (matched by its
+# unique message). The stash list is shared by every worktree, so never assume
+# stash@{0}; commit id and index come from one listing so they always agree.
+own_stash_entry() {
+    [ -n "$AUTO_STASH_MSG" ] || return 0
+    git stash list --format='%H %gd %gs' 2>/dev/null | awk -v m="$AUTO_STASH_MSG" '$NF == m { print $1, $2; exit }'
+}
+own_stash_sha() { own_stash_entry | cut -d' ' -f1; }
+own_stash_ref() { own_stash_entry | cut -d' ' -f2; }
+
+# Drop this run's stash (commit $1) only when it is the sole stash entry, with a
+# compare-and-delete of refs/stash: if another worktree stashes in the meantime
+# the ref no longer equals $1 and the delete fails without touching its entry.
+# `git stash drop` takes a mutable index, so with other entries present this run
+# never drops by index; the entry is retained (see note_retained_stash).
+drop_own_stash() {
+    local sha="$1"
+    [ -n "$sha" ] && [ "$(git stash list --format=%H 2>/dev/null)" = "$sha" ] || return 1
+    git update-ref -d refs/stash "$sha" >/dev/null 2>&1
+}
+
+# Explain a retained auto-stash entry (commit $1) and how to drop it by hand.
+note_retained_stash() {
+    log_warn "Stash" "entry kept in 'git stash list' (other stashes present, not dropped by index)"
+    echo "  Entry:    $1 ($AUTO_STASH_MSG)"
+    echo "  Drop it:  git stash list, then git stash drop stash@{N} for that entry"
+    HAS_WARNINGS=true
+}
+
+# Print "rebase" or "merge" when one is in progress in this worktree, else nothing.
+git_op_in_progress() {
+    if [ -d "$(git rev-parse --git-path rebase-merge)" ] || [ -d "$(git rev-parse --git-path rebase-apply)" ]; then
+        echo rebase
+    elif git rev-parse -q --verify MERGE_HEAD >/dev/null 2>&1; then
+        echo merge
+    fi
+}
+
+# Stash recovery helper (DRY - used in multiple places)
+handle_stash_conflict() {
+    local branch_context="$1"
+    log_err "Stash" "conflict when re-applying changes"
+    HAS_WARNINGS=true
+
+    # Auto-recovery: Create recovery branch from stash
+    RECOVERY_BRANCH="recovery/stash-conflict-$(date +%s)"
+    local own_sha
+    own_sha=$(own_stash_sha)
+    if [ -n "$own_sha" ] && git stash branch "$RECOVERY_BRANCH" "$own_sha" >/dev/null 2>&1; then
+        drop_own_stash "$own_sha" || note_retained_stash "$own_sha"
+        log_ok "Recovery" "$RECOVERY_BRANCH"
+        echo ""
+        echo "Note: You are now on $RECOVERY_BRANCH"
+        echo "To merge back to $branch_context:"
+        echo "  1. git checkout $branch_context"
+        echo "  2. git merge $RECOVERY_BRANCH"
+        echo "  3. Resolve conflicts manually"
+    else
+        log_err "Recovery" "failed to create branch"
+        local orphan_ref
+        orphan_ref=$(own_stash_ref)
+        if [ -n "$orphan_ref" ]; then
+            echo "  Your uncommitted changes are in stash: $orphan_ref"
+            echo "  Inspect:  git stash show -p $orphan_ref"
+            echo "  Restore:  git stash pop $orphan_ref"
+            echo "  Discard:  git stash drop $orphan_ref"
+        else
+            echo "Your changes are safe in stash. Use: git stash list"
+        fi
+    fi
+    exit 1
+}
+
+# ============================================================================
+# SHARED PULL HELPER - stash, pull/rebase, conflict recovery, unstash
+# ============================================================================
+# Encapsulates the stash → pull → conflict-abort → unstash flow used by
+# both sync mode and commit mode.
+#
+# Usage:
+#   do_pull_with_stash                          # normal pull from upstream
+#   do_pull_with_stash --rebase-onto origin/main  # rebase onto ref (no upstream)
+#
+# Globals read:
+#   HAS_TRACKED_CHANGES, HAS_UNTRACKED_ONLY, REBASE, CURRENT_BRANCH
+#
+# Globals written:
+#   STASHED  (true if changes were stashed and need external restore on early return)
+#
+# Returns:
+#   0 = success (stash restored on success path)
+#   1 = conflict (rebase/merge aborted, stash restored, caller should print
+#       resolution instructions and exit)
+#
+do_pull_with_stash() {
+    local rebase_onto=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --rebase-onto) rebase_onto="$2"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    # --- Stash ---
+    STASHED=false
+    if [ "$HAS_TRACKED_CHANGES" = true ]; then
+        ensure_backup_branch
+        AUTO_STASH_MSG="cm-auto-stash-$(date +%s)-$$-${RANDOM}"
+        if git stash push -u -q -m "$AUTO_STASH_MSG" && [ -n "$(own_stash_ref)" ]; then
+            STASHED=true
+            log_dim "Stash" "saved"
+        else
+            log_warn "Stash" "failed, continuing without"
+        fi
+    elif [ "$HAS_UNTRACKED_ONLY" = true ]; then
+        log_dim "Stash" "not needed (untracked only)"
+    fi
+
+    # --- Pull strategy ---
+    local pull_strategy="--rebase=merges"
+    if [ "$REBASE" = false ]; then
+        pull_strategy="--merge"
+    fi
+
+    # --- Execute pull or rebase-onto ---
+    local pull_ok=false
+
+    if [ -n "$rebase_onto" ]; then
+        # No upstream: rebase or merge onto an explicit ref (route-main path)
+        if [ "$REBASE" = true ]; then
+            if git rebase --rebase-merges -q "$rebase_onto" >/dev/null 2>&1; then
+                pull_ok=true
+                log_ok "Rebase" "onto $rebase_onto"
+            else
+                log_err "Rebase" "failed — $rebase_onto"
+                git rebase --abort 2>/dev/null || true
+            fi
+        else
+            if git merge -q "$rebase_onto" --no-edit >/dev/null 2>&1; then
+                pull_ok=true
+                log_ok "Merge" "from $rebase_onto"
+            else
+                log_err "Merge" "failed — $rebase_onto"
+                git merge --abort 2>/dev/null || true
+            fi
+        fi
+    elif git rev-parse --abbrev-ref --symbolic-full-name "@{u}" >/dev/null 2>&1; then
+        # Normal upstream pull
+        ensure_backup_branch
+        if git pull $pull_strategy >/dev/null 2>&1; then
+            pull_ok=true
+            log_ok "Pull" "done"
+        else
+            log_err "Pull" "conflict detected"
+            git rebase --abort 2>/dev/null || git merge --abort 2>/dev/null || true
+        fi
+    else
+        # No upstream, no rebase-onto: nothing to pull
+        pull_ok=true
+    fi
+
+    # --- Restore stash ---
+    # Apply this run's own stash by commit id (another worktree may have pushed
+    # a newer entry meanwhile), then drop that entry without touching others.
+    if [ "$STASHED" = true ]; then
+        local own_sha
+        own_sha=$(own_stash_sha)
+        if [ -n "$own_sha" ] && git stash apply -q "$own_sha" >/dev/null 2>&1; then
+            drop_own_stash "$own_sha" || note_retained_stash "$own_sha"
+            log_ok "Stash" "restored"
+            STASHED=false
+        else
+            if [ "$pull_ok" = true ]; then
+                # Pull succeeded but stash pop conflicted
+                handle_stash_conflict "$CURRENT_BRANCH"
+                # handle_stash_conflict exits; control does not return here
+            else
+                # Pull also failed; restore stash best-effort and report below
+                log_warn "Stash" "restore failed — use 'git stash list' to recover"
+            fi
+        fi
+    fi
+
+    if [ "$pull_ok" = true ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Try to find an open PR URL for a head branch (returns empty string if none / gh missing)
+# TODO: For fork workflows, add --repo flag to scope to intended base repo
+#   e.g., gh pr list --repo owner/repo --head ...
+get_open_pr_url_for_head() {
+    local head_branch="$1"
+
+    if ! command -v gh >/dev/null 2>&1; then
+        echo ""
+        return
+    fi
+
+    gh pr list \
+        --head "$head_branch" \
+        --state open \
+        --limit 1 \
+        --json url \
+        --jq '.[0].url' 2>/dev/null || echo ""
+}
+
+ensure_pr_for_head() {
+    local head_branch="$1"
+    local base_branch="$2"
+    local title="$3"
+    local body="$4"
+
+    if ! command -v gh >/dev/null 2>&1; then
+        log_warn "PR" "gh cli not found"
+        HAS_WARNINGS=true
+        return 1
+    fi
+
+    local existing_url
+    existing_url=$(get_open_pr_url_for_head "$head_branch")
+    if [ -n "$existing_url" ]; then
+        log_ok "PR" "$existing_url (existing)"
+        CREATED_PR_URL="$existing_url"
+        return 0
+    fi
+
+    local pr_url
+    pr_url=$(gh pr create --head "$head_branch" --base "$base_branch" --title "$title" --body "$body" 2>&1) || true
+    if echo "$pr_url" | grep -Eq "^https?://"; then
+        log_ok "PR" "$pr_url"
+        CREATED_PR_URL="$pr_url"
+        return 0
+    fi
+
+    log_warn "PR" "creation failed: $pr_url"
+    HAS_WARNINGS=true
+    return 1
+}
+
+# After the route branch is pushed, move local base branch back to its upstream so
+# the routed commits are not also left on main. Rewinds only when every commit on the
+# local base is contained in the route branch (base is an ancestor of, or equal to,
+# routed_sha) and the upstream is an ancestor of base. Not checked out: compare-and-swap
+# update-ref against the base's current tip. Checked out: HEAD must still be that tip,
+# then one reset --keep, which refuses (changing nothing) if local changes conflict.
+rewind_base_after_route() {
+    local base_branch="$1" routed_sha="$2" up_sha base_sha
+    up_sha=$(git rev-parse -q --verify "$base_branch@{u}" 2>/dev/null || echo "")
+    [ -n "$up_sha" ] && [ -n "$routed_sha" ] || return 0
+    base_sha=$(git rev-parse -q --verify "refs/heads/$base_branch" 2>/dev/null || echo "")
+    [ -n "$base_sha" ] || return 0
+    [ "$up_sha" != "$base_sha" ] || return 0
+    git merge-base --is-ancestor "$base_sha" "$routed_sha" 2>/dev/null || return 0
+    git merge-base --is-ancestor "$up_sha" "$base_sha" 2>/dev/null || return 0
+    if [ "$(git symbolic-ref -q --short HEAD 2>/dev/null)" = "$base_branch" ]; then
+        if [ "$(git rev-parse HEAD 2>/dev/null)" = "$base_sha" ] \
+            && git reset --keep "$up_sha" >/dev/null 2>&1; then
+            log_dim "Rewind" "$base_branch to upstream (commits are on the route branch)"
+        else
+            log_warn "Rewind" "$base_branch left at $base_sha (changed or local changes block the reset); commits are on the route branch"
+            HAS_WARNINGS=true
+        fi
+    elif git update-ref "refs/heads/$base_branch" "$up_sha" "$base_sha" 2>/dev/null; then
+        log_dim "Rewind" "$base_branch to upstream (commits are on the route branch)"
+    else
+        log_warn "Rewind" "$base_branch changed concurrently; left as is"
+        HAS_WARNINGS=true
+    fi
+}
+
+# Print the PR number from a PR URL (build ci merge takes a number, not a URL)
+pr_number_from_url() {
+    echo "${1:-}" | sed -n 's|.*/pull/\([0-9][0-9]*\).*|\1|p'
+}
+
+route_main_head_to_pr() {
+    local base_branch="$1"   # main/master
+    local stay_on_main="$2"  # true/false
+    local short_sha
+    local route_branch
+    local pr_title
+    local pr_body
+    local routed_sha
+
+    short_sha=$(git rev-parse --short=7 HEAD 2>/dev/null || echo "")
+    if [ -z "$short_sha" ]; then
+        log_err "Route-main" "failed to resolve HEAD"
+        return 1
+    fi
+
+    route_branch="wip/route-main/$short_sha"
+    routed_sha=$(git rev-parse HEAD 2>/dev/null || echo "")
+
+    # Create/reset local route branch at current HEAD, then checkout
+    if ! git checkout -B "$route_branch" HEAD >/dev/null 2>&1; then
+        log_err "Route-main" "checkout failed: $route_branch"
+        return 1
+    fi
+    CURRENT_BRANCH="$route_branch"
+
+    # Publish route branch (idempotent for same HEAD)
+    if ! run_git_push -u origin "$route_branch"; then
+        log_err "Push" "failed: origin/$route_branch"
+        log_git_push_reason
+        # Do not strand the checkout on the ephemeral route branch; nothing was published,
+        # so base is not rewound and the commits stay on the local route branch.
+        if git checkout "$base_branch" >/dev/null 2>&1; then
+            CURRENT_BRANCH="$base_branch"
+            log_dim "Route-main" "commits kept on local branch $route_branch; $base_branch checked out"
+        else
+            log_err "Checkout" "failed: $base_branch (stranded on $route_branch)"
+            HAS_WARNINGS=true
+        fi
+        return 1
+    fi
+    log_ok "Push" "origin/$route_branch"
+    UPSTREAM_EXISTS=true
+    UPSTREAM_BRANCH="origin/$route_branch"
+
+    # Ensure PR for the route branch (always ensure; routing implies intent)
+    pr_title="Route ${base_branch}: $(git log -1 --pretty=%s 2>/dev/null || echo "$short_sha")"
+    pr_body=$(build_sync_pr_body "route-main" "$route_branch" "$base_branch")
+    local pr_rc=0
+    ensure_pr_for_head "$route_branch" "$base_branch" "$pr_title" "$pr_body" || pr_rc=$?
+
+    # Return to base branch so agents are not stranded on an ephemeral wip/route-main/* branch.
+    if ! git checkout "$base_branch" >/dev/null 2>&1; then
+        log_err "Checkout" "failed: $base_branch (stranded on $route_branch)"
+        HAS_WARNINGS=true
+    else
+        log_dim "Checkout" "$base_branch"
+        CURRENT_BRANCH="$base_branch"
+        rewind_base_after_route "$base_branch" "$routed_sha"
+        # Fast-forward local base branch if behind origin (fetch already ran)
+        local behind_count
+        behind_count=$(git rev-list --count "HEAD..origin/$base_branch" 2>/dev/null || echo "0")
+        if [ "$behind_count" -gt 0 ]; then
+            if git merge --ff-only "origin/$base_branch" >/dev/null 2>&1; then
+                log_dim "Sync" "$base_branch (ff +$behind_count)"
+            else
+                log_warn "Sync" "$base_branch diverged from origin (ff-only rejected)"
+                HAS_WARNINGS=true
+            fi
+        fi
+    fi
+
+    if [ "$pr_rc" -ne 0 ]; then
+        log_err "Route-main" "incomplete: PR not created; commits are on origin/$route_branch"
+        log_dim "Next" "gh pr create --head $route_branch --base $base_branch"
+        return 1
+    fi
+    log_dim "Next" "after review: build ci merge $(pr_number_from_url "$CREATED_PR_URL") --sha $routed_sha"
+
+    return 0
+}
+
+# Reset PR URL tracking for this sync run (prevents stale values from previous iterations)
+CREATED_PR_URL=""
+
+# Status/PR-only should never mutate the repo
+if [ "$STATUS_ONLY" = true ] || [ "$PR_ONLY" = true ]; then
+    DRY_RUN=true
+fi
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || true)
+DETACHED_HEAD=false
+DETACHED_HEAD_SHA=""
+if [ -z "$CURRENT_BRANCH" ]; then
+    if [ "$STATUS_ONLY" = true ]; then
+        DETACHED_HEAD=true
+        DETACHED_HEAD_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+        CURRENT_BRANCH="HEAD"
+        log_dim "Branch" "detached HEAD ($DETACHED_HEAD_SHA)"
+    else
+        log_err "Branch" "detached HEAD"
+        exit 1
+    fi
+fi
+
+# Create safety backup branch (before any operations)
+BACKUP_BRANCH=""
+BACKUP_BRANCH_CREATED=false
+RECOVERY_BRANCH=""
+
+# Create backup branch lazily (only before first mutating operation)
+ensure_backup_branch() {
+    if [ "$BACKUP_BRANCH_CREATED" = true ]; then return 0; fi
+    if [ "$DRY_RUN" = true ]; then return 0; fi
+    BACKUP_BRANCH="backup/pre-sync-$(date +%s)"
+    if git branch "$BACKUP_BRANCH" >/dev/null 2>&1; then
+        BACKUP_BRANCH_CREATED=true
+        log_dim "Checkpoint" "$BACKUP_BRANCH"
+    else
+        log_err "Checkpoint" "failed to create backup"
+        exit 1
+    fi
+}
+
+# Print recovery hint: use backup branch if created, otherwise point to reflog/ORIG_HEAD
+print_recovery_hint() {
+    echo ""
+    if [ "$BACKUP_BRANCH_CREATED" = true ]; then
+        echo "Your work is safe in: $BACKUP_BRANCH"
+    else
+        echo "Your work is safe in git reflog (run: git reflog show HEAD)"
+    fi
+    echo ""
+}
+
+# Retention window for pruning stale backup branches (env-only knob; not a config key).
+#   unset/empty -> 7 days; off|never -> pruning disabled; integer (0 allowed) -> days,
+#   where 0 disables the age gate. Anything else falls back to 7 (fail-closed default).
+get_backup_retention_days() {
+    local v="${BUILD_SYNC_BACKUP_RETENTION_DAYS:-}"
+    case "$v" in
+        "") echo 7 ;;
+        off|never) echo disabled ;;
+        *)
+            # Digit cap avoids arithmetic overflow; 10# forces base-10 so leading
+            # zeroes ("08") cannot trigger bash octal-parse errors mid-cleanup.
+            if [[ "$v" =~ ^[0-9]{1,4}$ ]]; then
+                echo "$((10#$v))"
+            else
+                echo 7
+            fi
+            ;;
+    esac
+}
+
+# Reap backup/pre-sync-* branches orphaned by prior failed/interrupted runs.
+# Lossless-only: a branch is deleted ONLY when its content is provably preserved —
+# tip is an ancestor of HEAD, or a linear (merge-free) range whose every commit is
+# patch-equivalent to one in HEAD. Any safety-check failure retains the branch
+# (false-keep is harmless; false-delete is forbidden). Never touches the current
+# run's checkpoint, branches checked out in other worktrees, or exit/warning state.
+prune_stale_backup_branches() {
+    local retention_days now cutoff pruned=0 kept=""
+    retention_days=$(get_backup_retention_days)
+    [ "$retention_days" = "disabled" ] && return 0
+    now=$(date +%s)
+    cutoff=$((now - retention_days * 86400))
+
+    # Fail-closed: if the worktree list cannot be read, skip pruning this run
+    # (we cannot prove a candidate branch is not checked out elsewhere).
+    local wt_list
+    wt_list=$(git worktree list --porcelain 2>/dev/null) || return 0
+
+    local name epoch tip safe merges cherry_out
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        [ "$name" = "${BACKUP_BRANCH:-}" ] && continue
+        epoch="${name##*-}"
+        [[ "$epoch" =~ ^[0-9]{1,12}$ ]] || continue
+        [ "$epoch" -le "$cutoff" ] || continue
+        tip=$(git rev-parse --verify --quiet "refs/heads/$name^{commit}") || continue
+
+        safe=false
+        if git merge-base --is-ancestor "$tip" HEAD 2>/dev/null; then
+            safe=true
+        else
+            # cherry is patch-id based and blind to merge commits: only trust it on
+            # merge-free ranges, and only when it ran successfully (fail-closed).
+            merges=$(git rev-list --merges "HEAD..$tip" 2>/dev/null) || merges="unknown"
+            if [ -z "$merges" ]; then
+                if cherry_out=$(git cherry HEAD "$tip" 2>/dev/null); then
+                    # here-string, not a pipeline: under pipefail a grep -q early
+                    # exit can SIGPIPE the writer and invert the safety verdict
+                    if ! grep -q '^+' <<<"$cherry_out"; then
+                        safe=true
+                    fi
+                fi
+            fi
+        fi
+        if [ "$safe" != true ]; then
+            kept="$kept $name"
+            continue
+        fi
+
+        # Skip branches checked out in any worktree (shared branch namespace), then
+        # compare-and-swap delete against the verified tip so a moved ref is never pruned.
+        if grep -qxF "branch refs/heads/$name" <<<"$wt_list"; then
+            continue
+        fi
+        if git update-ref -d "refs/heads/$name" "$tip" 2>/dev/null; then
+            pruned=$((pruned + 1))
+        fi
+    done < <(git for-each-ref --format='%(refname:short)' 'refs/heads/backup/pre-sync-*' 2>/dev/null)
+
+    if [ "$pruned" -gt 0 ]; then
+        log_dim "Cleanup" "pruned $pruned stale backup branch(es)"
+    fi
+    if [ -n "$kept" ]; then
+        log_dim "Cleanup" "kept stale backup(s) with unique commits:$kept (inspect: git log HEAD..<name>)"
+    fi
+    return 0
+}
+
+# Get main branch name (main or master)
+# TODO: Support exotic default branches (e.g., develop) via:
+#   git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
+#   or: gh repo view --json defaultBranchRef -q .defaultBranchRef.name
+if git show-ref --verify --quiet refs/heads/main; then
+    MAIN_BRANCH="main"
+elif git show-ref --verify --quiet refs/heads/master; then
+    MAIN_BRANCH="master"
+else
+    log_err "Branch" "no main or master found"
+    exit 1
+fi
+
+# Resolve route-main effective setting (flag overrides config)
+ROUTE_MAIN_EFFECTIVE=false
+if [ "$NO_ROUTE_MAIN" = true ]; then
+    ROUTE_MAIN_EFFECTIVE=false
+elif [ "$ROUTE_MAIN_FORCE" = true ]; then
+    ROUTE_MAIN_EFFECTIVE=true
+else
+    ROUTE_MAIN_DEFAULT=$(get_route_main_default)
+    if is_truthy "$ROUTE_MAIN_DEFAULT"; then
+        ROUTE_MAIN_EFFECTIVE=true
+    fi
+fi
+
+# Backup branch is created lazily via ensure_backup_branch() before first mutating op
+
+# Check for uncommitted changes
+CHANGED_FILES=$(git status --porcelain)
+HAS_CHANGES=false
+HAS_TRACKED_CHANGES=false
+HAS_UNTRACKED_ONLY=false
+
+if [ -n "$CHANGED_FILES" ]; then
+    HAS_CHANGES=true
+
+    # Distinguish tracked changes from untracked-only (??) or ignored (!!)
+    # Git porcelain format: XY where X=index status, Y=worktree status
+    # Blacklist approach: exclude lines starting with ? or ! (covers all tracked codes)
+    TRACKED_CHANGES=$(echo "$CHANGED_FILES" | grep -Ev "^[\?!]" || true)
+    if [ -n "$TRACKED_CHANGES" ]; then
+        HAS_TRACKED_CHANGES=true
+    else
+        HAS_UNTRACKED_ONLY=true
+    fi
+fi
+
+# Auto-detect mode: if clean and no message, assume sync mode
+if [ "$PR_ONLY" = false ] && [ "$STATUS_ONLY" = false ] && [ "$HAS_CHANGES" = false ] && [ -z "$COMMIT_MESSAGE" ] && [ "$SYNC_MODE" = false ]; then
+    log_dim "Mode" "clean — switching to sync"
+    SYNC_MODE=true
+fi
+
+# Status/PR-only: force non-mutating "sync-style" control flow (skip commit/push phases)
+if [ "$STATUS_ONLY" = true ] || [ "$PR_ONLY" = true ]; then
+    SYNC_MODE=true
+fi
+
+# ============================================================================
+# Route-main pre-commit guardrail bypass (commit on a non-protected branch)
+# ============================================================================
+# If route-main is enabled and we're on main/master in commit mode, switch to a
+# temporary route branch BEFORE the protected-branch check so we never commit on
+# main/master (avoids requiring BUILD_ALLOW_MAIN_COMMIT in non-interactive runs).
+if [ "$DRY_RUN" = false ] && [ "$SYNC_MODE" = false ] && [ "$STATUS_ONLY" = false ] && [ "$PR_ONLY" = false ]; then
+    if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ] && [ "$ROUTE_MAIN_EFFECTIVE" = true ]; then
+        ensure_backup_branch
+        ROUTE_MAIN_MODE_ACTIVE=true
+        ROUTE_MAIN_WIP_BRANCH="wip/route-main/wip-$(date +%s)"
+        if ! git checkout -B "$ROUTE_MAIN_WIP_BRANCH" >/dev/null 2>&1; then
+            log_err "Route-main" "branch creation failed"
+            exit 1
+        fi
+        CURRENT_BRANCH="$ROUTE_MAIN_WIP_BRANCH"
+    fi
+fi
+
+# ============================================================================
+# GUARDRAIL 1: Protected Branch Check (Soft by Default)
+# ============================================================================
+# Modes: off (no message), warn (print warning, proceed), confirm (prompt y/N), block (always block)
+# Configure: BUILD_PROTECT_MAIN=<mode> or build config set --scope user sync.protectMain <mode>
+# Default: confirm (interactive prompt when TTY, block when non-TTY unless BUILD_ALLOW_MAIN_COMMIT=1)
+
+if [ "$FORCE" = false ] && [ "$NO_PROTECT_MAIN" = false ]; then
+    # Define protected branches (main, master, and any branch starting with release/)
+    IS_PROTECTED=false
+    if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
+        IS_PROTECTED=true
+    elif [[ "$CURRENT_BRANCH" == release/* ]]; then
+        IS_PROTECTED=true
+    fi
+
+    if [ "$DRY_RUN" = false ] && [ "$IS_PROTECTED" = true ] && [ "$SYNC_MODE" = false ] && [ "$STATUS_ONLY" = false ] && [ "$PR_ONLY" = false ]; then
+        PROTECT_MODE=$(get_protect_main_mode)
+
+        case "$PROTECT_MODE" in
+            off)
+                # No message, proceed silently
+                ;;
+            warn)
+                # Print warning to stderr, proceed
+                printf "  ${YELLOW}%-16s %s${NC}\n" "Protect-main" "committing to '$CURRENT_BRANCH'" >&2
+                ;;
+            block)
+                # Always block (original behavior)
+                echo ""
+                log_err "Blocked" "commits to '$CURRENT_BRANCH' are not allowed"
+                echo ""
+                echo "    To change this behavior:"
+                echo "    build config set --scope user sync.protectMain confirm  # Interactive prompt"
+                echo "    build config set --scope user sync.protectMain warn     # Warn and proceed"
+                echo "    build config set --scope user sync.protectMain off      # No protection"
+                echo ""
+                echo "    Or bypass for this run:"
+                echo "    build sync --no-protect-main"
+                echo ""
+                [ "$BACKUP_BRANCH_CREATED" = true ] && git branch -D "$BACKUP_BRANCH" >/dev/null 2>&1 || true
+                exit 1
+                ;;
+            confirm|*)
+                # Default: Interactive confirm when TTY, block otherwise
+                # Robust TTY check: both stdin AND stdout must be terminals
+                # Note: This is intentionally strict - redirected stdin with TTY stdout
+                # still goes to non-interactive path (safer default for piped input)
+                if [ -t 0 ] && [ -t 1 ]; then
+                    # Interactive terminal - prompt user
+                    echo ""
+                    printf "  ${YELLOW}%-16s %s${NC}\n" "Protect-main" "committing to '$CURRENT_BRANCH'"
+                    echo -n "Continue? [y/N] "
+
+                    # Read with timeout (5s) to prevent hanging on weird stdin states
+                    # Empty input or timeout = "No" (safe default)
+                    # Note: if statement captures exit code, safe with set -e
+                    if read -r -n 1 -t 5 response 2>/dev/null; then
+                        echo ""  # newline after single char input
+                    else
+                        # Timeout or read error - treat as "No"
+                        echo ""
+                        log_dim "Confirm" "timed out — treating as no"
+                        response="n"
+                    fi
+
+                    if [[ ! "$response" =~ ^[Yy]$ ]]; then
+                        log_dim "Confirm" "aborted"
+                        [ "$BACKUP_BRANCH_CREATED" = true ] && git branch -D "$BACKUP_BRANCH" >/dev/null 2>&1 || true
+                        exit 1  # Exit non-zero: user declined or timeout
+                    fi
+                else
+                    # Non-interactive (CI/script) - check for explicit allow
+                    if [ "${BUILD_ALLOW_MAIN_COMMIT:-}" = "1" ]; then
+                        printf "  ${YELLOW}%-16s %s${NC}\n" "Protect-main" "committing to '$CURRENT_BRANCH' (BUILD_ALLOW_MAIN_COMMIT=1)" >&2
+                    else
+                        echo ""
+                        log_err "Blocked" "non-interactive commit to '$CURRENT_BRANCH'"
+                        echo ""
+                        echo "    For CI/scripts, set:"
+                        echo "    BUILD_ALLOW_MAIN_COMMIT=1"
+                        echo ""
+                        echo "    Or change default mode:"
+                        echo "    build config set --scope user sync.protectMain warn"
+                        echo ""
+                        [ "$BACKUP_BRANCH_CREATED" = true ] && git branch -D "$BACKUP_BRANCH" >/dev/null 2>&1 || true
+                        exit 1
+                    fi
+                fi
+                ;;
+        esac
+    fi
+fi
+
+# ============================================================================
+# GUARDRAIL 2: Orphaned Branch Work Detection
+# ============================================================================
+# Warn if there are local branches with unpushed commits that might be lost
+# Scoped to: branches ahead of upstream OR commits not reachable from target ref
+# Filtered to: only branches with activity in last 7 days (reduces noise)
+# Note: Only runs when committing (HAS_CHANGES=true), not during sync-only
+# Throttle: only show orphan warning once per 24h (timestamp file under the
+# user's Build state directory, keyed by a hash of the repo root; without a
+# hash tool the warning is simply not throttled)
+if [ -n "${BUILD_HOME:-}" ]; then
+    ORPHAN_BUILD_HOME="$BUILD_HOME"
+    case "$ORPHAN_BUILD_HOME" in
+        '~') ORPHAN_BUILD_HOME="$HOME" ;;
+        '~/'*) ORPHAN_BUILD_HOME="$HOME/${ORPHAN_BUILD_HOME#\~/}" ;;
+    esac
+    ORPHAN_STATE_DIR="${ORPHAN_BUILD_HOME%/}/state/sync"
+elif [ -n "${XDG_STATE_HOME:-}" ]; then
+    ORPHAN_STATE_DIR="${XDG_STATE_HOME%/}/build/sync"
+else
+    ORPHAN_STATE_DIR="$HOME/.build/state/sync"
+fi
+ORPHAN_REPO_KEY=$(printf '%s' "$REPO_ROOT" | { shasum -a 256 2>/dev/null || sha256sum 2>/dev/null; } | cut -c1-12 || true)
+ORPHAN_THROTTLE_FILE=""
+if [ -n "$ORPHAN_REPO_KEY" ]; then
+    ORPHAN_THROTTLE_FILE="$ORPHAN_STATE_DIR/orphan-warn-$ORPHAN_REPO_KEY"
+fi
+ORPHAN_THROTTLED=false
+if [ -n "$ORPHAN_THROTTLE_FILE" ] && [ -f "$ORPHAN_THROTTLE_FILE" ]; then
+    LAST_WARN=$(cat "$ORPHAN_THROTTLE_FILE" 2>/dev/null || echo "0")
+    NOW_TS=$(date +%s)
+    if [ $((NOW_TS - LAST_WARN)) -lt 86400 ]; then
+        ORPHAN_THROTTLED=true
+    fi
+fi
+
+if [ "$NO_ORPHAN_WARN" = false ] && [ "$ORPHAN_THROTTLED" = false ] && [ "$HAS_CHANGES" = true ] && [ "$STATUS_ONLY" = false ] && [ "$PR_ONLY" = false ]; then
+    ORPHANED_WORK=""
+    SEVEN_DAYS_AGO=$(( $(date +%s) - 604800 ))  # 7 days = 604800 seconds (portable)
+
+    # Check for local branches ahead of their upstream (unpushed work)
+    while IFS= read -r branch; do
+        # Skip current branch and backup branches
+        if [ "$branch" = "$CURRENT_BRANCH" ] || [[ "$branch" == backup/* ]]; then
+            continue
+        fi
+
+        # Filter: Only check branches with recent activity (last 7 days)
+        LAST_COMMIT_TIME=$(git log -1 --format=%ct "$branch" 2>/dev/null || echo "0")
+        if [ "$LAST_COMMIT_TIME" -lt "$SEVEN_DAYS_AGO" ]; then
+            continue  # Skip stale branches to reduce noise
+        fi
+
+        # Check if branch has upstream
+        UPSTREAM=$(git rev-parse --abbrev-ref "$branch@{u}" 2>/dev/null || echo "")
+        if [ -n "$UPSTREAM" ]; then
+            # Count commits ahead of upstream
+            AHEAD_COUNT=$(git rev-list --count "$UPSTREAM..$branch" 2>/dev/null || echo "0")
+            if [ "$AHEAD_COUNT" -gt 0 ]; then
+                ORPHANED_WORK="${ORPHANED_WORK}    $branch: $AHEAD_COUNT unpushed commit(s)\n"
+            fi
+        else
+            # No upstream - check if it has commits not on current branch
+            UNIQUE_COMMITS=$(git rev-list --count "$CURRENT_BRANCH..$branch" 2>/dev/null || echo "0")
+            if [ "$UNIQUE_COMMITS" -gt 0 ]; then
+                ORPHANED_WORK="${ORPHANED_WORK}    $branch: $UNIQUE_COMMITS commit(s) not on $CURRENT_BRANCH (no upstream)\n"
+            fi
+        fi
+    done < <(git for-each-ref --format='%(refname:short)' refs/heads/)
+
+    if [ -n "$ORPHANED_WORK" ]; then
+        echo ""
+        log_warn "Orphaned" "unpushed work on other branches (last 7 days):"
+        echo -e "$ORPHANED_WORK"
+        echo "    Current branch: $CURRENT_BRANCH"
+        echo "    Suppress: build sync --no-orphan-warn"
+        echo ""
+
+        # Don't block, just warn prominently (user can --no-orphan-warn if intentional)
+        # This is a warning, not a hard block, per Codex's feedback
+        HAS_WARNINGS=true
+        # Throttle: don't show again for 24h
+        if [ -n "$ORPHAN_THROTTLE_FILE" ]; then
+            (umask 077 && mkdir -p "$ORPHAN_STATE_DIR") 2>/dev/null || true
+            date +%s > "$ORPHAN_THROTTLE_FILE" 2>/dev/null || true
+        fi
+    fi
+fi
+
+# DRY RUN HEADER
+if [ "$DRY_RUN" = true ]; then
+    log_warn "Mode" "dry run — no changes will be made"
+fi
+
+# STEP 0: Fetch from remote(s) (ALWAYS do this first)
+# Smart remote: fetch only the upstream's remote (usually origin) when single-remote.
+# Fall back to --all only when multiple remotes are configured.
+FETCH_REMOTE="origin"
+REMOTE_COUNT=$(git remote 2>/dev/null | wc -l | tr -d ' ')
+if [ "$REMOTE_COUNT" -gt 1 ]; then
+    # Multiple remotes: check if branch's upstream points to a specific one
+    UPSTREAM_REMOTE=$(git config "branch.${CURRENT_BRANCH}.remote" 2>/dev/null || echo "")
+    if [ -n "$UPSTREAM_REMOTE" ]; then
+        FETCH_REMOTE="$UPSTREAM_REMOTE"
+    else
+        FETCH_REMOTE="--all"
+    fi
+fi
+
+SYNC_FETCH_DONE=false
+if [ "$DRY_RUN" = false ]; then
+    if [ "$FETCH_REMOTE" = "--all" ]; then
+        if git fetch --all --prune >/dev/null 2>&1; then
+            log_ok "Fetch" "done (all remotes)"
+            SYNC_FETCH_DONE=true
+        else
+            log_warn "Fetch" "completed with warnings"
+        fi
+    else
+        if git fetch "$FETCH_REMOTE" --prune >/dev/null 2>&1; then
+            log_ok "Fetch" "done"
+            SYNC_FETCH_DONE=true
+        else
+            log_warn "Fetch" "completed with warnings"
+        fi
+    fi
+else
+    echo "Would fetch from ${FETCH_REMOTE}"
+fi
+
+# STEP 1: Check upstream tracking (cache result for reuse)
+if [ "$DETACHED_HEAD" = true ]; then
+    UPSTREAM_EXISTS=false
+    UPSTREAM_BRANCH=""
+    log_dim "Upstream" "not applicable (detached HEAD)"
+elif git rev-parse --abbrev-ref --symbolic-full-name "@{u}" >/dev/null 2>&1; then
+    UPSTREAM_EXISTS=true
+    UPSTREAM_BRANCH=$(git rev-parse --abbrev-ref --symbolic-full-name "@{u}")
+else
+    if [ "$ROUTE_MAIN_MODE_ACTIVE" = true ]; then
+        log_dim "Upstream" "not configured (route-main work branch)"
+    else
+        log_warn "Upstream" "not configured"
+        HAS_WARNINGS=true
+    fi
+
+    if [ "$DRY_RUN" = false ]; then
+        # Use the resolved fetch remote (respects multi-remote setups)
+        UPSTREAM_CANDIDATE="${FETCH_REMOTE}"
+        # If FETCH_REMOTE is --all, fall back to origin for upstream detection
+        [ "$UPSTREAM_CANDIDATE" = "--all" ] && UPSTREAM_CANDIDATE="origin"
+
+        # Check if remote branch exists using local refs (fetch already ran, no network needed)
+        if git show-ref --verify --quiet "refs/remotes/${UPSTREAM_CANDIDATE}/$CURRENT_BRANCH" 2>/dev/null; then
+            log_dim "Upstream" "setting to ${UPSTREAM_CANDIDATE}/$CURRENT_BRANCH"
+            git branch --set-upstream-to="${UPSTREAM_CANDIDATE}/$CURRENT_BRANCH" "$CURRENT_BRANCH"
+            log_ok "Upstream" "configured"
+            UPSTREAM_EXISTS=true
+            UPSTREAM_BRANCH="${UPSTREAM_CANDIDATE}/$CURRENT_BRANCH"
+        else
+            log_dim "Upstream" "remote branch not yet created"
+        fi
+    else
+        echo "Would set upstream to ${FETCH_REMOTE}/$CURRENT_BRANCH (if exists)"
+    fi
+fi
+
+# Compute TRACKED_BRANCHES once (both branch and upstream columns) for reuse everywhere.
+# Format: "branch_name upstream_ref" per line (e.g., "main origin/main")
+# Includes any branch with a non-empty upstream (not limited to origin).
+TRACKED_BRANCHES=$(git for-each-ref --format='%(if)%(upstream:short)%(then)%(refname:short) %(upstream:short)%(end)' refs/heads/ | grep -v '^$' || true)
+
+# SYNC MODE: Pull all branches and report status
+if [ "$SYNC_MODE" = true ]; then
+    if [ "$DRY_RUN" = false ]; then
+        if git rev-parse --abbrev-ref --symbolic-full-name "@{u}" >/dev/null 2>&1; then
+            # Early-exit optimization: skip pull if already synced
+            AHEAD=$(git rev-list --count "@{u}..HEAD" 2>/dev/null || echo "0")
+            BEHIND=$(git rev-list --count "HEAD..@{u}" 2>/dev/null || echo "0")
+
+            if [ "$AHEAD" -eq 0 ] && [ "$BEHIND" -eq 0 ] && [ "$HAS_CHANGES" = false ] && [ "$ALL_BRANCHES" = false ]; then
+                log_ok "$CURRENT_BRANCH" "up-to-date"
+            else
+                # Pull using shared helper (stash → pull → conflict-abort → unstash)
+                if do_pull_with_stash; then
+                    log_ok "Pull" "$CURRENT_BRANCH"
+
+                    # Bidirectional sync: push if local is ahead
+                    AHEAD_AFTER_PULL=$(git rev-list --count "@{u}..HEAD" 2>/dev/null || echo "0")
+                    if [ "$AHEAD_AFTER_PULL" -gt 0 ]; then
+                        # --pr on main means "never push main directly": route via a PR branch
+                        if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ] && [ "$NO_SYNC_PUSH" = false ] && { [ "$ROUTE_MAIN_EFFECTIVE" = true ] || [ "$CREATE_PR" = true ]; }; then
+                            ROUTE_MAIN_NEEDED=true
+                            ROUTE_MAIN_AHEAD_COUNT="$AHEAD_AFTER_PULL"
+                            log_dim "Route-main" "$AHEAD_AFTER_PULL commit(s) ahead — routing via PR"
+                        elif [ "$NO_SYNC_PUSH" = false ]; then
+                            if run_git_push; then
+                                log_ok "Push" "$UPSTREAM_BRANCH"
+                                PUSH_SUCCESS=true
+                            else
+                                log_warn "Push" "failed — push manually"
+                                log_git_push_reason
+                                HAS_WARNINGS=true
+                            fi
+                        else
+                            log_dim "Push" "skipped ($AHEAD_AFTER_PULL ahead, sync push disabled)"
+                        fi
+                    fi
+                else
+                    SYNC_SUCCESS=false
+                    print_recovery_hint
+                    echo "To resolve manually:"
+                    echo "  1. git pull --rebase (or --merge)"
+                    echo "  2. Resolve conflicts in affected files"
+                    echo "  3. git add <resolved-files>"
+                    echo "  4. git rebase --continue (or git commit)"
+                    echo "  5. Run build sync again to push"
+                    exit 1
+                fi
+            fi
+        else
+            # No upstream: optionally auto-publish (push -u) to establish tracking
+            if [ "$NO_SYNC_PUSH" = true ]; then
+                log_dim "Pull" "no upstream (--no-sync-push)"
+            else
+                MAIN_REMOTE_REF=""
+                if git show-ref --verify --quiet "refs/remotes/origin/$MAIN_BRANCH"; then
+                    MAIN_REMOTE_REF="origin/$MAIN_BRANCH"
+                elif git show-ref --verify --quiet "refs/remotes/origin/master"; then
+                    MAIN_REMOTE_REF="origin/master"
+                fi
+                if [ -z "$MAIN_REMOTE_REF" ]; then
+                    MAIN_REMOTE_REF="$MAIN_BRANCH"
+                fi
+
+                UNIQUE_TO_MAIN=$(git rev-list --count "$MAIN_REMOTE_REF..HEAD" 2>/dev/null || echo "0")
+
+                if [ "$UNIQUE_TO_MAIN" -gt 0 ] && should_publish_new_branch "$CURRENT_BRANCH"; then
+                    if run_git_push -u origin "$CURRENT_BRANCH"; then
+                        log_ok "Push" "origin/$CURRENT_BRANCH (set upstream)"
+                        PUSH_SUCCESS=true
+                        UPSTREAM_EXISTS=true
+                        UPSTREAM_BRANCH="origin/$CURRENT_BRANCH"
+                    else
+                        log_warn "Push" "auto-publish failed"
+                        log_git_push_reason
+                        HAS_WARNINGS=true
+                    fi
+                elif [ "$UNIQUE_TO_MAIN" -eq 0 ]; then
+                    log_dim "Push" "skipped (no commits beyond $MAIN_REMOTE_REF)"
+                else
+                    log_dim "Push" "publishing disabled (use --publish)"
+                fi
+            fi
+        fi
+
+                # Sync all branches if requested
+                if [ "$ALL_BRANCHES" = true ]; then
+                    # Keep strategy local to this block (PULL_STRATEGY is not a global).
+                    pull_strategy_all="--rebase=merges"
+                    if [ "$REBASE" = false ]; then
+                        pull_strategy_all="--merge"
+                    fi
+
+                    # Iterate branch names from TRACKED_BRANCHES (computed after fetch)
+                    # Process substitution keeps the loop in this shell so HAS_WARNINGS survives.
+                    while IFS= read -r branch; do
+                        [ -z "$branch" ] && continue
+                        if [ "$branch" != "$CURRENT_BRANCH" ]; then
+                            if git checkout -q "$branch" 2>/dev/null; then
+                                op_before=$(git_op_in_progress)
+                                if ! git pull -q "$pull_strategy_all" >/dev/null 2>&1; then
+                                    # Undo only a rebase/merge this pull started, so the loop can move on
+                                    if [ -z "$op_before" ]; then
+                                        case "$(git_op_in_progress)" in
+                                            rebase) git rebase --abort >/dev/null 2>&1 || true ;;
+                                            merge) git merge --abort >/dev/null 2>&1 || true ;;
+                                        esac
+                                    fi
+                                    log_warn "$branch" "pull failed — skipped"
+                                    HAS_WARNINGS=true
+                                else
+                                    local_ahead=$(git rev-list --count "@{u}..HEAD" 2>/dev/null || echo "0")
+                                    if [ "$local_ahead" -gt 0 ]; then
+                                        if [ "$PUSH_ALL_BRANCHES" = true ] && [ "$NO_SYNC_PUSH" = false ]; then
+                                            if run_git_push -q; then
+                                                log_dim "$branch" "pushed $local_ahead commit(s)"
+                                            else
+                                                log_warn "$branch" "push failed ($local_ahead ahead)"
+                                                log_git_push_reason
+                                                HAS_WARNINGS=true
+                                            fi
+                                        else
+                                            log_dim "$branch" "$local_ahead commit(s) ahead"
+                                        fi
+                                    fi
+                                fi
+                            fi
+                        fi
+                    done < <(echo "$TRACKED_BRANCHES" | awk '{print $1}')
+
+                    # Return to original branch
+                    if ! git checkout -q "$CURRENT_BRANCH" 2>/dev/null; then
+                        log_err "Sync" "could not return to $CURRENT_BRANCH (now on $(git rev-parse --abbrev-ref HEAD 2>/dev/null))"
+                        echo "  Check 'git status' for an in-progress rebase or merge"
+                        exit 1
+                    fi
+                    log_ok "Sync" "all branches done"
+                fi
+
+	        # Route main only after sync operations complete (keeps stash/branch handling coherent)
+	        if [ "$ROUTE_MAIN_NEEDED" = true ]; then
+	            if route_main_head_to_pr "$MAIN_BRANCH" "$STAY_ON_MAIN"; then
+	                PUSH_SUCCESS=true
+	            else
+	                log_err "Route-main" "failed"
+	                exit 1
+	            fi
+	        fi
+	    else
+	        echo "Would pull latest changes using $([ "$REBASE" = true ] && echo "rebase" || echo "merge")"
+	        if [ "$ALL_BRANCHES" = true ]; then
+	            echo "Would sync all tracked branches"
+	        fi
+    fi
+
+    # Skip to status report
+    SKIP_COMMIT=true
+else
+    SKIP_COMMIT=false
+fi
+
+# STEP 2: Pull current branch BEFORE committing (critical for multi-env)
+if [ "$SKIP_COMMIT" = false ] && [ "$DRY_RUN" = false ]; then
+    if [ "$ROUTE_MAIN_MODE_ACTIVE" = true ]; then
+        # Route-main pre-commit branch has no upstream; rebase/merge onto origin/main
+        PULL_RC=0; do_pull_with_stash --rebase-onto "origin/$MAIN_BRANCH" || PULL_RC=$?
+    else
+        PULL_RC=0; do_pull_with_stash || PULL_RC=$?
+    fi
+
+    if [ "$PULL_RC" -ne 0 ]; then
+        echo ""
+        echo "Please resolve conflicts manually and run build sync again"
+        exit 1
+    fi
+fi
+
+# STEP 3: Stage and Commit (if not sync mode)
+if [ "$SKIP_COMMIT" = false ]; then
+    if [ "$HAS_CHANGES" = false ]; then
+        log_dim "Commit" "nothing to commit"
+    else
+        if [ "$DRY_RUN" = false ]; then
+            # Stage all changes FIRST (so pre-commit checks see what we're about to commit)
+            git add -A
+            STAGED_COUNT=$(git diff --cached --numstat | wc -l | tr -d ' ')
+            log_ok "Staged" "$STAGED_COUNT files"
+
+            # ============================================================================
+            # GUARDRAIL 3: Staged Changes Preview
+            # ============================================================================
+            # Show what's about to be committed for verification
+            if [ "$FORCE" = false ] && [ "$STAGED_COUNT" -gt 10 ]; then
+                echo ""
+                log_warn "Staging" "$STAGED_COUNT files — review below"
+                echo ""
+                # Show summary by directory
+                git diff --cached --stat | tail -20
+                echo ""
+                # Show file types being changed
+                printf "  ${DIM}%-16s${NC}\n" "File types:"
+                git diff --cached --name-only | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5
+                echo ""
+                echo "    Verify this matches your intended changes."
+                echo "    To abort: Ctrl+C then 'git reset HEAD'"
+                echo "    To skip: build sync --force"
+                echo ""
+                # Brief pause for human review (non-blocking in CI)
+                if [ -t 0 ]; then
+                    sleep 2
+                fi
+            fi
+
+            # Pre-commit validation
+            log_dim "Pre-commit" "checking..."
+
+            # Check for sensitive filenames (most reliable check)
+            SENSITIVE_FILES=$(git diff --cached --name-only | grep -E '\.(env|key|pem|p12|pfx|credentials|secret)$|^\.env' || true)
+            if [ -n "$SENSITIVE_FILES" ]; then
+                log_err "Blocked" "sensitive files detected"
+                echo "$SENSITIVE_FILES"
+                echo ""
+                echo "To remove: git reset HEAD <file>"
+                exit 1
+            fi
+
+            # Check for actual secret values (pattern: key="value" or key: "value")
+            # Skip known-safe paths (test fixtures, benchmarks, coverage, etc.)
+            SKIP_SECRET_CHECK='\.build-project/|test-results|benchmarks|coverage|\.test\.|__tests__|fixtures|\.snap$'
+            FILES_TO_CHECK=$(git diff --cached --name-only | grep -vE "$SKIP_SECRET_CHECK" || true)
+
+            SECRET_VALUE_PATTERNS=(
+                '["\x27][a-zA-Z0-9_-]{20,}["\x27].*?(api[_-]?key|password|token|secret)'
+                '(api[_-]?key|password|token|secret)["\x27]?\s*[:=]\s*["\x27][^"\x27]{8,}'
+            )
+
+            SECRETS_FOUND=false
+            FLAGGED_FILES=""
+            if [ -n "$FILES_TO_CHECK" ]; then
+                for pattern in "${SECRET_VALUE_PATTERNS[@]}"; do
+                    # Only check non-allowlisted files
+                    MATCHES=$(git diff --cached -- $FILES_TO_CHECK 2>/dev/null | grep -iE "$pattern" || true)
+                    if [ -n "$MATCHES" ]; then
+                        FLAGGED_FILES=$(git diff --cached --name-only -- $FILES_TO_CHECK | head -10)
+                        SECRETS_FOUND=true
+                        break
+                    fi
+                done
+            fi
+
+            if [ "$SECRETS_FOUND" = true ]; then
+                # WARN instead of BLOCK - let AI/human review
+                log_warn "Secrets" "possible secrets detected in:"
+                echo "$FLAGGED_FILES"
+                echo ""
+                echo "Review these files: git diff --cached <file>"
+                echo "To unstage if needed: git reset HEAD <file>"
+                echo ""
+                # Continue - don't exit (was: exit 1)
+                HAS_WARNINGS=true
+            fi
+
+            # Check for merge conflict markers
+            if git diff --cached | grep -q "^<<<<<<< \|^======= \|^>>>>>>> "; then
+                log_err "Blocked" "merge conflict markers in staged files"
+                echo "Please resolve conflicts before committing"
+                exit 1
+            fi
+
+            # Check for large files (>10MB) - skip interactive prompt for automated workflows
+            LARGE_FILES=$(git diff --cached --name-only | xargs -I {} find {} -type f -size +10M 2>/dev/null || true)
+            if [ -n "$LARGE_FILES" ]; then
+                log_warn "Large files" "detected (>10MB):"
+                echo "$LARGE_FILES"
+                echo ""
+                echo "Consider using Git LFS for large files."
+                echo "To exclude: git reset HEAD <file>"
+                # Don't block - just warn (for automated end-of-day workflow)
+            fi
+
+            if [ "$FORCE" = false ] && { { [ -n "$COMMIT_MESSAGE" ] && cli_refuses_mixed_stage_set; } || { [ "$IS_PROTECTED" = true ] && staged_has_mixed_system_and_code; }; }; then
+                echo ""
+                log_err "Blocked" "mixed planning metadata and code changes staged on protected branch '$CURRENT_BRANCH'"
+                echo ""
+                echo "    This staged set would create a misleading combined sync commit."
+                echo "    Move the work onto a feature/run branch, or split the staged changes first."
+                echo ""
+                echo "    Recommended:"
+                echo "    git reset HEAD task/ sprint/ backlog/"
+                echo "    git checkout -b <run-branch>"
+                echo "    build sync"
+                echo ""
+                exit 1
+            fi
+
+            GENERATED_SYNC_ARTIFACTS=$(get_staged_generated_artifacts)
+            if [ -n "$GENERATED_SYNC_ARTIFACTS" ]; then
+                generated_count=$(echo "$GENERATED_SYNC_ARTIFACTS" | wc -l | tr -d ' ')
+                log_dim "Generated" "$generated_count generated artifact(s) staged"
+                if [ "$ROUTE_MAIN_MODE_ACTIVE" = true ]; then
+                    log_dim "Route-main" "generated artifacts will be routed via PR"
+                fi
+                if [ "$VERBOSE" = true ]; then
+                    echo "$GENERATED_SYNC_ARTIFACTS" | while IFS= read -r generated_file; do
+                        [ -n "$generated_file" ] || continue
+                        log_dim "Generated file" "$generated_file"
+                    done
+                fi
+            fi
+
+            # Generate or use commit message
+            if [ -z "$COMMIT_MESSAGE" ]; then
+                # Auto-generate from staged changes
+                COMMIT_MESSAGE=$(generate_commit_message)
+
+                if [ "$VERBOSE" = true ]; then
+                    log_dim "Message" "$COMMIT_MESSAGE"
+                fi
+            fi
+
+            # Commit
+            if git commit -m "$COMMIT_MESSAGE" >/dev/null 2>&1; then
+                CREATED_COMMIT_SHA=$(git rev-parse HEAD)
+                CREATED_COMMIT_PARENT_SHA=$(git rev-parse "${CREATED_COMMIT_SHA}^")
+                log_ok "Commit" "$COMMIT_MESSAGE"
+            else
+                log_err "Commit" "failed"
+                HAS_FAILURE=true
+                exit 1
+            fi
+        else
+            echo ""
+            echo "Would stage and commit:"
+            git status --short
+            echo ""
+            if [ -n "$COMMIT_MESSAGE" ]; then
+                echo "Commit message: \"$COMMIT_MESSAGE\""
+            else
+                echo "Commit message: (auto-generated)"
+            fi
+        fi
+    fi
+fi
+
+# STEP 4: Merge from main (if not on main)
+if [ "$CURRENT_BRANCH" != "$MAIN_BRANCH" ] && [ "$DRY_RUN" = false ] && [ "$SKIP_COMMIT" = false ]; then
+    # Rebasing published commits onto a newer main rewrites them; the push is then
+    # rejected and recovery would replay them onto the old upstream. Skip instead.
+    SKIP_MAIN_REBASE=false
+    if [ "$REBASE" = true ] && git rev-parse -q --verify "@{u}" >/dev/null 2>&1 \
+        && ! git merge-base --is-ancestor "@{u}" "origin/$MAIN_BRANCH" 2>/dev/null \
+        && ! git merge-base --is-ancestor "origin/$MAIN_BRANCH" "@{u}" 2>/dev/null; then
+        SKIP_MAIN_REBASE=true
+        log_dim "Rebase" "onto $MAIN_BRANCH skipped (branch already pushed; use --merge to integrate)"
+    fi
+
+    # Use rebase or merge based on flag
+    if [ "$SKIP_MAIN_REBASE" = true ]; then
+        :
+    elif [ "$REBASE" = true ]; then
+        if git rebase --rebase-merges "origin/$MAIN_BRANCH" >/dev/null 2>&1; then
+            log_ok "Rebase" "onto $MAIN_BRANCH"
+        else
+            if git diff --quiet HEAD "origin/$MAIN_BRANCH"; then
+                git rebase --abort 2>/dev/null || true
+                log_dim "Rebase" "up-to-date with $MAIN_BRANCH"
+            else
+                log_err "Rebase" "conflict detected"
+                git rebase --abort 2>/dev/null || true
+                print_recovery_hint
+                echo "Conflicted files:"
+                git diff --name-only --diff-filter=U 2>/dev/null || echo "(run git status to see conflicts)"
+                echo ""
+                echo "To resolve manually:"
+                echo "  1. git rebase origin/$MAIN_BRANCH"
+                echo "  2. Edit conflicted files"
+                echo "  3. git add <resolved-files>"
+                echo "  4. git rebase --continue"
+                echo "  5. Run build sync again to push"
+                exit 1
+            fi
+        fi
+    else
+        if git merge "origin/$MAIN_BRANCH" --no-edit >/dev/null 2>&1; then
+            log_ok "Merge" "from $MAIN_BRANCH"
+        else
+            if git diff --quiet HEAD "origin/$MAIN_BRANCH"; then
+                log_dim "Merge" "up-to-date with $MAIN_BRANCH"
+            else
+                log_err "Merge" "conflict detected"
+                print_recovery_hint
+                echo "Conflicted files:"
+                git diff --name-only --diff-filter=U
+                echo ""
+                echo "To resolve manually:"
+                echo "  1. Edit conflicted files"
+                echo "  2. git add <resolved-files>"
+                echo "  3. git commit"
+                echo "  4. Run build sync again to push"
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+# STEP 5: Push to remote or create PR
+if [ "$DRY_RUN" = false ] && [ "$SKIP_COMMIT" = false ]; then
+
+    # Route-main: if enabled for a main/master commit, route via deterministic PR branch (no direct push to origin/main)
+    if [ "$ROUTE_MAIN_MODE_ACTIVE" = true ] || { [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ] && [ "$ROUTE_MAIN_EFFECTIVE" = true ]; }; then
+        if route_main_head_to_pr "$MAIN_BRANCH" "$STAY_ON_MAIN"; then
+            PUSH_SUCCESS=true
+            # Route-main already ensured the PR for the route branch, then checked
+            # back out to main. A standalone --ensure-pr (ENSURE_PR=true) would now
+            # re-trigger PR creation in Step 5b while on main and hard-fail with
+            # "cannot create from main". Route-main subsumes ensure-pr, so mark it
+            # satisfied here. (--route-main --ensure-pr must be a no-op overlap, not a trap.)
+            ENSURE_PR=false
+            # Best-effort cleanup: remove temporary WIP branch used to avoid committing on main.
+            if [ -n "${ROUTE_MAIN_WIP_BRANCH:-}" ]; then
+                git branch -D "$ROUTE_MAIN_WIP_BRANCH" >/dev/null 2>&1 || true
+                ROUTE_MAIN_WIP_BRANCH=""
+            fi
+        else
+            log_err "Route-main" "failed"
+            exit 1
+        fi
+    else
+        # If --pr is used on a non-main branch, treat it as an intent to ensure a PR for this branch
+        if [ "$CREATE_PR" = true ] && [ "$CURRENT_BRANCH" != "$MAIN_BRANCH" ]; then
+            ENSURE_PR=true
+        fi
+
+	    # Determine if we should create a PR
+	    SHOULD_CREATE_PR=false
+	    if [ "$CREATE_PR" = true ] && [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
+	        SHOULD_CREATE_PR=true
+	    fi
+
+	    if [ "$SHOULD_CREATE_PR" = true ]; then
+        if [ -z "$CREATED_COMMIT_SHA" ] || [ "$(git rev-parse HEAD)" != "$CREATED_COMMIT_SHA" ]; then
+            log_err "PR" "no sync-owned commit available to route"
+            exit 1
+        fi
+
+        # Generate branch name from commit message or timestamp
+        PR_BRANCH_NAME=""
+        if [ -n "$COMMIT_MESSAGE" ]; then
+            # Convert message to branch-safe name
+            PR_BRANCH_NAME="pr/$(echo "$COMMIT_MESSAGE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//' | cut -c1-50)"
+        else
+            PR_BRANCH_NAME="pr/changes-$(date +%Y%m%d-%H%M%S)"
+        fi
+
+        # Use only the commit created by this invocation. The original branch
+        # is restored with a compare-and-swap below so foreign ref updates can
+        # never be rewound by this cleanup.
+        COMMIT_SHA="$CREATED_COMMIT_SHA"
+
+        # Create and checkout PR branch from current position
+        if git checkout -b "$PR_BRANCH_NAME" >/dev/null 2>&1; then
+            log_ok "Branch" "$PR_BRANCH_NAME"
+        else
+            log_err "Branch" "creation failed"
+            exit 1
+        fi
+
+        # Remove our temporary commit from the original branch before the
+        # network/PR window. update-ref's old-value check makes this rollback
+        # fail closed if another process has already advanced the branch.
+        if git update-ref "refs/heads/$CURRENT_BRANCH" "$CREATED_COMMIT_PARENT_SHA" "$COMMIT_SHA"; then
+            log_dim "Reset" "$CURRENT_BRANCH (commit on PR branch)"
+        else
+            log_err "Reset" "$CURRENT_BRANCH changed concurrently; preserved $PR_BRANCH_NAME"
+            git checkout "$CURRENT_BRANCH" >/dev/null 2>&1 || true
+            exit 1
+        fi
+
+        # Push PR branch
+        if run_git_push -u origin "$PR_BRANCH_NAME"; then
+            log_ok "Push" "origin/$PR_BRANCH_NAME"
+        else
+            log_err "Push" "failed: $PR_BRANCH_NAME"
+            log_git_push_reason
+            git checkout "$CURRENT_BRANCH" >/dev/null 2>&1
+            log_dim "Recovery" "commit preserved on $PR_BRANCH_NAME"
+            exit 1
+        fi
+
+        # Create PR using gh cli
+        PR_TITLE="${COMMIT_MESSAGE:-$(git log -1 --pretty=%s 2>/dev/null || echo "Sync changes")}"
+        PR_BODY=$(build_sync_pr_body "pr" "$PR_BRANCH_NAME" "$CURRENT_BRANCH")
+
+	        if command -v gh >/dev/null 2>&1; then
+	            PR_URL=$(gh pr create --title "$PR_TITLE" --body "$PR_BODY" --base "$MAIN_BRANCH" 2>&1)
+	            if [ $? -eq 0 ]; then
+	                log_ok "PR" "$PR_URL"
+	                CREATED_PR_URL="$PR_URL"
+	                PUSH_SUCCESS=true
+
+	                echo ""
+	                log_dim "CI" "Quality Gate will run automatically"
+	                log_dim "Merge" "after review: build ci merge $(pr_number_from_url "$PR_URL") --sha $COMMIT_SHA"
+	            else
+	                log_warn "PR" "creation failed: $PR_URL"
+	                log_dim "PR" "branch pushed — create PR manually"
+                PUSH_SUCCESS=true
+            fi
+        else
+            log_warn "PR" "gh cli not found"
+            echo "  Branch: $PR_BRANCH_NAME"
+            echo "  URL: https://github.com/$(git remote get-url origin | sed 's/.*github.com[:/]//' | sed 's/.git$//')/pull/new/$PR_BRANCH_NAME"
+            PUSH_SUCCESS=true
+        fi
+
+        # Return to original branch
+        git checkout "$CURRENT_BRANCH" >/dev/null 2>&1
+
+	    else
+	        # Original direct push logic
+
+	        # Use cached UPSTREAM_EXISTS instead of rechecking
+	        if [ "$UPSTREAM_EXISTS" = false ]; then
+	            if ! should_publish_new_branch "$CURRENT_BRANCH"; then
+	                log_err "Push" "no upstream — refusing to publish"
+	                echo ""
+	                if is_wip_named_branch "$CURRENT_BRANCH"; then
+	                    echo "Note: '$CURRENT_BRANCH' looks like a local-only/WIP branch (local/*, wip/*, tmp/*, validation/*, etc.)"
+	                    echo ""
+	                fi
+	                echo "To publish and set upstream (force):"
+		                echo "  build sync --publish"
+	                echo ""
+	                echo "To enable auto-publish by default:"
+	                echo "  build config set --scope user sync.autoPublish true"
+	                echo ""
+	                echo "Or manually:"
+	                echo "  git push -u origin $CURRENT_BRANCH"
+	                exit 1
+	            fi
+
+	            if run_git_push -u origin "$CURRENT_BRANCH"; then
+	                log_ok "Push" "origin/$CURRENT_BRANCH (set upstream)"
+	                PUSH_SUCCESS=true
+	                UPSTREAM_EXISTS=true
+	                UPSTREAM_BRANCH="origin/$CURRENT_BRANCH"
+            else
+                log_err "Push" "failed (new branch)"
+                log_git_push_reason
+                PUSH_SUCCESS=false
+                HAS_FAILURE=true
+                exit 1
+            fi
+        else
+            # Try push, with automatic retry on rejection
+            if run_git_push; then
+                log_ok "Push" "$UPSTREAM_BRANCH"
+                PUSH_SUCCESS=true
+            else
+                log_warn "Push" "rejected — remote may have changed"
+                log_git_push_reason
+                log_dim "Push" "retrying after rebase..."
+
+                # Auto-recover: pull, rebase, retry push
+                if git pull --rebase=merges >/dev/null 2>&1; then
+                    log_ok "Rebase" "onto remote changes"
+
+                    if run_git_push; then
+                        log_ok "Push" "$UPSTREAM_BRANCH (after rebase)"
+                        PUSH_SUCCESS=true
+                    else
+                        log_err "Push" "still rejected after rebase"
+                        log_git_push_reason
+                        PUSH_SUCCESS=false
+                        HAS_FAILURE=true
+
+                        echo ""
+                        print_recovery_hint
+                        echo "Push failed even after rebase. Possible causes:"
+                        echo "  - Force push from another location"
+                        echo "  - Protected branch rules"
+                        echo "  - Permission issues"
+                        echo ""
+                        echo "To investigate:"
+                        echo "  1. git log --oneline -3  (see your commits)"
+                        echo "  2. git status             (see current state)"
+                        echo "  3. Check branch protection rules"
+                        exit 1
+                    fi
+                else
+                    log_err "Pull" "failed during recovery"
+                    PUSH_SUCCESS=false
+                    HAS_FAILURE=true
+
+                    print_recovery_hint
+                    echo "Recovery pull failed. Resolve manually:"
+                    echo "  1. git pull --rebase (resolve any conflicts)"
+                    echo "  2. git push"
+                    exit 1
+	        fi
+	    fi
+    fi
+fi
+fi
+fi
+
+# STEP 5b: PR status / ensure (show-only by default)
+if [ "$SYNC_ONLY" = false ]; then
+    # Avoid PR creation directly from main/master (use route-main instead)
+    if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
+        if [ "$ENSURE_PR" = true ]; then
+            log_err "PR" "cannot create from '$MAIN_BRANCH' — use --route-main"
+            exit 1
+        fi
+    else
+        EXISTING_PR_URL=$(get_open_pr_url_for_head "$CURRENT_BRANCH")
+        if [ -n "$EXISTING_PR_URL" ]; then
+            log_dim "PR" "$EXISTING_PR_URL"
+            CREATED_PR_URL="$EXISTING_PR_URL"
+        elif [ "$ENSURE_PR" = true ]; then
+            PR_TITLE="${COMMIT_MESSAGE:-$(git log -1 --pretty=%s 2>/dev/null || echo "$CURRENT_BRANCH")}"
+            if [ "$USER_DRY_RUN" = true ]; then
+                log_dim "PR" "dry run: would create a PR for '$CURRENT_BRANCH' into '$MAIN_BRANCH'"
+            else
+                PR_BODY=$(build_sync_pr_body "ensure-pr" "$CURRENT_BRANCH" "$MAIN_BRANCH")
+                ensure_pr_for_head "$CURRENT_BRANCH" "$MAIN_BRANCH" "$PR_TITLE" "$PR_BODY" || true
+            fi
+        fi
+    fi
+fi
+
+# STEP 6: Cross-Environment Status Report
+echo ""
+echo "  Branch Status"
+printf '  %0.s' $(seq 1 40); echo ""
+
+# === CACHE BRANCH STATUS (Fix 1: Eliminate duplicate git operations) ===
+# Scan all branches ONCE and cache the results
+# Note: Associative arrays require bash 4+
+# Temporarily disable unbound variable check for caching section
+set +u
+
+# Check bash version for associative array support
+BASH_MAJOR="${BASH_VERSION%%.*}"
+HAS_ASSOC_ARRAYS=false
+if [ "$BASH_MAJOR" -ge 4 ] 2>/dev/null; then
+    HAS_ASSOC_ARRAYS=true
+    declare -A BRANCH_AHEAD 2>/dev/null || HAS_ASSOC_ARRAYS=false
+    declare -A BRANCH_BEHIND 2>/dev/null || HAS_ASSOC_ARRAYS=false
+    declare -A BRANCH_HAS_UPSTREAM 2>/dev/null || HAS_ASSOC_ARRAYS=false
+fi
+
+# Cache current branch status (for bash 4+) or use simple variables (bash 3.2)
+if [ "$DETACHED_HEAD" = true ]; then
+    CURRENT_HAS_UPSTREAM=false
+    CURRENT_AHEAD=0
+    CURRENT_BEHIND=0
+elif git rev-parse --abbrev-ref --symbolic-full-name "@{u}" >/dev/null 2>&1; then
+    CURRENT_HAS_UPSTREAM=true
+    CURRENT_AHEAD=$(git rev-list --count "@{u}..HEAD" 2>/dev/null || echo "0")
+    CURRENT_BEHIND=$(git rev-list --count "HEAD..@{u}" 2>/dev/null || echo "0")
+    if [ "$HAS_ASSOC_ARRAYS" = true ]; then
+        BRANCH_HAS_UPSTREAM["$CURRENT_BRANCH"]=true
+        BRANCH_AHEAD["$CURRENT_BRANCH"]="$CURRENT_AHEAD"
+        BRANCH_BEHIND["$CURRENT_BRANCH"]="$CURRENT_BEHIND"
+    fi
+else
+    CURRENT_HAS_UPSTREAM=false
+    CURRENT_AHEAD=0
+    CURRENT_BEHIND=0
+    if [ "$HAS_ASSOC_ARRAYS" = true ]; then
+        BRANCH_HAS_UPSTREAM["$CURRENT_BRANCH"]=false
+        BRANCH_AHEAD["$CURRENT_BRANCH"]=0
+        BRANCH_BEHIND["$CURRENT_BRANCH"]=0
+    fi
+fi
+
+# Cache other branches status (only on bash 4+ and verbose mode)
+if [ "$HAS_ASSOC_ARRAYS" = true ] && [ "$VERBOSE" = true ] && [ -n "$TRACKED_BRANCHES" ]; then
+    while IFS= read -r line; do
+        branch=$(echo "$line" | awk '{print $1}')
+        upstream=$(echo "$line" | awk '{print $2}')
+
+        if [ "$branch" != "$CURRENT_BRANCH" ]; then
+            BRANCH_HAS_UPSTREAM["$branch"]=true
+            BRANCH_AHEAD["$branch"]=$(git rev-list --count "$upstream..$branch" 2>/dev/null || echo "0")
+            BRANCH_BEHIND["$branch"]=$(git rev-list --count "$branch..$upstream" 2>/dev/null || echo "0")
+        fi
+    done <<< "$TRACKED_BRANCHES"
+fi
+
+# === SUMMARY SECTION (using cached values) ===
+# Note: Keeping set +u active for array access throughout status reporting
+
+echo "  Summary"
+printf '  %0.s' $(seq 1 40); echo ""
+
+# Count synced vs warning branches using cached values
+SYNCED_COUNT=0
+WARNING_COUNT=0
+
+# Check current branch (use simple variables - works on all bash versions)
+if [ "$CURRENT_HAS_UPSTREAM" = true ]; then
+    if [ "$CURRENT_AHEAD" -eq 0 ] && [ "$CURRENT_BEHIND" -eq 0 ]; then
+        SYNCED_COUNT=$((SYNCED_COUNT + 1))
+    else
+        WARNING_COUNT=$((WARNING_COUNT + 1))
+        HAS_WARNINGS=true
+    fi
+fi
+
+# Check other branches using cached values (bash 4+ only, verbose only)
+if [ "$HAS_ASSOC_ARRAYS" = true ] && [ "$VERBOSE" = true ] && [ -n "$TRACKED_BRANCHES" ]; then
+    while IFS= read -r line; do
+        branch=$(echo "$line" | awk '{print $1}')
+
+        if [ "$branch" != "$CURRENT_BRANCH" ] && [ "${BRANCH_HAS_UPSTREAM["$branch"]}" = true ]; then
+            AHEAD="${BRANCH_AHEAD["$branch"]}"
+            BEHIND="${BRANCH_BEHIND["$branch"]}"
+
+            if [ "$AHEAD" -eq 0 ] && [ "$BEHIND" -eq 0 ]; then
+                SYNCED_COUNT=$((SYNCED_COUNT + 1))
+            else
+                WARNING_COUNT=$((WARNING_COUNT + 1))
+                HAS_WARNINGS=true
+            fi
+        fi
+    done <<< "$TRACKED_BRANCHES"
+fi
+
+# Display summary counts
+if [ "$SYNCED_COUNT" -gt 0 ]; then
+    log_ok "Synced" "$SYNCED_COUNT branch(es)"
+fi
+if [ "$WARNING_COUNT" -gt 0 ]; then
+    log_warn "Warnings" "$WARNING_COUNT branch(es)"
+fi
+
+echo ""
+echo "  Details"
+printf '  %0.s' $(seq 1 40); echo ""
+
+# Current branch status (use simple variables - works on all bash versions)
+if [ "$DETACHED_HEAD" = true ]; then
+    log_dim "detached HEAD" "$DETACHED_HEAD_SHA (no branch)"
+elif [ "$CURRENT_HAS_UPSTREAM" = true ]; then
+    if [ "$CURRENT_AHEAD" -eq 0 ] && [ "$CURRENT_BEHIND" -eq 0 ]; then
+        log_ok "$CURRENT_BRANCH" "synced"
+    elif [ "$CURRENT_AHEAD" -gt 0 ] && [ "$CURRENT_BEHIND" -eq 0 ]; then
+        log_warn "$CURRENT_BRANCH" "$CURRENT_AHEAD ahead (needs push)"
+    elif [ "$CURRENT_AHEAD" -eq 0 ] && [ "$CURRENT_BEHIND" -gt 0 ]; then
+        log_warn "$CURRENT_BRANCH" "$CURRENT_BEHIND behind (needs pull)"
+    else
+        log_warn "$CURRENT_BRANCH" "$CURRENT_AHEAD ahead, $CURRENT_BEHIND behind (diverged)"
+    fi
+else
+    log_dim "$CURRENT_BRANCH" "no upstream tracking"
+fi
+
+# Other tracked branches + untracked: only show in verbose mode (default: fast)
+if [ "$VERBOSE" = true ]; then
+    # Other tracked branches (using cached values - bash 4+ only)
+    if [ -n "$TRACKED_BRANCHES" ]; then
+        if [ "$HAS_ASSOC_ARRAYS" = true ]; then
+            echo "$TRACKED_BRANCHES" | while read -r branch upstream; do
+                if [ "$branch" != "$CURRENT_BRANCH" ]; then
+                    AHEAD="${BRANCH_AHEAD["$branch"]}"
+                    BEHIND="${BRANCH_BEHIND["$branch"]}"
+
+                    if [ "$AHEAD" -eq 0 ] && [ "$BEHIND" -eq 0 ]; then
+                        log_ok "$branch" "synced"
+                    elif [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -eq 0 ]; then
+                        log_warn "$branch" "$AHEAD ahead (needs push)"
+                    elif [ "$AHEAD" -eq 0 ] && [ "$BEHIND" -gt 0 ]; then
+                        log_warn "$branch" "$BEHIND behind (needs pull)"
+                    else
+                        log_warn "$branch" "+$AHEAD/-$BEHIND (diverged)"
+                    fi
+                fi
+            done
+        else
+            # Bash 3.2 fallback: fetch status inline (slower but works)
+            echo "$TRACKED_BRANCHES" | while read -r branch upstream; do
+                if [ "$branch" != "$CURRENT_BRANCH" ]; then
+                    AHEAD=$(git rev-list --count "$upstream..$branch" 2>/dev/null || echo "0")
+                    BEHIND=$(git rev-list --count "$branch..$upstream" 2>/dev/null || echo "0")
+
+                    if [ "$AHEAD" -eq 0 ] && [ "$BEHIND" -eq 0 ]; then
+                        log_ok "$branch" "synced"
+                    elif [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -eq 0 ]; then
+                        log_warn "$branch" "$AHEAD ahead (needs push)"
+                    elif [ "$AHEAD" -eq 0 ] && [ "$BEHIND" -gt 0 ]; then
+                        log_warn "$branch" "$BEHIND behind (needs pull)"
+                    else
+                        log_warn "$branch" "+$AHEAD/-$BEHIND (diverged)"
+                    fi
+                fi
+            done
+        fi
+    fi
+
+    # Untracked local branches (no per-branch subprocess; single git call)
+    UNTRACKED=$(git for-each-ref --format='%(if)%(upstream)%(then)%(else)%(refname:short)%(end)' refs/heads/ | grep -v '^$' || true)
+    if [ -n "$UNTRACKED" ]; then
+        echo ""
+        printf "  ${DIM}%-16s${NC}\n" "Untracked:"
+        echo "$UNTRACKED" | while read -r branch; do
+            log_dim "$branch" "local only"
+        done
+    fi
+fi  # end verbose branch/untracked detail
+
+# Remote-only branches + tip: verbose only
+if [ "$VERBOSE" = true ]; then
+    REMOTE_ONLY=$(git branch -r --format='%(refname:short)' | sed 's/origin\///' | grep -v "HEAD" | while read -r rbranch; do
+        if ! git show-ref --verify --quiet "refs/heads/$rbranch"; then
+            echo "$rbranch"
+        fi
+    done)
+    if [ -n "$REMOTE_ONLY" ]; then
+        echo ""
+        printf "  ${DIM}%-16s${NC}\n" "Remote-only:"
+        echo "$REMOTE_ONLY" | while read -r rbranch; do
+            log_dim "$rbranch" "not checked out locally"
+        done
+    fi
+fi
+
+# Restore strict unbound-variable checking (disabled at status cache section)
+set -u
+
+# === CLEANUP BACKUP BRANCH (only if created and successful) ===
+if [ "$DRY_RUN" = false ] && [ "$BACKUP_BRANCH_CREATED" = true ]; then
+    if [ "$PUSH_SUCCESS" = true ] || [ "$SYNC_MODE" = true ]; then
+        if git branch -D "$BACKUP_BRANCH" >/dev/null 2>&1; then
+            log_dim "Cleanup" "backup branch removed"
+        fi
+    fi
+fi
+
+# === PRUNE STALE BACKUP BRANCHES (orphaned by prior failed/interrupted runs) ===
+if [ "$DRY_RUN" = false ] && [ "$STATUS_ONLY" = false ] && [ "$PR_ONLY" = false ]; then
+    if [ "$PUSH_SUCCESS" = true ] || [ "$SYNC_MODE" = true ]; then
+        prune_stale_backup_branches || true
+    fi
+fi
+
+# === POST-SYNC HOOKS (project-local) ===
+if [ "$DRY_RUN" = false ] && [ "$STATUS_ONLY" = false ] && [ "$PR_ONLY" = false ]; then
+    run_post_sync_hooks
+fi
+
+# === AUTO-CHECKOUT MAIN (optional) ===
+maybe_checkout_main_after_sync() {
+    local checkout_default
+    checkout_default=$(get_sync_checkout_main_default)
+    if ! is_truthy "$checkout_default"; then
+        return 0
+    fi
+
+    # Only after a real sync run with a successful push or sync-mode pull.
+    if [ "$PUSH_SUCCESS" != true ] && [ "$SYNC_MODE" != true ]; then
+        return 0
+    fi
+
+    local branch
+    branch=$(git branch --show-current 2>/dev/null || echo "")
+    if [ "$branch" = "$MAIN_BRANCH" ]; then
+        return 0
+    fi
+
+    if has_tracked_changes; then
+        log_warn "Checkout" "skipped — working tree has changes"
+        return 0
+    fi
+
+    if git checkout "$MAIN_BRANCH" >/dev/null 2>&1; then
+        log_dim "Checkout" "$MAIN_BRANCH"
+        if [ -n "${CREATED_PR_URL:-}" ]; then
+            log_dim "Note" "changes on PR branch, not $MAIN_BRANCH"
+            log_dim "PR" "$CREATED_PR_URL"
+        fi
+    else
+        log_warn "Checkout" "failed: $MAIN_BRANCH"
+    fi
+}
+
+if [ "$DRY_RUN" = false ] && [ "$STATUS_ONLY" = false ]; then
+    maybe_checkout_main_after_sync
+fi
+
+# === CLEANUP MERGED ROUTE-MAIN BRANCHES ===
+# After successful sync, clean up local wip/route-main/* branches that have been merged.
+if [ "$DRY_RUN" = false ]; then
+    if [ "$PUSH_SUCCESS" = true ] || [ "$SYNC_MODE" = true ]; then
+        # Prefer origin's tree (more up-to-date after fetch), fall back to local
+        main_tree=$(git rev-parse "origin/$MAIN_BRANCH^{tree}" 2>/dev/null || git rev-parse "$MAIN_BRANCH^{tree}" 2>/dev/null || true)
+        if [ -n "$main_tree" ]; then
+            current_branch=$(git branch --show-current 2>/dev/null || true)
+            tmpfile=$(mktemp 2>/dev/null) || true
+            if [ -z "${tmpfile:-}" ]; then
+                log_warn "Cleanup" "mktemp failed, skipping"
+            else
+                trap 'rm -f "$tmpfile"' EXIT
+                git branch --list 'wip/route-main/*' 2>/dev/null | sed 's/^[* ]*//' | while IFS= read -r branch; do
+                    [ -z "$branch" ] && continue
+                    [ "$branch" = "$current_branch" ] && continue  # Can't delete current branch
+                    branch_tree=$(git rev-parse "$branch^{tree}" 2>/dev/null || true)
+                    if [ -n "$branch_tree" ] && [ "$main_tree" = "$branch_tree" ]; then
+                        if delete_local_route_branch "$branch"; then
+                            echo "$branch" >> "$tmpfile"
+                        fi
+                    fi
+                done
+                if [ -s "$tmpfile" ]; then
+                    cleaned_count=$(wc -l < "$tmpfile" | tr -d ' ')
+                    log_dim "Cleanup" "$cleaned_count route-main branch(es) removed"
+                fi
+            fi
+        fi
+    fi
+fi
+
+# === ORPHANED AUTO-STASH CHECK ===
+# If this run stashed changes, verify the stash was actually consumed.
+# Safety net: catches any path that leaves this run's auto-stash unconsumed.
+if [ "$DRY_RUN" = false ] && [ "${STASHED:-false}" = true ]; then
+    stash_ref=$(own_stash_ref || true)
+    if [ -n "$stash_ref" ]; then
+        log_err "Stash" "orphaned auto-stash detected: $stash_ref"
+        echo "  Your uncommitted changes were stashed but could not be restored."
+        echo "  Inspect:  git stash show -p $stash_ref"
+        echo "  Restore:  git stash pop $stash_ref"
+        echo "  Discard:  git stash drop $stash_ref"
+        HAS_WARNINGS=true
+    fi
+fi
+
+# === COMPLETION ===
+echo ""
+if [ "$DRY_RUN" = true ]; then
+    log_dim "Done" "dry run complete — no changes made"
+elif [ "$SYNC_MODE" = true ]; then
+    if [ "$HAS_WARNINGS" = true ]; then
+        log_warn "Done" "synced (warnings above)"
+    else
+        log_ok "Done" "synced"
+    fi
+else
+    if [ "$PUSH_SUCCESS" = true ]; then
+        if [ "$HAS_WARNINGS" = true ]; then
+            log_warn "Done" "committed and pushed (warnings above)"
+        else
+            log_ok "Done" "committed and pushed"
+        fi
+    else
+        log_warn "Done" "partial success (see above)"
+    fi
+fi
+echo ""
+
+# Explicit exit code: 0 when journey completed; 1 only on failure (warnings do not fail)
+if [ "$HAS_FAILURE" = true ]; then
+    exit 1
+else
+    exit 0
+fi