@imdeadpool/guardex 5.0.1 → 5.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.1",
+  "version": "5.0.3",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -15,7 +15,7 @@
     "agent:codex": "bash ./scripts/codex-agent.sh",
     "agent:branch:start": "bash ./scripts/agent-branch-start.sh",
     "agent:branch:finish": "bash ./scripts/agent-branch-finish.sh",
-    "agent:cleanup": "bash ./scripts/agent-worktree-prune.sh --base dev",
+    "agent:cleanup": "gx cleanup",
     "agent:hooks:install": "bash ./scripts/install-agent-git-hooks.sh",
     "agent:locks:claim": "python3 ./scripts/agent-file-locks.py claim",
     "agent:locks:allow-delete": "python3 ./scripts/agent-file-locks.py allow-delete",

package/templates/AGENTS.multiagent-safety.md

@@ -11,8 +11,14 @@
 - If ownership is unclear or overlaps, stop that edit, post a blocker comment, and let the leader/integrator reassign scope.
 - For git isolation, each agent must start on a dedicated branch via `scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"`.
 - Treat the base branch (`main` or the user's current local base branch) as read-only while the agent branch is active.
-- Agent completion must use `scripts/agent-branch-finish.sh` (direct merge to base when allowed; auto PR fallback for protected bases, then cleanup after merge).
+- Agent completion defaults to `scripts/codex-agent.sh`, which auto-finishes the branch (auto-commit changed files, push/create PR, attempt merge, and pull the local base branch after merge).
+- Auto-finish now waits for required checks/merge and then cleans merged sandbox branch/worktree by default.
+- Use `--no-cleanup` only when you explicitly need to keep a merged sandbox for audit/debug follow-up.
+- If codex-agent auto-finish cannot complete, immediately run `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge` and keep the branch open until checks/review pass.
+- If merge/rebase conflicts block auto-finish, run a conflict-resolution review pass in that sandbox branch, then rerun `agent-branch-finish.sh --via-pr` until merged.
+- Completion is not valid until these are true: commit exists on the agent branch, branch is pushed to `origin`, and PR/merge status is produced by `agent-branch-finish.sh` or `codex-agent`.
 - Per-message loop is mandatory: for every new user message/task, start a fresh agent branch/worktree, claim ownership locks, implement and verify, finish via PR/merge cleanup, then repeat for the next message/task.
+- If the change publishes or bumps a version, the same change must also update release notes/changelog entries.
 
 1. Explicit ownership before edits
 

package/templates/codex/skills/guardex/SKILL.md

@@ -36,4 +36,6 @@ gx scan
 - Keep agent work isolated (`agent/*` branches + lock claims).
 - For every new user message/task, restart the full loop on a fresh agent branch/worktree.
 - For one-command Codex sandbox startup, use `bash scripts/codex-agent.sh "<task>" "<agent-name>"`.
+- `scripts/codex-agent.sh` auto-syncs the sandbox branch against base before each task and auto-finishes merge/PR flow after Codex exits.
+- Auto-finish keeps the branch/worktree by default; remove merged branches explicitly with `gx cleanup` (or `gx cleanup --branch "<agent-branch>"`).
 - Do not bypass protected branch safeguards unless explicitly required.

package/templates/githooks/pre-commit

@@ -50,9 +50,31 @@ case "$codex_require_agent_branch" in
   *) should_require_codex_agent_branch=1 ;;
 esac
 
+is_codex_managed_only_commit_on_protected=0
+if [[ "$is_codex_session" == "1" && "$is_protected_branch" == "1" ]]; then
+  deleted_paths="$(git diff --cached --name-only --diff-filter=D)"
+  staged_paths="$(git diff --cached --name-only --diff-filter=ACMRTUXB)"
+  if [[ -z "$deleted_paths" && -n "$staged_paths" ]]; then
+    managed_only=1
+    while IFS= read -r staged_path; do
+      case "$staged_path" in
+        AGENTS.md|.gitignore) ;;
+        *) managed_only=0; break ;;
+      esac
+    done <<< "$staged_paths"
+    if [[ "$managed_only" == "1" ]]; then
+      is_codex_managed_only_commit_on_protected=1
+    fi
+  fi
+fi
+
 if [[ "$should_require_codex_agent_branch" == "1" && "${MUSAFETY_ALLOW_CODEX_ON_NON_AGENT:-0}" != "1" ]]; then
   if [[ "$is_codex_session" == "1" && "$branch" != agent/* ]]; then
     if [[ "$is_protected_branch" == "1" ]]; then
+      if [[ "$is_codex_managed_only_commit_on_protected" == "1" ]]; then
+        exit 0
+      fi
+
       cat >&2 <<'MSG'
 [guardex-preedit-guard] Codex edit/commit detected on a protected branch.
 GuardeX requires Codex work to run from an isolated agent/* branch.

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

@@ -5,9 +5,49 @@ BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 SOURCE_BRANCH=""
 PUSH_ENABLED=1
-DELETE_REMOTE_BRANCH=1
+DELETE_REMOTE_BRANCH=0
+DELETE_REMOTE_BRANCH_EXPLICIT=0
 MERGE_MODE="auto"
 GH_BIN="${MUSAFETY_GH_BIN:-gh}"
+CLEANUP_AFTER_MERGE_RAW="${MUSAFETY_FINISH_CLEANUP:-false}"
+WAIT_FOR_MERGE_RAW="${MUSAFETY_FINISH_WAIT_FOR_MERGE:-false}"
+WAIT_TIMEOUT_SECONDS_RAW="${MUSAFETY_FINISH_WAIT_TIMEOUT_SECONDS:-1800}"
+WAIT_POLL_SECONDS_RAW="${MUSAFETY_FINISH_WAIT_POLL_SECONDS:-10}"
+
+normalize_bool() {
+  local raw="${1:-}"
+  local fallback="${2:-0}"
+  local lowered
+  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$lowered" in
+    1|true|yes|on) printf '1' ;;
+    0|false|no|off) printf '0' ;;
+    '') printf '%s' "$fallback" ;;
+    *) printf '%s' "$fallback" ;;
+  esac
+}
+
+normalize_int() {
+  local raw="${1:-}"
+  local fallback="${2:-0}"
+  local min_value="${3:-0}"
+  local value="$raw"
+
+  if [[ -z "$value" || ! "$value" =~ ^[0-9]+$ ]]; then
+    value="$fallback"
+  fi
+
+  if (( value < min_value )); then
+    value="$min_value"
+  fi
+
+  printf '%s' "$value"
+}
+
+CLEANUP_AFTER_MERGE="$(normalize_bool "$CLEANUP_AFTER_MERGE_RAW" "0")"
+WAIT_FOR_MERGE="$(normalize_bool "$WAIT_FOR_MERGE_RAW" "0")"
+WAIT_TIMEOUT_SECONDS="$(normalize_int "$WAIT_TIMEOUT_SECONDS_RAW" "1800" "30")"
+WAIT_POLL_SECONDS="$(normalize_int "$WAIT_POLL_SECONDS_RAW" "10" "0")"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -26,8 +66,38 @@ while [[ $# -gt 0 ]]; do
       ;;
     --keep-remote-branch)
       DELETE_REMOTE_BRANCH=0
+      DELETE_REMOTE_BRANCH_EXPLICIT=1
+      shift
+      ;;
+    --delete-remote-branch)
+      DELETE_REMOTE_BRANCH=1
+      DELETE_REMOTE_BRANCH_EXPLICIT=1
+      shift
+      ;;
+    --cleanup)
+      CLEANUP_AFTER_MERGE=1
+      shift
+      ;;
+    --no-cleanup)
+      CLEANUP_AFTER_MERGE=0
+      shift
+      ;;
+    --wait-for-merge)
+      WAIT_FOR_MERGE=1
+      shift
+      ;;
+    --no-wait-for-merge)
+      WAIT_FOR_MERGE=0
       shift
       ;;
+    --wait-timeout-seconds)
+      WAIT_TIMEOUT_SECONDS="$(normalize_int "${2:-}" "1800" "30")"
+      shift 2
+      ;;
+    --wait-poll-seconds)
+      WAIT_POLL_SECONDS="$(normalize_int "${2:-}" "10" "0")"
+      shift 2
+      ;;
     --mode)
       MERGE_MODE="${2:-auto}"
       shift 2
@@ -42,12 +112,16 @@ while [[ $# -gt 0 ]]; do
       ;;
     *)
       echo "[agent-branch-finish] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--keep-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>] [--keep-remote-branch|--delete-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only]" >&2
       exit 1
       ;;
   esac
 done
 
+if [[ "$CLEANUP_AFTER_MERGE" -eq 1 && "$DELETE_REMOTE_BRANCH_EXPLICIT" -eq 0 ]]; then
+  DELETE_REMOTE_BRANCH=1
+fi
+
 case "$MERGE_MODE" in
   auto|direct|pr) ;;
   *)
@@ -63,6 +137,14 @@ fi
 
 repo_root="$(git rev-parse --show-toplevel)"
 current_worktree="$(pwd -P)"
+common_git_dir_raw="$(git -C "$repo_root" rev-parse --git-common-dir)"
+if [[ "$common_git_dir_raw" == /* ]]; then
+  common_git_dir="$common_git_dir_raw"
+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)"
@@ -136,7 +218,7 @@ created_source_probe=0
 source_probe_path=""
 
 if [[ -z "$source_worktree" ]]; then
-  source_probe_path="${repo_root}/.omx/agent-worktrees/__source-probe-${SOURCE_BRANCH//\//__}-$(date +%Y%m%d-%H%M%S)"
+  source_probe_path="${agent_worktree_root}/__source-probe-${SOURCE_BRANCH//\//__}-$(date +%Y%m%d-%H%M%S)"
   mkdir -p "$(dirname "$source_probe_path")"
   git -C "$repo_root" worktree add "$source_probe_path" "$SOURCE_BRANCH" >/dev/null
   source_worktree="$source_probe_path"
@@ -194,7 +276,7 @@ if [[ "$should_require_sync" -eq 1 ]] && git -C "$repo_root" show-ref --verify -
   fi
 fi
 
-integration_worktree="${repo_root}/.omx/agent-worktrees/__integrate-${BASE_BRANCH//\//__}-$(date +%Y%m%d-%H%M%S)"
+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)"
 mkdir -p "$(dirname "$integration_worktree")"
 
@@ -254,6 +336,78 @@ is_local_branch_delete_error() {
   return 1
 }
 
+read_pr_state() {
+  local state_line
+  state_line="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json state,mergedAt,url --jq '[.state, (.mergedAt // ""), (.url // "")] | @tsv' 2>/dev/null || true)"
+  if [[ -z "$state_line" ]]; then
+    return 1
+  fi
+
+  local parsed_state=""
+  local parsed_merged_at=""
+  local parsed_url=""
+  IFS=$'\t' read -r parsed_state parsed_merged_at parsed_url <<< "$state_line"
+  PR_STATE="$parsed_state"
+  PR_MERGED_AT="$parsed_merged_at"
+  if [[ -n "$parsed_url" ]]; then
+    pr_url="$parsed_url"
+  fi
+  return 0
+}
+
+wait_for_pr_merge() {
+  local deadline
+  deadline=$(( $(date +%s) + WAIT_TIMEOUT_SECONDS ))
+  local wait_notice_printed=0
+  local merge_output=""
+
+  while true; do
+    if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch 2>&1)"; then
+      return 0
+    fi
+    if is_local_branch_delete_error "$merge_output"; then
+      echo "[agent-branch-finish] PR merged but gh could not delete the local branch (active worktree); continuing local cleanup." >&2
+      return 0
+    fi
+
+    PR_STATE=""
+    PR_MERGED_AT=""
+    if read_pr_state; then
+      if [[ "$PR_STATE" == "MERGED" || -n "$PR_MERGED_AT" ]]; then
+        return 0
+      fi
+      if [[ "$PR_STATE" == "CLOSED" ]]; then
+        echo "[agent-branch-finish] PR closed without merge; cannot continue auto-finish." >&2
+        if [[ -n "$pr_url" ]]; then
+          echo "[agent-branch-finish] PR: ${pr_url}" >&2
+        fi
+        if [[ -n "$merge_output" ]]; then
+          echo "$merge_output" >&2
+        fi
+        return 1
+      fi
+    fi
+
+    if [[ "$wait_notice_printed" -eq 0 ]]; then
+      echo "[agent-branch-finish] Waiting for required checks/reviews, then retrying merge automatically (timeout ${WAIT_TIMEOUT_SECONDS}s)." >&2
+      if [[ -n "$pr_url" ]]; then
+        echo "[agent-branch-finish] PR: ${pr_url}" >&2
+      fi
+      wait_notice_printed=1
+    fi
+
+    if (( $(date +%s) >= deadline )); then
+      echo "[agent-branch-finish] Timed out waiting for PR merge after ${WAIT_TIMEOUT_SECONDS}s." >&2
+      if [[ -n "$merge_output" ]]; then
+        echo "$merge_output" >&2
+      fi
+      return 2
+    fi
+
+    sleep "$WAIT_POLL_SECONDS"
+  done
+}
+
 run_pr_flow() {
   if ! command -v "$GH_BIN" >/dev/null 2>&1; then
     echo "[agent-branch-finish] PR fallback requested but GitHub CLI not found: ${GH_BIN}" >&2
@@ -285,6 +439,11 @@ run_pr_flow() {
     return 0
   fi
 
+  if [[ "$WAIT_FOR_MERGE" -eq 1 ]]; then
+    wait_for_pr_merge
+    return $?
+  fi
+
   auto_output=""
   if auto_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch --auto 2>&1)"; then
     echo "[agent-branch-finish] PR auto-merge enabled; waiting for required checks/reviews." >&2
@@ -330,6 +489,10 @@ if [[ "$PUSH_ENABLED" -eq 1 ]]; then
         if [[ -n "$pr_url" ]]; then
           echo "[agent-branch-finish] PR: ${pr_url}" >&2
         fi
+        if [[ "$WAIT_FOR_MERGE" -eq 1 ]]; then
+          echo "[agent-branch-finish] Merge did not complete within wait window; keeping branch open." >&2
+          exit 1
+        fi
         echo "[agent-branch-finish] Merge pending review/check policy. Branch cleanup skipped for now." >&2
         exit 0
       fi
@@ -347,43 +510,63 @@ if [[ -x "${repo_root}/scripts/agent-file-locks.py" ]]; then
   python3 "${repo_root}/scripts/agent-file-locks.py" release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
 fi
 
-if [[ "$source_worktree" == "$repo_root" ]]; then
-  if is_clean_worktree "$source_worktree"; then
-    git -C "$source_worktree" checkout "$BASE_BRANCH" >/dev/null 2>&1 || true
-    if [[ "$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
+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
+
+if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
+  if [[ "$source_worktree" == "$repo_root" ]]; then
+    if is_clean_worktree "$source_worktree"; then
+      switched_to_base=0
+      if git -C "$source_worktree" checkout "$BASE_BRANCH" >/dev/null 2>&1; then
+        switched_to_base=1
+      else
+        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
+      fi
     fi
+  elif [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* ]]; then
+    git -C "$source_worktree" checkout --detach >/dev/null 2>&1 || true
   fi
-elif [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
-  git -C "$source_worktree" checkout --detach >/dev/null 2>&1 || true
-fi
 
-if [[ "$source_worktree" != "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
-  git -C "$repo_root" worktree remove "$source_worktree" --force >/dev/null 2>&1 || true
-fi
+  if [[ "$source_worktree" != "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* ]]; then
+    git -C "$repo_root" worktree remove "$source_worktree" --force >/dev/null 2>&1 || true
+  fi
 
-git -C "$repo_root" branch -d "$SOURCE_BRANCH"
+  git -C "$repo_root" branch -d "$SOURCE_BRANCH"
 
-if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
-  if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
-    git -C "$repo_root" push origin --delete "$SOURCE_BRANCH"
+  if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+    if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
+      git -C "$repo_root" push origin --delete "$SOURCE_BRANCH"
+    fi
   fi
-fi
 
-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
+  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
+    prune_args=(--base "$BASE_BRANCH" --delete-branches)
+    if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+      prune_args+=(--delete-remote-branches)
+    fi
+    if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
+      echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
+      echo "[agent-branch-finish] You can run manual cleanup: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches" >&2
+    fi
+  fi
 
-if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-  if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" --base "$BASE_BRANCH"; then
-    echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
-    echo "[agent-branch-finish] You can run manual cleanup: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH}" >&2
+  echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and cleaned source branch/worktree."
+  if [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* ]]; then
+    echo "[agent-branch-finish] Current worktree '${source_worktree}' still exists because it is the active shell cwd." >&2
+    echo "[agent-branch-finish] Leave this directory, then run: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches" >&2
+  fi
+else
+  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
+    if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" --base "$BASE_BRANCH"; then
+      echo "[agent-branch-finish] Warning: temporary worktree prune failed." >&2
+    fi
   fi
-fi
 
-echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and removed branch."
-if [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
-  echo "[agent-branch-finish] Current worktree '${source_worktree}' still exists because it is the active shell cwd." >&2
-  echo "[agent-branch-finish] Leave this directory, then run: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH}" >&2
+  echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and kept source branch/worktree."
+  echo "[agent-branch-finish] Cleanup later with: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches --delete-remote-branches"
 fi

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

@@ -152,6 +152,36 @@ is_protected_branch_name() {
   return 1
 }
 
+hydrate_local_helper_in_worktree() {
+  local repo="$1"
+  local worktree="$2"
+  local relative_path="$3"
+  local worktree_target="${worktree}/${relative_path}"
+  local source_path=""
+
+  if [[ -e "$worktree_target" ]]; then
+    return 0
+  fi
+
+  if [[ -f "${repo}/${relative_path}" ]]; then
+    source_path="${repo}/${relative_path}"
+  elif [[ -f "${repo}/templates/${relative_path}" ]]; then
+    source_path="${repo}/templates/${relative_path}"
+  fi
+
+  if [[ -z "$source_path" ]]; then
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$worktree_target")"
+  cp "$source_path" "$worktree_target"
+  if [[ -x "$source_path" ]]; then
+    chmod +x "$worktree_target"
+  fi
+
+  echo "[agent-branch-start] Hydrated local helper in worktree: ${relative_path}"
+}
+
 if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   echo "[agent-branch-start] Not inside a git repository." >&2
   exit 1
@@ -195,15 +225,17 @@ snapshot_name="$(resolve_active_codex_snapshot_name)"
 snapshot_slug="$(sanitize_slug "$snapshot_name" "")"
 timestamp="$(date +%Y%m%d-%H%M%S)"
 if [[ -n "$snapshot_slug" ]]; then
-  branch_name="agent/${agent_slug}/${timestamp}-${snapshot_slug}-${task_slug}"
+  branch_name_base="agent/${agent_slug}/${snapshot_slug}-${task_slug}"
 else
-  branch_name="agent/${agent_slug}/${timestamp}-${task_slug}"
+  branch_name_base="agent/${agent_slug}/${task_slug}"
 fi
 
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  echo "[agent-branch-start] Branch already exists: ${branch_name}" >&2
-  exit 1
-fi
+branch_name="$branch_name_base"
+branch_suffix=2
+while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
+  branch_name="${branch_name_base}-${branch_suffix}"
+  branch_suffix=$((branch_suffix + 1))
+done
 
 if [[ "$WORKTREE_MODE" -eq 0 ]]; then
   if [[ "$ALLOW_IN_PLACE" -ne 1 ]]; then
@@ -280,6 +312,8 @@ if [[ -n "$auto_transfer_stash_ref" ]]; then
   fi
 fi
 
+hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh"
+
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
 echo "[agent-branch-start] Next steps:"

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

@@ -5,6 +5,9 @@ BASE_BRANCH="${MUSAFETY_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 DRY_RUN=0
 FORCE_DIRTY=0
+DELETE_BRANCHES=0
+DELETE_REMOTE_BRANCHES=0
+TARGET_BRANCH=""
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -25,9 +28,21 @@ while [[ $# -gt 0 ]]; do
       FORCE_DIRTY=1
       shift
       ;;
+    --delete-branches)
+      DELETE_BRANCHES=1
+      shift
+      ;;
+    --delete-remote-branches)
+      DELETE_REMOTE_BRANCHES=1
+      shift
+      ;;
+    --branch)
+      TARGET_BRANCH="${2:-}"
+      shift 2
+      ;;
     *)
       echo "[agent-worktree-prune] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--branch <agent/...>]" >&2
       exit 1
       ;;
   esac
@@ -73,6 +88,11 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   exit 1
 fi
 
+if [[ -n "$TARGET_BRANCH" && "$TARGET_BRANCH" != agent/* ]]; then
+  echo "[agent-worktree-prune] --branch must reference an agent/* branch: ${TARGET_BRANCH}" >&2
+  exit 1
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   BASE_BRANCH="$(resolve_base_branch)"
 fi
@@ -124,6 +144,10 @@ process_entry() {
     branch="${branch_ref#refs/heads/}"
   fi
 
+  if [[ -n "$TARGET_BRANCH" && "$branch" != "$TARGET_BRANCH" ]]; then
+    return
+  fi
+
   if [[ "$wt" == "$current_pwd" ]]; then
     skipped_active=$((skipped_active + 1))
     echo "[agent-worktree-prune] Skipping active cwd worktree: ${wt}"
@@ -138,7 +162,9 @@ process_entry() {
     remove_reason="missing-branch"
   elif [[ "$branch" == agent/* ]]; then
     if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
-      remove_reason="merged-agent-branch"
+      if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
+        remove_reason="merged-agent-branch"
+      fi
     fi
   elif [[ "$branch" == __agent_integrate_* || "$branch" == __source-probe-* ]]; then
     remove_reason="temporary-worktree"
@@ -163,10 +189,16 @@ process_entry() {
   fi
 
   if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}" && ! branch_has_worktree "$branch"; then
-    if [[ "$branch" == agent/* ]]; then
+    if [[ "$branch" == agent/* && "$DELETE_BRANCHES" -eq 1 ]]; then
       if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
         echo "[agent-worktree-prune] Deleted merged 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}"
+          fi
+        fi
       fi
     elif [[ "$branch" == __agent_integrate_* || "$branch" == __source-probe-* ]]; then
       run_cmd git -C "$repo_root" branch -D "$branch" >/dev/null 2>&1 || true
@@ -199,18 +231,29 @@ done < <(git -C "$repo_root" worktree list --porcelain)
 
 process_entry "$current_wt" "$current_branch_ref"
 
-while IFS= read -r branch; do
-  [[ -z "$branch" ]] && continue
-  if branch_has_worktree "$branch"; then
-    continue
-  fi
-  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
-      removed_branches=$((removed_branches + 1))
-      echo "[agent-worktree-prune] Deleted stale merged branch: ${branch}"
+if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
+  while IFS= read -r branch; do
+    [[ -z "$branch" ]] && continue
+    if [[ -n "$TARGET_BRANCH" && "$branch" != "$TARGET_BRANCH" ]]; then
+      continue
     fi
-  fi
-done < <(git -C "$repo_root" for-each-ref --format='%(refname:short)' refs/heads/agent)
+    if branch_has_worktree "$branch"; then
+      continue
+    fi
+    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
+        removed_branches=$((removed_branches + 1))
+        echo "[agent-worktree-prune] Deleted stale merged 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}"
+          fi
+        fi
+      fi
+    fi
+  done < <(git -C "$repo_root" for-each-ref --format='%(refname:short)' refs/heads/agent)
+fi
 
 run_cmd git -C "$repo_root" worktree prune