@imdeadpool/guardex 7.0.41 → 7.0.43

package/templates/scripts/agent-branch-finish.sh

@@ -11,11 +11,22 @@ MERGE_MODE="auto"
 GH_BIN="${GUARDEX_GH_BIN:-gh}"
 NODE_BIN="${GUARDEX_NODE_BIN:-node}"
 CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
-CLEANUP_AFTER_MERGE_RAW="${GUARDEX_FINISH_CLEANUP:-false}"
-WAIT_FOR_MERGE_RAW="${GUARDEX_FINISH_WAIT_FOR_MERGE:-false}"
+CLEANUP_AFTER_MERGE_RAW="${GUARDEX_FINISH_CLEANUP:-true}"
+WAIT_FOR_MERGE_RAW="${GUARDEX_FINISH_WAIT_FOR_MERGE:-true}"
 WAIT_TIMEOUT_SECONDS_RAW="${GUARDEX_FINISH_WAIT_TIMEOUT_SECONDS:-1800}"
 WAIT_POLL_SECONDS_RAW="${GUARDEX_FINISH_WAIT_POLL_SECONDS:-10}"
 PARENT_GITLINK_AUTO_COMMIT_RAW="${GUARDEX_FINISH_PARENT_GITLINK_AUTO_COMMIT:-true}"
+AUTO_RESOLVE_MODE_RAW="${GUARDEX_FINISH_AUTO_RESOLVE:-none}"
+AUTO_RESOLVE_SAFE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+AUTO_RESOLVE_SAFE_GLOBS_RAW="${GUARDEX_FINISH_AUTO_RESOLVE_SAFE_GLOBS-$AUTO_RESOLVE_SAFE_GLOBS_DEFAULT}"
+PREFLIGHT_ENABLED_RAW="${GUARDEX_FINISH_PREFLIGHT:-true}"
+PREFLIGHT_SCRIPT_RAW="${GUARDEX_FINISH_PREFLIGHT_SCRIPT:-scripts/agent-preflight.sh}"
+AUTO_PROMOTE_DRAFT_RAW="${GUARDEX_FINISH_AUTO_PROMOTE:-true}"
+# --skip-checks (or GUARDEX_FINISH_SKIP_CHECKS=1): append `--admin` to every
+# `gh pr merge` invocation, bypassing required status checks. Requires admin
+# permission on the target repo. Use when CI is wedged (e.g. runner billing,
+# infrastructure outage) and the operator has accepted the risk.
+SKIP_CHECKS_RAW="${GUARDEX_FINISH_SKIP_CHECKS:-false}"
 
 run_guardex_cli() {
   if [[ -n "$CLI_ENTRY" ]]; then
@@ -64,11 +75,84 @@ normalize_int() {
   printf '%s' "$value"
 }
 
-CLEANUP_AFTER_MERGE="$(normalize_bool "$CLEANUP_AFTER_MERGE_RAW" "0")"
-WAIT_FOR_MERGE="$(normalize_bool "$WAIT_FOR_MERGE_RAW" "0")"
+# Resolve the pre-flight script path against the source worktree. The
+# caller passes either the configured path (which may be relative) or
+# an empty string; we return the absolute path if it exists and is
+# executable, otherwise return empty.
+resolve_preflight_script() {
+  local worktree="$1"
+  local configured="$2"
+  if [[ -z "$configured" ]]; then
+    configured="scripts/agent-preflight.sh"
+  fi
+  if [[ "$configured" = /* ]]; then
+    if [[ -x "$configured" ]]; then
+      printf '%s' "$configured"
+    fi
+    return 0
+  fi
+  local candidate="${worktree}/${configured}"
+  if [[ -x "$candidate" ]]; then
+    printf '%s' "$candidate"
+  fi
+}
+
+# Run the pre-flight verification gate in the agent worktree before
+# any push happens. Returns 0 on success or when no gate is
+# configured; returns non-zero (and prints a hint) on failure, which
+# the caller propagates so the push is refused.
+run_preflight() {
+  local worktree="$1"
+  if [[ "$PREFLIGHT_ENABLED" -ne 1 ]]; then
+    return 0
+  fi
+  local script_path
+  script_path="$(resolve_preflight_script "$worktree" "$PREFLIGHT_SCRIPT_RAW")"
+  if [[ -z "$script_path" ]]; then
+    echo "[agent-branch-finish] No executable pre-flight script at ${PREFLIGHT_SCRIPT_RAW} (in ${worktree}); skipping pre-flight." >&2
+    return 0
+  fi
+  echo "[agent-branch-finish] Running pre-flight: ${script_path}" >&2
+  if ( cd "$worktree" && "$script_path" ); then
+    echo "[agent-branch-finish] Pre-flight passed." >&2
+    return 0
+  fi
+  echo "[agent-branch-finish] Pre-flight FAILED; refusing push. Override with --no-preflight if you really mean it." >&2
+  return 1
+}
+
+# After a PR exists, if it is in draft and auto-promote is enabled,
+# mark it ready-for-review. With the budget-friendly CI defaults
+# (draft PRs skip CI), this is the moment when CI is allowed to fire.
+maybe_auto_promote_pr() {
+  local pr_url="$1"
+  if [[ -z "$pr_url" ]] || [[ "$AUTO_PROMOTE_DRAFT" -ne 1 ]]; then
+    return 0
+  fi
+  if ! command -v "$GH_BIN" >/dev/null 2>&1; then
+    return 0
+  fi
+  local is_draft
+  is_draft="$("$GH_BIN" pr view "$pr_url" --json isDraft --jq '.isDraft' 2>/dev/null || true)"
+  if [[ "$is_draft" != "true" ]]; then
+    return 0
+  fi
+  echo "[agent-branch-finish] PR is draft; promoting to ready-for-review (pre-flight passed)." >&2
+  if "$GH_BIN" pr ready "$pr_url" >/dev/null 2>&1; then
+    echo "[agent-branch-finish] PR marked ready-for-review." >&2
+  else
+    echo "[agent-branch-finish] gh pr ready failed; PR left in draft. Promote manually if intended." >&2
+  fi
+}
+
+CLEANUP_AFTER_MERGE="$(normalize_bool "$CLEANUP_AFTER_MERGE_RAW" "1")"
+WAIT_FOR_MERGE="$(normalize_bool "$WAIT_FOR_MERGE_RAW" "1")"
 WAIT_TIMEOUT_SECONDS="$(normalize_int "$WAIT_TIMEOUT_SECONDS_RAW" "1800" "30")"
 WAIT_POLL_SECONDS="$(normalize_int "$WAIT_POLL_SECONDS_RAW" "10" "0")"
 PARENT_GITLINK_AUTO_COMMIT="$(normalize_bool "$PARENT_GITLINK_AUTO_COMMIT_RAW" "1")"
+PREFLIGHT_ENABLED="$(normalize_bool "$PREFLIGHT_ENABLED_RAW" "1")"
+AUTO_PROMOTE_DRAFT="$(normalize_bool "$AUTO_PROMOTE_DRAFT_RAW" "1")"
+SKIP_CHECKS="$(normalize_bool "$SKIP_CHECKS_RAW" "0")"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -139,9 +223,54 @@ while [[ $# -gt 0 ]]; do
       MERGE_MODE="direct"
       shift
       ;;
+    --auto-resolve)
+      if [[ "${2:-}" =~ ^(none|safe|full)$ ]]; then
+        AUTO_RESOLVE_MODE_RAW="$2"
+        shift 2
+      else
+        AUTO_RESOLVE_MODE_RAW="safe"
+        shift
+      fi
+      ;;
+    --auto-resolve=*)
+      AUTO_RESOLVE_MODE_RAW="${1#--auto-resolve=}"
+      shift
+      ;;
+    --no-auto-resolve)
+      AUTO_RESOLVE_MODE_RAW="none"
+      shift
+      ;;
+    --no-preflight)
+      PREFLIGHT_ENABLED_RAW="false"
+      shift
+      ;;
+    --preflight)
+      PREFLIGHT_ENABLED_RAW="true"
+      shift
+      ;;
+    --preflight-script)
+      PREFLIGHT_SCRIPT_RAW="${2:-}"
+      shift 2
+      ;;
+    --skip-checks)
+      SKIP_CHECKS=1
+      shift
+      ;;
+    --no-skip-checks)
+      SKIP_CHECKS=0
+      shift
+      ;;
+    --no-auto-promote)
+      AUTO_PROMOTE_DRAFT_RAW="false"
+      shift
+      ;;
+    --auto-promote)
+      AUTO_PROMOTE_DRAFT_RAW="true"
+      shift
+      ;;
     *)
       echo "[agent-branch-finish] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--cleanup|--no-cleanup] [--wait-for-merge|--no-wait-for-merge] [--wait-timeout-seconds <n>] [--wait-poll-seconds <n>] [--parent-gitlink-commit|--no-parent-gitlink-commit] [--keep-remote-branch|--delete-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only]" >&2
+      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--cleanup|--no-cleanup] [--wait-for-merge|--no-wait-for-merge] [--wait-timeout-seconds <n>] [--wait-poll-seconds <n>] [--parent-gitlink-commit|--no-parent-gitlink-commit] [--keep-remote-branch|--delete-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only] [--auto-resolve[=none|safe|full]|--no-auto-resolve] [--no-preflight|--preflight] [--preflight-script <path>] [--no-auto-promote|--auto-promote]" >&2
       exit 1
       ;;
   esac
@@ -159,12 +288,162 @@ case "$MERGE_MODE" in
     ;;
 esac
 
+AUTO_RESOLVE_MODE="$(printf '%s' "$AUTO_RESOLVE_MODE_RAW" | tr '[:upper:]' '[:lower:]')"
+case "$AUTO_RESOLVE_MODE" in
+  none|safe|full) ;;
+  *)
+    echo "[agent-branch-finish] Invalid --auto-resolve value: ${AUTO_RESOLVE_MODE_RAW} (expected none|safe|full)" >&2
+    exit 1
+    ;;
+esac
+
+path_matches_auto_resolve_safe_glob() {
+  local path="$1"
+  if [[ -z "${AUTO_RESOLVE_SAFE_GLOBS_RAW:-}" ]]; then
+    return 1
+  fi
+  local -a globs=()
+  IFS=':' read -ra globs <<< "$AUTO_RESOLVE_SAFE_GLOBS_RAW"
+  local pattern rewritten
+  for pattern in "${globs[@]}"; do
+    [[ -z "$pattern" ]] && continue
+    rewritten="${pattern%/**}"
+    if [[ "$rewritten" != "$pattern" ]]; then
+      if [[ "$path" == "$rewritten"/* ]]; then
+        return 0
+      fi
+    else
+      # shellcheck disable=SC2053
+      if [[ "$path" == $pattern ]]; then
+        return 0
+      fi
+    fi
+  done
+  return 1
+}
+
+# Resolve a conflicting submodule pointer if and only if one side is a strict
+# ancestor of the other (fast-forward direction). Writes the resolved SHA via
+# git update-index and prints the chosen SHA on stdout. Returns 0 on success,
+# 1 on uninitialized/divergent/unreachable cases.
+try_resolve_submodule_pointer_conflict() {
+  local repo_root_arg="$1"
+  local source_worktree_arg="$2"
+  local conflict_path="$3"
+
+  # Confirm registered submodule path.
+  if [[ ! -f "$repo_root_arg/.gitmodules" ]]; then
+    return 1
+  fi
+  if ! git -C "$repo_root_arg" config -f .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null \
+       | awk '{print $2}' | grep -Fxq -- "$conflict_path"; then
+    return 1
+  fi
+
+  # Read the three stages from the index.
+  local stage_out
+  stage_out="$(git -C "$source_worktree_arg" ls-files -u -- "$conflict_path" 2>/dev/null || true)"
+  if [[ -z "$stage_out" ]]; then
+    return 1
+  fi
+
+  local base_sha="" ours_sha="" theirs_sha=""
+  local mode_field stage_sha stage_num path_field
+  while IFS=$'\t' read -r meta path_field; do
+    [[ -z "$meta" || -z "$path_field" ]] && continue
+    # meta format: "<mode> <sha> <stage>"
+    read -r mode_field stage_sha stage_num <<< "$meta"
+    [[ "$mode_field" != "160000" ]] && return 1
+    case "$stage_num" in
+      1) base_sha="$stage_sha" ;;
+      2) ours_sha="$stage_sha" ;;
+      3) theirs_sha="$stage_sha" ;;
+    esac
+  done <<< "$stage_out"
+
+  if [[ -z "$ours_sha" || -z "$theirs_sha" ]]; then
+    return 1
+  fi
+
+  # Pick a working clone for the submodule. Three sources, in order:
+  #   1) checked-out submodule worktree (cheap, no network)
+  #   2) cached internal clone at .git/modules/<name>
+  #   3) temp bare clone from the submodule URL (last resort; needs network)
+  local sub_query_dir=""
+  local sub_dir="$source_worktree_arg/$conflict_path"
+  if [[ -d "$sub_dir" ]] && git -C "$sub_dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    sub_query_dir="$sub_dir"
+  else
+    local repo_git_dir
+    repo_git_dir="$(git -C "$source_worktree_arg" rev-parse --git-common-dir 2>/dev/null || true)"
+    if [[ -n "$repo_git_dir" && -d "$repo_git_dir/modules/$conflict_path" ]]; then
+      sub_query_dir="$repo_git_dir/modules/$conflict_path"
+    fi
+  fi
+
+  local temp_sub_clone=""
+  cleanup_temp_sub_clone() {
+    [[ -n "$temp_sub_clone" && -d "$temp_sub_clone" ]] && rm -rf "$temp_sub_clone"
+  }
+  trap cleanup_temp_sub_clone RETURN
+
+  if [[ -z "$sub_query_dir" ]]; then
+    local sub_url
+    sub_url="$(git -C "$repo_root_arg" config -f .gitmodules --get "submodule.${conflict_path}.url" 2>/dev/null || true)"
+    if [[ -z "$sub_url" ]]; then
+      return 1
+    fi
+    temp_sub_clone="$(mktemp -d -t gx-submod-resolve-XXXXXX 2>/dev/null || true)"
+    if [[ -z "$temp_sub_clone" || ! -d "$temp_sub_clone" ]]; then
+      return 1
+    fi
+    if ! git clone --quiet --bare "$sub_url" "$temp_sub_clone" >/dev/null 2>&1; then
+      return 1
+    fi
+    sub_query_dir="$temp_sub_clone"
+  fi
+
+  if ! git -C "$sub_query_dir" cat-file -e "${ours_sha}^{commit}" 2>/dev/null \
+     || ! git -C "$sub_query_dir" cat-file -e "${theirs_sha}^{commit}" 2>/dev/null; then
+    git -C "$sub_query_dir" fetch --quiet --all 2>/dev/null || true
+  fi
+  if ! git -C "$sub_query_dir" cat-file -e "${ours_sha}^{commit}" 2>/dev/null \
+     || ! git -C "$sub_query_dir" cat-file -e "${theirs_sha}^{commit}" 2>/dev/null; then
+    return 1
+  fi
+
+  local chosen_sha=""
+  if [[ "$ours_sha" == "$theirs_sha" ]]; then
+    chosen_sha="$ours_sha"
+  elif git -C "$sub_query_dir" merge-base --is-ancestor "$ours_sha" "$theirs_sha" 2>/dev/null; then
+    chosen_sha="$theirs_sha"
+  elif git -C "$sub_query_dir" merge-base --is-ancestor "$theirs_sha" "$ours_sha" 2>/dev/null; then
+    chosen_sha="$ours_sha"
+  else
+    # Divergent histories; refuse.
+    return 1
+  fi
+
+  if ! git -C "$source_worktree_arg" update-index --cacheinfo "160000,${chosen_sha},${conflict_path}" >/dev/null 2>&1; then
+    return 1
+  fi
+
+  printf '%s' "$chosen_sha"
+  return 0
+}
+
 if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   echo "[agent-branch-finish] Not inside a git repository." >&2
   exit 1
 fi
 
 repo_root="$(git rev-parse --show-toplevel)"
+finish_active_cwd="${GUARDEX_FINISH_ACTIVE_CWD:-$(pwd -P)}"
+if [[ -d "$finish_active_cwd" ]]; then
+  finish_active_cwd="$(cd "$finish_active_cwd" && pwd -P)"
+else
+  finish_active_cwd=""
+fi
 # The physical cwd may be a subdirectory inside the source worktree. Cleanup
 # decisions need the enclosing worktree root, otherwise finishing from `src/`
 # can delete the caller's cwd and turn a successful merge into a false shell
@@ -178,6 +457,36 @@ else
 fi
 repo_common_root="$(cd "$common_git_dir/.." && pwd -P)"
 
+resolve_same_repo_worktree_for_cwd() {
+  local active_cwd="$1"
+  [[ -n "$active_cwd" && -d "$active_cwd" ]] || return 0
+  git -C "$active_cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+
+  local active_worktree=""
+  active_worktree="$(git -C "$active_cwd" rev-parse --show-toplevel 2>/dev/null || true)"
+  [[ -n "$active_worktree" ]] || return 0
+
+  local active_common_raw=""
+  local active_common_dir=""
+  active_common_raw="$(git -C "$active_worktree" rev-parse --git-common-dir 2>/dev/null || true)"
+  [[ -n "$active_common_raw" ]] || return 0
+  if [[ "$active_common_raw" == /* ]]; then
+    active_common_dir="$active_common_raw"
+  else
+    active_common_dir="${active_worktree}/${active_common_raw}"
+  fi
+  active_common_dir="$(cd "$active_common_dir" 2>/dev/null && pwd -P)" || return 0
+
+  if [[ "$active_common_dir" == "$common_git_dir" ]]; then
+    cd "$active_worktree" 2>/dev/null && pwd -P
+  fi
+}
+
+active_cwd_worktree="$(resolve_same_repo_worktree_for_cwd "$finish_active_cwd")"
+if [[ -n "$active_cwd_worktree" ]]; then
+  current_worktree="$active_cwd_worktree"
+fi
+
 if [[ -z "$SOURCE_BRANCH" ]]; then
   SOURCE_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
 fi
@@ -336,6 +645,22 @@ is_clean_worktree() {
     && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json"
 }
 
+refresh_clean_base_worktree() {
+  local wt="$1"
+  [[ -z "$wt" || "$PUSH_ENABLED" -ne 1 ]] && return 0
+
+  if ! is_clean_worktree "$wt"; then
+    echo "[agent-branch-finish] Warning: local ${BASE_BRANCH} worktree is dirty; skipping 'git pull --ff-only origin ${BASE_BRANCH}' for ${wt}." >&2
+    return 0
+  fi
+
+  if GUARDEX_DISABLE_POST_MERGE_CLEANUP=1 GUARDEX_PRUNE_ACTIVE_CWD="$finish_active_cwd" git -C "$wt" pull --ff-only origin "$BASE_BRANCH" >/dev/null; then
+    echo "[agent-branch-finish] Refreshed local ${BASE_BRANCH} worktree with 'git pull --ff-only origin ${BASE_BRANCH}': ${wt}"
+  else
+    echo "[agent-branch-finish] Warning: failed to refresh local ${BASE_BRANCH} worktree with 'git pull --ff-only origin ${BASE_BRANCH}': ${wt}" >&2
+  fi
+}
+
 remove_stale_source_probe_worktrees "$SOURCE_BRANCH"
 source_worktree="$(get_worktree_for_branch "$SOURCE_BRANCH")"
 created_source_probe=0
@@ -346,6 +671,7 @@ merge_completed=0
 merge_status="pr"
 direct_push_error=""
 pr_url=""
+changed_submodule_push_done=0
 
 cleanup() {
   if [[ -n "$integration_worktree" && -d "$integration_worktree" ]]; then
@@ -432,20 +758,97 @@ if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRA
 
   if ! git -C "$source_worktree" merge --no-commit --no-ff "origin/${BASE_BRANCH}" >/dev/null 2>&1; then
     conflict_files="$(git -C "$source_worktree" diff --name-only --diff-filter=U || true)"
-    git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
 
-    echo "[agent-branch-finish] Preflight conflict detected between '${SOURCE_BRANCH}' and latest origin/${BASE_BRANCH}." >&2
-    if [[ -n "$conflict_files" ]]; then
-      echo "[agent-branch-finish] Conflicting files:" >&2
-      while IFS= read -r file; do
-        [[ -n "$file" ]] && echo "  - ${file}" >&2
+    if [[ "$AUTO_RESOLVE_MODE" != "none" && -n "$conflict_files" ]]; then
+      auto_resolve_unresolved=""
+      auto_resolve_resolved_state=""
+      auto_resolve_resolved_submodules=""
+      while IFS= read -r conflict_path; do
+        [[ -z "$conflict_path" ]] && continue
+        if path_matches_auto_resolve_safe_glob "$conflict_path"; then
+          if git -C "$source_worktree" checkout --theirs -- "$conflict_path" >/dev/null 2>&1 \
+            && git -C "$source_worktree" add -- "$conflict_path" >/dev/null 2>&1; then
+            auto_resolve_resolved_state+="${conflict_path}"$'\n'
+            continue
+          fi
+        fi
+        if [[ "$AUTO_RESOLVE_MODE" == "full" ]]; then
+          if chosen_sha="$(try_resolve_submodule_pointer_conflict "$repo_root" "$source_worktree" "$conflict_path")"; then
+            auto_resolve_resolved_submodules+="${conflict_path}@${chosen_sha}"$'\n'
+            continue
+          fi
+        fi
+        auto_resolve_unresolved+="${conflict_path}"$'\n'
       done <<< "$conflict_files"
+
+      if [[ -n "$auto_resolve_unresolved" ]]; then
+        git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
+        echo "[agent-branch-finish] --auto-resolve=${AUTO_RESOLVE_MODE}: some conflicts are outside the safe allowlist (or submodule histories diverge); aborting." >&2
+        echo "[agent-branch-finish] Unresolved conflicts:" >&2
+        while IFS= read -r unresolved_path; do
+          [[ -n "$unresolved_path" ]] && echo "  - ${unresolved_path}" >&2
+        done <<< "$auto_resolve_unresolved"
+        echo "[agent-branch-finish] State-file allowlist (GUARDEX_FINISH_AUTO_RESOLVE_SAFE_GLOBS): ${AUTO_RESOLVE_SAFE_GLOBS_RAW}" >&2
+        if [[ "$AUTO_RESOLVE_MODE" != "full" ]]; then
+          echo "[agent-branch-finish] Submodule pointer auto-resolve requires --auto-resolve=full; not enabled for this run." >&2
+        fi
+        exit 1
+      fi
+
+      # Claim resolved paths so the pre-commit lock guard accepts the merge.
+      auto_resolve_claim_paths=()
+      while IFS= read -r resolved_path; do
+        [[ -n "$resolved_path" ]] && auto_resolve_claim_paths+=("$resolved_path")
+      done <<< "$auto_resolve_resolved_state"
+      while IFS= read -r resolved_entry; do
+        [[ -z "$resolved_entry" ]] && continue
+        auto_resolve_claim_paths+=("${resolved_entry%@*}")
+      done <<< "$auto_resolve_resolved_submodules"
+      if [[ "${#auto_resolve_claim_paths[@]}" -gt 0 ]]; then
+        run_guardex_cli locks claim --branch "$SOURCE_BRANCH" "${auto_resolve_claim_paths[@]}" >/dev/null 2>&1 || true
+      fi
+
+      auto_resolve_commit_msg="Merge origin/${BASE_BRANCH} into ${SOURCE_BRANCH} (gx --auto-resolve=${AUTO_RESOLVE_MODE}; state files -> base, submodule pointers fast-forwarded)"
+      if ! git -C "$source_worktree" commit -m "$auto_resolve_commit_msg" >/dev/null 2>&1; then
+        git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
+        echo "[agent-branch-finish] --auto-resolve=${AUTO_RESOLVE_MODE}: failed to commit resolved merge (pre-commit hook may have rejected it; verify file locks)." >&2
+        exit 1
+      fi
+
+      state_count=0
+      submod_count=0
+      [[ -n "$auto_resolve_resolved_state" ]] && state_count="$(printf '%s' "$auto_resolve_resolved_state" | grep -c '^[^[:space:]]')"
+      [[ -n "$auto_resolve_resolved_submodules" ]] && submod_count="$(printf '%s' "$auto_resolve_resolved_submodules" | grep -c '^[^[:space:]]')"
+      echo "[agent-branch-finish] --auto-resolve=${AUTO_RESOLVE_MODE}: resolved ${state_count} state-file conflict(s), ${submod_count} submodule pointer conflict(s)." >&2
+      if [[ -n "$auto_resolve_resolved_state" ]]; then
+        echo "[agent-branch-finish] State files (resolved to base):" >&2
+        while IFS= read -r resolved_path; do
+          [[ -n "$resolved_path" ]] && echo "  - ${resolved_path}" >&2
+        done <<< "$auto_resolve_resolved_state"
+      fi
+      if [[ -n "$auto_resolve_resolved_submodules" ]]; then
+        echo "[agent-branch-finish] Submodule pointers (fast-forwarded):" >&2
+        while IFS= read -r resolved_entry; do
+          [[ -n "$resolved_entry" ]] && echo "  - ${resolved_entry%@*} -> ${resolved_entry##*@}" >&2
+        done <<< "$auto_resolve_resolved_submodules"
+      fi
+    else
+      git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
+
+      echo "[agent-branch-finish] Preflight conflict detected between '${SOURCE_BRANCH}' and latest origin/${BASE_BRANCH}." >&2
+      if [[ -n "$conflict_files" ]]; then
+        echo "[agent-branch-finish] Conflicting files:" >&2
+        while IFS= read -r file; do
+          [[ -n "$file" ]] && echo "  - ${file}" >&2
+        done <<< "$conflict_files"
+      fi
+      echo "[agent-branch-finish] Rebase/merge '${BASE_BRANCH}' into '${SOURCE_BRANCH}' and resolve conflicts before finishing." >&2
+      echo "[agent-branch-finish] Or rerun with --auto-resolve=safe (state files) or --auto-resolve=full (state files + fast-forward-able submodule pointers)." >&2
+      exit 1
     fi
-    echo "[agent-branch-finish] Rebase/merge '${BASE_BRANCH}' into '${SOURCE_BRANCH}' and resolve conflicts before finishing." >&2
-    exit 1
+  else
+    git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
   fi
-
-  git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
 fi
 
 should_create_integration_helper=1
@@ -682,14 +1085,89 @@ maybe_auto_commit_parent_gitlink() {
   echo "[agent-branch-finish] Parent gitlink auto-committed '${subrepo_rel}' in ${super_root}."
 }
 
+maybe_push_changed_submodule_branches() {
+  local base_ref="${1:-}"
+  local source_ref="${2:-}"
+  local changed_path=""
+  local gitlink_mode=""
+  local gitlink_sha=""
+  local submodule_dir=""
+  local branch_name=""
+  local candidate_branch=""
+  local remote_name=""
+  local push_output=""
+
+  if [[ "$PUSH_ENABLED" -ne 1 || "$changed_submodule_push_done" -eq 1 ]]; then
+    return 0
+  fi
+  changed_submodule_push_done=1
+  if [[ -z "$base_ref" || -z "$source_ref" ]]; then
+    return 0
+  fi
+
+  while IFS= read -r changed_path; do
+    [[ -n "$changed_path" ]] || continue
+
+    gitlink_mode="$(git -C "$source_worktree" ls-tree "$source_ref" -- "$changed_path" | awk 'NR == 1 { print $1 }')"
+    if [[ "$gitlink_mode" != "160000" ]]; then
+      continue
+    fi
+    gitlink_sha="$(git -C "$source_worktree" ls-tree "$source_ref" -- "$changed_path" | awk 'NR == 1 { print $3 }')"
+    if [[ -z "$gitlink_sha" ]]; then
+      continue
+    fi
+
+    submodule_dir="${source_worktree}/${changed_path}"
+    if ! git -C "$submodule_dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      echo "[agent-branch-finish] Warning: changed gitlink '${changed_path}' has no checked-out submodule at ${submodule_dir}; cannot auto-push submodule commit ${gitlink_sha}." >&2
+      return 1
+    fi
+    if ! git -C "$submodule_dir" cat-file -e "${gitlink_sha}^{commit}" >/dev/null 2>&1; then
+      echo "[agent-branch-finish] Warning: changed gitlink '${changed_path}' points at ${gitlink_sha}, but that commit is not present in ${submodule_dir}; cannot auto-push it." >&2
+      return 1
+    fi
+
+    branch_name="$(git -C "$submodule_dir" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+    if [[ -z "$branch_name" || "$branch_name" == "HEAD" ]] || ! git -C "$submodule_dir" merge-base --is-ancestor "$gitlink_sha" "$branch_name" >/dev/null 2>&1; then
+      candidate_branch="$(git -C "$submodule_dir" for-each-ref --contains "$gitlink_sha" --format='%(refname:short)' refs/heads | head -n 1)"
+      branch_name="$candidate_branch"
+    fi
+    if [[ -z "$branch_name" || "$branch_name" == "HEAD" ]]; then
+      echo "[agent-branch-finish] Warning: changed gitlink '${changed_path}' points at ${gitlink_sha}, but no local submodule branch contains it; cannot choose a safe remote branch to push." >&2
+      return 1
+    fi
+
+    remote_name="$(git -C "$submodule_dir" config --get "branch.${branch_name}.remote" || true)"
+    if [[ -z "$remote_name" ]]; then
+      remote_name="origin"
+    fi
+    if ! git -C "$submodule_dir" remote get-url "$remote_name" >/dev/null 2>&1; then
+      echo "[agent-branch-finish] Warning: changed gitlink '${changed_path}' branch '${branch_name}' has no usable remote '${remote_name}'; cannot auto-push submodule commit ${gitlink_sha}." >&2
+      return 1
+    fi
+
+    if push_output="$(git -C "$submodule_dir" push -u "$remote_name" "${branch_name}:${branch_name}" 2>&1)"; then
+      echo "[agent-branch-finish] Pushed changed submodule '${changed_path}' branch '${branch_name}' to '${remote_name}' before parent finish."
+    else
+      echo "[agent-branch-finish] Changed submodule '${changed_path}' must be pushed before the parent branch can be finished." >&2
+      [[ -n "$push_output" ]] && echo "$push_output" >&2
+      return 1
+    fi
+  done < <(git -C "$source_worktree" diff --name-only "$base_ref" "$source_ref" -- 2>/dev/null || true)
+}
+
 wait_for_pr_merge() {
   local deadline
   deadline=$(( $(date +%s) + WAIT_TIMEOUT_SECONDS ))
   local wait_notice_printed=0
   local merge_output=""
+  local -a merge_flags=(--squash --delete-branch)
+  if [[ "$SKIP_CHECKS" -eq 1 ]]; then
+    merge_flags+=(--admin)
+  fi
 
   while true; do
-    if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch 2>&1)"; then
+    if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" "${merge_flags[@]}" 2>&1)"; then
       return 0
     fi
     if is_local_branch_delete_error "$merge_output"; then
@@ -752,6 +1230,7 @@ run_pr_flow() {
     return 0
   fi
 
+  maybe_push_changed_submodule_branches "$start_ref" "$SOURCE_BRANCH"
   git -C "$source_worktree" push -u origin "$SOURCE_BRANCH"
 
   pr_title="$(git -C "$repo_root" log -1 --pretty=%s "$SOURCE_BRANCH" 2>/dev/null || true)"
@@ -760,16 +1239,45 @@ run_pr_flow() {
   fi
   pr_body="Automated by gx branch finish (PR flow)."
 
-  "$GH_BIN" pr create \
+  pr_create_output=""
+  if pr_create_output="$("$GH_BIN" pr create \
     --base "$BASE_BRANCH" \
     --head "$SOURCE_BRANCH" \
     --title "$pr_title" \
-    --body "$pr_body" >/dev/null 2>&1 || true
+    --body "$pr_body" 2>&1)"; then
+    :
+  else
+    # Idempotent: a PR already opened for this head is fine — fall through
+    # to `gh pr view` so we still capture the URL. Anything else is a real
+    # failure and the user needs to see it.
+    if ! grep -qiE 'already exists|a pull request for branch' <<<"$pr_create_output"; then
+      echo "[agent-branch-finish] gh pr create failed:" >&2
+      echo "${pr_create_output}" >&2
+    fi
+  fi
 
   pr_url="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json url --jq '.url' 2>/dev/null || true)"
 
+  if [[ -z "$pr_url" ]]; then
+    echo "[agent-branch-finish] No PR found for '${SOURCE_BRANCH}' after gh pr create; cannot proceed with PR merge." >&2
+    if [[ -n "$pr_create_output" ]]; then
+      echo "[agent-branch-finish] Last gh pr create output:" >&2
+      echo "${pr_create_output}" >&2
+    fi
+    return 1
+  fi
+  echo "[agent-branch-finish] PR URL: ${pr_url}" >&2
+
+  # Pre-flight already passed by the time we reach the PR; promote any
+  # existing draft so the budget-friendly CI gate fires once.
+  maybe_auto_promote_pr "$pr_url"
+
   merge_output=""
-  if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch 2>&1)"; then
+  local -a merge_flags=(--squash --delete-branch)
+  if [[ "$SKIP_CHECKS" -eq 1 ]]; then
+    merge_flags+=(--admin)
+  fi
+  if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" "${merge_flags[@]}" 2>&1)"; then
     return 0
   fi
   if is_local_branch_delete_error "$merge_output"; then
@@ -783,7 +1291,11 @@ run_pr_flow() {
   fi
 
   auto_output=""
-  if auto_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch --auto 2>&1)"; then
+  local -a auto_flags=(--squash --delete-branch --auto)
+  if [[ "$SKIP_CHECKS" -eq 1 ]]; then
+    auto_flags+=(--admin)
+  fi
+  if auto_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" "${auto_flags[@]}" 2>&1)"; then
     echo "[agent-branch-finish] PR auto-merge enabled; waiting for required checks/reviews." >&2
     return 2
   fi
@@ -799,7 +1311,11 @@ run_pr_flow() {
 }
 
 if [[ "$PUSH_ENABLED" -eq 1 ]]; then
+  if ! run_preflight "$source_worktree"; then
+    exit 1
+  fi
   if [[ "$MERGE_MODE" != "pr" ]]; then
+    maybe_push_changed_submodule_branches "$start_ref" "$SOURCE_BRANCH"
     if ! direct_push_output="$(git -C "$integration_worktree" push origin "HEAD:${BASE_BRANCH}" 2>&1)"; then
       direct_push_error="$direct_push_output"
       merge_completed=0
@@ -847,9 +1363,7 @@ fi
 run_guardex_cli locks release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
 
 base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
-if [[ -n "$base_worktree" ]] && is_clean_worktree "$base_worktree" && [[ "$PUSH_ENABLED" -eq 1 ]]; then
-  git -C "$base_worktree" pull --ff-only origin "$BASE_BRANCH" >/dev/null 2>&1 || true
-fi
+refresh_clean_base_worktree "$base_worktree"
 maybe_auto_commit_parent_gitlink "$base_worktree"
 
 # Pivot out of the agent worktree before prune calls that may remove it.
@@ -861,6 +1375,10 @@ pivot_to_repo_root_before_prune() {
   fi
 }
 
+run_guardex_prune() {
+  GUARDEX_PRUNE_ACTIVE_CWD="$finish_active_cwd" run_guardex_cli worktree prune "$@"
+}
+
 if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
   if [[ "$source_worktree" == "$repo_root" ]]; then
     if is_clean_worktree "$source_worktree"; then
@@ -871,7 +1389,7 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
         git -C "$source_worktree" checkout --detach >/dev/null 2>&1 || true
       fi
       if [[ "$switched_to_base" -eq 1 && "$PUSH_ENABLED" -eq 1 ]] && git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
-        git -C "$source_worktree" pull --ff-only origin "$BASE_BRANCH" >/dev/null 2>&1 || true
+        refresh_clean_base_worktree "$source_worktree"
       fi
     fi
   elif [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* ]]; then
@@ -906,7 +1424,7 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
   fi
 
   pivot_to_repo_root_before_prune
-  if ! run_guardex_cli worktree prune "${prune_args[@]}"; then
+  if ! run_guardex_prune "${prune_args[@]}"; then
     echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
     echo "[agent-branch-finish] You can run manual cleanup: gx cleanup --base ${BASE_BRANCH}" >&2
   fi
@@ -920,7 +1438,7 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
   fi
 else
   pivot_to_repo_root_before_prune
-  if ! run_guardex_cli worktree prune --base "$BASE_BRANCH"; then
+  if ! run_guardex_prune --base "$BASE_BRANCH"; then
     echo "[agent-branch-finish] Warning: temporary worktree prune failed." >&2
   fi