@imdeadpool/guardex 7.0.13 → 7.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.13",
+  "version": "7.0.15",
   "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
   "license": "MIT",
   "preferGlobal": true,
@@ -60,7 +60,7 @@
   "bugs": {
     "url": "https://github.com/recodeee/gitguardex/issues"
   },
-  "homepage": "https://guardextutorial.com",
+  "homepage": "https://github.com/recodeee/gitguardex-frontend",
   "funding": "https://github.com/sponsors/recodeecom",
   "publishConfig": {
     "access": "public"

package/templates/AGENTS.multiagent-safety.md

@@ -1,21 +1,28 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Safety Contract
+## Multi-Agent Execution Contract (GX)
 
-**Repo toggle.** `GUARDEX_ON=0|false|no|off` disables this contract. `GUARDEX_ON=1|true|yes|on` re-enables it.
+**Repo toggle.** Guardex is enabled by default. If the repo root `.env` sets `GUARDEX_ON=0`, `false`, `no`, or `off`, treat this entire Guardex contract as disabled for the repo and do not require Guardex worktrees, lock claims, completion flow, or OpenSpec workflow until `GUARDEX_ON` is re-enabled.
 
-**Isolation.** One task = one `agent/*` branch + worktree. Start `scripts/agent-branch-start.sh "<task>" "<agent>"`. Base branches stay read-only. No `git checkout` on primary worktrees; use `git worktree add`. `.githooks/post-checkout` auto-reverts primary-branch switches unless `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
+**Repo toggle examples.** Add one of these lines to the repo-root `.env` file:
+`GUARDEX_ON=0` disables Guardex for that repo.
+`GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
-**Ownership.** Claim before edits: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Delete only claimed paths.
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
+For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
+Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 
-**Handoff.** Post a one-line note before edits. Re-read latest handoffs before replacing nearby work.
+**Ownership.** Before editing, claim files: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 
-**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` or `gx finish --all`. Done = commit pushed, PR URL recorded, state=`MERGED`, sandbox pruned. If blocked, append `BLOCKED:` and stop.
+**Handoff gate.** Post a one-line handoff note (plan/change, owned scope, intended action) before editing. Re-read the latest handoffs before replacing others' code.
 
-**Parallel safety.** Never revert unrelated edits. Report conflicts.
+**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
+OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
 
-**Reporting.** Completion handoff includes files changed, behavior touched, verification commands/results, and risks/follow-ups.
+**Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
 
-**OpenSpec.** Keep `openspec/changes/<slug>/tasks.md` current. End task scaffolds with PR merge + sandbox cleanup evidence. Run `openspec validate --specs` before archive.
+**Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
+
+**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `scripts/agent-branch-finish.sh ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/github/workflows/cr.yml

@@ -10,12 +10,18 @@ permissions:
 
 jobs:
   review:
-    if: ${{ secrets.OPENAI_API_KEY != '' }}
     runs-on: ubuntu-latest
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     steps:
-      - uses: anc95/ChatGPT-CodeReview@main
+      - name: Skip when OPENAI_API_KEY is missing
+        if: ${{ env.OPENAI_API_KEY == '' }}
+        run: echo "OPENAI_API_KEY is not configured; skipping Code Review workflow."
+
+      - uses: anc95/ChatGPT-CodeReview@1e3df152c1b85c12da580b206c91ad343460c584 # v1.0.23
+        if: ${{ env.OPENAI_API_KEY != '' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_API_KEY: ${{ env.OPENAI_API_KEY }}
           OPENAI_API_ENDPOINT: https://api.openai.com/v1
           MODEL: gpt-4o-mini

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

@@ -144,24 +144,44 @@ else
   common_git_dir="$(cd "$repo_root/$common_git_dir_raw" && pwd -P)"
 fi
 repo_common_root="$(cd "$common_git_dir/.." && pwd -P)"
-agent_worktree_root="${repo_common_root}/.omx/agent-worktrees"
 
 if [[ -z "$SOURCE_BRANCH" ]]; then
   SOURCE_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
 fi
 
+stored_worktree_root_rel="$(git -C "$repo_root" config --get "branch.${SOURCE_BRANCH}.guardexWorktreeRoot" || true)"
+if [[ -z "$stored_worktree_root_rel" ]]; then
+  stored_worktree_root_rel=".omx/agent-worktrees"
+fi
+agent_worktree_root="${repo_common_root}/${stored_worktree_root_rel}"
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   echo "[agent-branch-finish] --base requires a non-empty branch name." >&2
   exit 1
 fi
 
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
-  configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
-  if [[ -n "$configured_base" ]]; then
-    BASE_BRANCH="$configured_base"
+  source_branch_base="$(git -C "$repo_root" config --get "branch.${SOURCE_BRANCH}.guardexBase" || true)"
+  if [[ -n "$source_branch_base" ]]; then
+    BASE_BRANCH="$source_branch_base"
+  else
+    configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
+    if [[ -n "$configured_base" ]]; then
+      BASE_BRANCH="$configured_base"
+    fi
   fi
 fi
 
+if [[ -z "$BASE_BRANCH" ]]; then
+  for fallback_branch in dev main master; do
+    if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${fallback_branch}" \
+      || git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${fallback_branch}"; then
+      BASE_BRANCH="$fallback_branch"
+      break
+    fi
+  done
+fi
+
 if [[ -z "$BASE_BRANCH" ]]; then
   BASE_BRANCH="dev"
 fi
@@ -268,8 +288,17 @@ if [[ "$should_require_sync" -eq 1 ]] && git -C "$repo_root" show-ref --verify -
   fi
 fi
 
-integration_worktree="${agent_worktree_root}/__integrate-${BASE_BRANCH//\//__}-$(date +%Y%m%d-%H%M%S)"
-integration_branch="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
+integration_stamp="$(date +%Y%m%d-%H%M%S)"
+integration_worktree_base="${agent_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
+integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
+integration_worktree="$integration_worktree_base"
+integration_branch="$integration_branch_base"
+integration_suffix=1
+while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
+  integration_worktree="${integration_worktree_base}-${integration_suffix}"
+  integration_branch="${integration_branch_base}_${integration_suffix}"
+  integration_suffix=$((integration_suffix + 1))
+done
 mkdir -p "$(dirname "$integration_worktree")"
 
 git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null

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

@@ -5,7 +5,8 @@ TASK_NAME="task"
 AGENT_NAME="agent"
 BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
-WORKTREE_ROOT_REL=".omx/agent-worktrees"
+WORKTREE_ROOT_REL=""
+WORKTREE_ROOT_EXPLICIT=0
 OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
@@ -44,6 +45,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     --worktree-root)
       WORKTREE_ROOT_REL="${2:-.omx/agent-worktrees}"
+      WORKTREE_ROOT_EXPLICIT=1
       shift 2
       ;;
     --)
@@ -123,12 +125,41 @@ shorten_slug() {
   printf '%s' "$shortened"
 }
 
-# Collapse arbitrary agent identifiers to a clean role token: claude | codex |
-# <other-kebab>. Priority: GUARDEX_AGENT_TYPE env override, then the raw
-# AGENT_NAME (if it contains 'claude' or 'codex'), then CLAUDECODE=1 sentinel
-# (set by Claude Code CLI), else fall back to 'codex'. Any other role name
-# (integrator, executor, rust-port, etc.) is preserved as-is after slug
-# sanitization.
+env_flag_truthy() {
+  local raw="${1:-}"
+  local lowered
+  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$lowered" in
+    1|true|yes|on) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+default_worktree_root_rel() {
+  local raw_agent="$1"
+  local override="${GUARDEX_AGENT_TYPE:-}"
+  local lowered_agent lowered_override
+  lowered_agent="$(printf '%s' "$raw_agent" | tr '[:upper:]' '[:lower:]')"
+  lowered_override="$(printf '%s' "$override" | tr '[:upper:]' '[:lower:]')"
+
+  if [[ -n "${CLAUDE_CODE_SESSION_ID:-}" ]] || env_flag_truthy "${CLAUDECODE:-}"; then
+    printf '.omc/agent-worktrees'
+    return 0
+  fi
+
+  if [[ "$lowered_agent" == *claude* ]] || [[ "$lowered_override" == *claude* ]]; then
+    printf '.omc/agent-worktrees'
+    return 0
+  fi
+
+  printf '.omx/agent-worktrees'
+}
+
+# Collapse arbitrary agent identifiers to a clean role token. Priority:
+# GUARDEX_AGENT_TYPE env override, then recognizable claude/codex aliases, then
+# a small legacy compatibility set, then the literal requested role after slug
+# sanitization. This preserves explicit roles such as planner/executor while
+# keeping the older bot -> codex fallback stable for existing callers.
 normalize_role() {
   local raw_agent="$1"
   local override="${GUARDEX_AGENT_TYPE:-}"
@@ -150,10 +181,13 @@ normalize_role() {
     printf 'claude'
     return 0
   fi
-  # Unrecognized raw name (rust-port-lead, some-worker, empty, ...): default to
-  # codex. To get a different role (integrator, executor, ...) pass the role
-  # explicitly via GUARDEX_AGENT_TYPE, handled above.
-  printf 'codex'
+  local sanitized
+  sanitized="$(sanitize_slug "$raw_agent" "codex")"
+  if [[ "$sanitized" == "bot" ]]; then
+    printf 'codex'
+    return 0
+  fi
+  printf '%s' "$sanitized"
 }
 
 # Timestamp the branch/worktree/openspec slug so parallel agents never collide
@@ -413,6 +447,9 @@ fi
 
 task_slug="$(sanitize_slug "$TASK_NAME" "task")"
 agent_slug="$(normalize_role "$AGENT_NAME")"
+if [[ "$WORKTREE_ROOT_EXPLICIT" -eq 0 ]]; then
+  WORKTREE_ROOT_REL="$(default_worktree_root_rel "$AGENT_NAME")"
+fi
 branch_timestamp="$(compose_branch_timestamp)"
 branch_descriptor="$(compose_branch_descriptor "$task_slug" "$branch_timestamp")"
 branch_name_base="agent/${agent_slug}/${branch_descriptor}"
@@ -497,6 +534,7 @@ if ! worktree_add_output="$(git -C "$repo_root" worktree add -b "$branch_name" "
   exit 1
 fi
 git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
+git -C "$repo_root" config "branch.${branch_name}.guardexWorktreeRoot" "$WORKTREE_ROOT_REL" >/dev/null 2>&1 || true
 # Fresh agent branches should start unpublished; clear any inherited base-branch tracking.
 git -C "$worktree_path" branch --unset-upstream "$branch_name" >/dev/null 2>&1 || true
 
@@ -533,4 +571,4 @@ echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
 echo "  python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" <file...>"
 echo "  # implement + commit"
-echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base dev --via-pr --wait-for-merge"
+echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"

package/templates/scripts/agent-worktree-prune.sh

@@ -8,11 +8,20 @@ FORCE_DIRTY=0
 DELETE_BRANCHES=0
 DELETE_REMOTE_BRANCHES=0
 ONLY_DIRTY_WORKTREES=0
+INCLUDE_PR_MERGED=0
 TARGET_BRANCH=""
 IDLE_MINUTES=0
 NOW_EPOCH_RAW="${GUARDEX_PRUNE_NOW_EPOCH:-}"
 IDLE_SECONDS=0
 NOW_EPOCH=0
+GH_BIN="${GUARDEX_GH_BIN:-gh}"
+PR_MERGED_LOOKUP_DISABLED=0
+PR_MERGED_LOOKUP_LOADED=0
+declare -A MERGED_PR_BRANCHES=()
+WORKTREE_ROOT_RELS=(
+  ".omx/agent-worktrees"
+  ".omc/agent-worktrees"
+)
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -45,6 +54,10 @@ while [[ $# -gt 0 ]]; do
       ONLY_DIRTY_WORKTREES=1
       shift
       ;;
+    --include-pr-merged)
+      INCLUDE_PR_MERGED=1
+      shift
+      ;;
     --branch)
       TARGET_BRANCH="${2:-}"
       shift 2
@@ -55,7 +68,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     *)
       echo "[agent-worktree-prune] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>] [--idle-minutes <minutes>]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--include-pr-merged] [--branch <agent/...>] [--idle-minutes <minutes>]" >&2
       exit 1
       ;;
   esac
@@ -68,13 +81,36 @@ fi
 
 repo_root="$(git rev-parse --show-toplevel)"
 current_pwd="$(pwd -P)"
-worktree_root="${repo_root}/.omx/agent-worktrees"
 repo_common_dir="$(
   git -C "$repo_root" rev-parse --git-common-dir \
     | awk -v root="$repo_root" '{ if ($0 ~ /^\//) { print $0 } else { print root "/" $0 } }'
 )"
 repo_common_dir="$(cd "$repo_common_dir" && pwd -P)"
 
+resolve_worktree_root_rel_for_entry() {
+  local entry="$1"
+  case "$entry" in
+    */.omc/agent-worktrees/*)
+      printf '%s' '.omc/agent-worktrees'
+      ;;
+    *)
+      printf '%s' '.omx/agent-worktrees'
+      ;;
+  esac
+}
+
+is_managed_worktree_path() {
+  local entry="$1"
+  local rel root
+  for rel in "${WORKTREE_ROOT_RELS[@]}"; do
+    root="${repo_root}/${rel}"
+    if [[ "$entry" == "${root}"/* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
 resolve_base_branch() {
   local configured=""
   local current=""
@@ -101,6 +137,44 @@ resolve_base_branch() {
   printf '%s' ""
 }
 
+load_merged_pr_branches() {
+  if [[ "$INCLUDE_PR_MERGED" -ne 1 ]]; then
+    return 1
+  fi
+  if [[ "$PR_MERGED_LOOKUP_DISABLED" -eq 1 ]]; then
+    return 1
+  fi
+  if [[ "$PR_MERGED_LOOKUP_LOADED" -eq 1 ]]; then
+    return 0
+  fi
+  if ! command -v "$GH_BIN" >/dev/null 2>&1; then
+    PR_MERGED_LOOKUP_DISABLED=1
+    return 1
+  fi
+
+  local merged_branches=""
+  merged_branches="$(
+    "$GH_BIN" pr list --state merged --base "$BASE_BRANCH" --limit 200 --json headRefName --jq '.[].headRefName' 2>/dev/null || true
+  )"
+  if [[ -n "$merged_branches" ]]; then
+    while IFS= read -r merged_branch; do
+      [[ -z "$merged_branch" ]] && continue
+      MERGED_PR_BRANCHES["$merged_branch"]=1
+    done <<< "$merged_branches"
+  fi
+  PR_MERGED_LOOKUP_LOADED=1
+  return 0
+}
+
+branch_has_merged_pr() {
+  local branch="$1"
+  if [[ "$INCLUDE_PR_MERGED" -ne 1 ]]; then
+    return 1
+  fi
+  load_merged_pr_branches || return 1
+  [[ -n "${MERGED_PR_BRANCHES[$branch]:-}" ]]
+}
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   echo "[agent-worktree-prune] --base requires a non-empty branch name." >&2
   exit 1
@@ -261,54 +335,59 @@ relocated_foreign=0
 skipped_foreign=0
 
 relocate_foreign_worktree_entries() {
-  [[ -d "$worktree_root" ]] || return 0
-
-  local entry=""
-  for entry in "${worktree_root}"/*; do
-    [[ -d "$entry" ]] || continue
-    if ! git -C "$entry" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-      continue
-    fi
-
-    local entry_common_dir=""
-    entry_common_dir="$(resolve_worktree_common_dir "$entry" || true)"
-    [[ -n "$entry_common_dir" ]] || continue
+  local rel="" worktree_root="" entry=""
+  for rel in "${WORKTREE_ROOT_RELS[@]}"; do
+    worktree_root="${repo_root}/${rel}"
+    [[ -d "$worktree_root" ]] || continue
+
+    for entry in "${worktree_root}"/*; do
+      [[ -d "$entry" ]] || continue
+      if ! git -C "$entry" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        continue
+      fi
 
-    if [[ "$entry_common_dir" == "$repo_common_dir" ]]; then
-      continue
-    fi
+      local entry_common_dir=""
+      entry_common_dir="$(resolve_worktree_common_dir "$entry" || true)"
+      [[ -n "$entry_common_dir" ]] || continue
 
-    if [[ "$(basename "$entry_common_dir")" != ".git" ]]; then
-      skipped_foreign=$((skipped_foreign + 1))
-      echo "[agent-worktree-prune] Skipping foreign worktree with unsupported git common dir: ${entry}"
-      continue
-    fi
+      if [[ "$entry_common_dir" == "$repo_common_dir" ]]; then
+        continue
+      fi
 
-    local owner_repo_root
-    owner_repo_root="$(dirname "$entry_common_dir")"
-    local owner_worktree_root="${owner_repo_root}/.omx/agent-worktrees"
-    local target_path
-    target_path="$(select_unique_worktree_path "$owner_worktree_root" "$(basename "$entry")")"
+      if [[ "$(basename "$entry_common_dir")" != ".git" ]]; then
+        skipped_foreign=$((skipped_foreign + 1))
+        echo "[agent-worktree-prune] Skipping foreign worktree with unsupported git common dir: ${entry}"
+        continue
+      fi
 
-    if [[ "$entry" == "$current_pwd" || "$current_pwd" == "${entry}"/* ]]; then
-      skipped_foreign=$((skipped_foreign + 1))
-      echo "[agent-worktree-prune] Skipping active foreign worktree: ${entry}"
-      continue
-    fi
+      local owner_repo_root
+      owner_repo_root="$(dirname "$entry_common_dir")"
+      local owner_worktree_root_rel owner_worktree_root
+      owner_worktree_root_rel="$(resolve_worktree_root_rel_for_entry "$entry")"
+      owner_worktree_root="${owner_repo_root}/${owner_worktree_root_rel}"
+      local target_path
+      target_path="$(select_unique_worktree_path "$owner_worktree_root" "$(basename "$entry")")"
+
+      if [[ "$entry" == "$current_pwd" || "$current_pwd" == "${entry}"/* ]]; then
+        skipped_foreign=$((skipped_foreign + 1))
+        echo "[agent-worktree-prune] Skipping active foreign worktree: ${entry}"
+        continue
+      fi
 
-    echo "[agent-worktree-prune] Relocating foreign worktree to owning repo: ${entry} -> ${target_path}"
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      relocated_foreign=$((relocated_foreign + 1))
-      continue
-    fi
+      echo "[agent-worktree-prune] Relocating foreign worktree to owning repo: ${entry} -> ${target_path}"
+      if [[ "$DRY_RUN" -eq 1 ]]; then
+        relocated_foreign=$((relocated_foreign + 1))
+        continue
+      fi
 
-    mkdir -p "$owner_worktree_root"
-    if git -C "$owner_repo_root" worktree move "$entry" "$target_path" >/dev/null 2>&1; then
-      relocated_foreign=$((relocated_foreign + 1))
-    else
-      skipped_foreign=$((skipped_foreign + 1))
-      echo "[agent-worktree-prune] Failed to relocate foreign worktree: ${entry}" >&2
-    fi
+      mkdir -p "$owner_worktree_root"
+      if git -C "$owner_repo_root" worktree move "$entry" "$target_path" >/dev/null 2>&1; then
+        relocated_foreign=$((relocated_foreign + 1))
+      else
+        skipped_foreign=$((skipped_foreign + 1))
+        echo "[agent-worktree-prune] Failed to relocate foreign worktree: ${entry}" >&2
+      fi
+    done
   done
 }
 
@@ -324,7 +403,9 @@ process_entry() {
   local branch_ref="$2"
 
   [[ -z "$wt" ]] && return
-  [[ "$wt" != "${worktree_root}"/* ]] && return
+  if ! is_managed_worktree_path "$wt"; then
+    return
+  fi
 
   local branch=""
   if [[ -n "$branch_ref" ]]; then
@@ -342,6 +423,7 @@ process_entry() {
   fi
 
   local remove_reason=""
+  local branch_delete_mode="safe"
 
   if [[ -z "$branch_ref" ]]; then
     remove_reason="detached-worktree"
@@ -352,6 +434,9 @@ process_entry() {
       if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
         remove_reason="merged-agent-branch"
       fi
+    elif [[ "$DELETE_BRANCHES" -eq 1 ]] && branch_has_merged_pr "$branch"; then
+      remove_reason="merged-agent-pr"
+      branch_delete_mode="force"
     elif [[ "$ONLY_DIRTY_WORKTREES" -eq 1 ]] && is_clean_worktree "$wt"; then
       remove_reason="clean-agent-worktree"
     fi
@@ -383,13 +468,19 @@ process_entry() {
 
   if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}" && ! branch_has_worktree "$branch"; then
     if [[ "$branch" == agent/* && "$DELETE_BRANCHES" -eq 1 ]]; then
-      if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
+      local delete_flag="-d"
+      local deleted_label="merged"
+      if [[ "$branch_delete_mode" == "force" ]]; then
+        delete_flag="-D"
+        deleted_label="merged PR"
+      fi
+      if run_cmd git -C "$repo_root" branch "$delete_flag" "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
-        echo "[agent-worktree-prune] Deleted merged branch: ${branch}"
+        echo "[agent-worktree-prune] Deleted ${deleted_label} branch: ${branch}"
         if [[ "$DELETE_REMOTE_BRANCHES" -eq 1 ]]; then
           if git -C "$repo_root" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
             run_cmd git -C "$repo_root" push origin --delete "$branch" >/dev/null 2>&1 || true
-            echo "[agent-worktree-prune] Deleted merged remote branch: ${branch}"
+            echo "[agent-worktree-prune] Deleted ${deleted_label} remote branch: ${branch}"
           fi
         fi
       fi
@@ -420,7 +511,7 @@ while IFS= read -r line || [[ -n "$line" ]]; do
       current_branch_ref="${line#branch }"
       ;;
   esac
-done < <(git -C "$repo_root" worktree list --porcelain)
+  done < <(git -C "$repo_root" worktree list --porcelain)
 
 process_entry "$current_wt" "$current_branch_ref"
 
@@ -436,14 +527,27 @@ if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
     if ! branch_idle_gate "$branch" "" "stale-merged-branch"; then
       continue
     fi
+    merged_by_ancestor=0
+    merged_by_pr=0
     if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
-      if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
+      merged_by_ancestor=1
+    elif branch_has_merged_pr "$branch"; then
+      merged_by_pr=1
+    fi
+    if [[ "$merged_by_ancestor" -eq 1 || "$merged_by_pr" -eq 1 ]]; then
+      delete_flag="-d"
+      deleted_label="merged"
+      if [[ "$merged_by_pr" -eq 1 && "$merged_by_ancestor" -eq 0 ]]; then
+        delete_flag="-D"
+        deleted_label="merged PR"
+      fi
+      if run_cmd git -C "$repo_root" branch "$delete_flag" "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
-        echo "[agent-worktree-prune] Deleted stale merged branch: ${branch}"
+        echo "[agent-worktree-prune] Deleted stale ${deleted_label} branch: ${branch}"
         if [[ "$DELETE_REMOTE_BRANCHES" -eq 1 ]]; then
           if git -C "$repo_root" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
             run_cmd git -C "$repo_root" push origin --delete "$branch" >/dev/null 2>&1 || true
-            echo "[agent-worktree-prune] Deleted stale merged remote branch: ${branch}"
+            echo "[agent-worktree-prune] Deleted stale ${deleted_label} remote branch: ${branch}"
           fi
         fi
       fi

package/templates/scripts/codex-agent.sh

@@ -249,6 +249,35 @@ resolve_start_ref() {
   return 1
 }
 
+origin_remote_looks_like_github() {
+  local wt="$1"
+  local origin_url=""
+  origin_url="$(git -C "$wt" remote get-url origin 2>/dev/null || true)"
+  [[ -n "$origin_url" && "$origin_url" =~ github\.com[:/] ]]
+}
+
+auto_finish_context_is_ready() {
+  local wt="$1"
+  local gh_bin="${GUARDEX_GH_BIN:-gh}"
+
+  if ! git -C "$wt" remote get-url origin >/dev/null 2>&1; then
+    return 1
+  fi
+  if ! command -v "$gh_bin" >/dev/null 2>&1; then
+    return 1
+  fi
+
+  if [[ -n "${GUARDEX_GH_BIN:-}" ]]; then
+    return 0
+  fi
+
+  if ! origin_remote_looks_like_github "$wt"; then
+    return 1
+  fi
+
+  "$gh_bin" auth status >/dev/null 2>&1
+}
+
 restore_repo_branch_if_changed() {
   local expected_branch="$1"
   if [[ -z "$expected_branch" || "$expected_branch" == "HEAD" ]]; then
@@ -372,6 +401,17 @@ has_origin_remote() {
   git -C "$repo_root" remote get-url origin >/dev/null 2>&1
 }
 
+origin_remote_supports_pr_finish() {
+  local origin_url
+  origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
+  case "$origin_url" in
+    ''|/*|./*|../*|file://*)
+      return 1
+      ;;
+  esac
+  return 0
+}
+
 resolve_worktree_base_branch() {
   local _wt="$1"
   if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -n "$BASE_BRANCH" ]]; then
@@ -685,7 +725,12 @@ run_finish_flow() {
       echo "[codex-agent] Auto-finish requires GitHub CLI for PR flow; command not found: ${GUARDEX_GH_BIN:-gh}" >&2
       return 2
     fi
-    finish_args+=(--via-pr)
+    if origin_remote_supports_pr_finish; then
+      finish_args+=(--via-pr)
+    else
+      echo "[codex-agent] Origin remote does not provide a mergeable PR surface; skipping auto-finish merge/PR pipeline." >&2
+      return 2
+    fi
   else
     echo "[codex-agent] No origin remote detected; skipping auto-finish merge/PR pipeline." >&2
     return 2
@@ -764,7 +809,9 @@ if [[ "$AUTO_FINISH" -eq 1 && -n "$worktree_branch" && "$worktree_branch" != "HE
   else
     echo "[codex-agent] Auto-finish enabled: commit -> push/PR -> merge (keep branch/worktree)."
   fi
-  if auto_commit_worktree_changes "$worktree_path" "$worktree_branch"; then
+  if ! auto_finish_context_is_ready "$worktree_path"; then
+    echo "[codex-agent] Auto-finish skipped for '${worktree_branch}' (no mergeable remote context)." >&2
+  elif auto_commit_worktree_changes "$worktree_path" "$worktree_branch"; then
     if run_finish_flow "$worktree_path" "$worktree_branch"; then
       auto_finish_completed=1
       echo "[codex-agent] Auto-finish completed for '${worktree_branch}'."