@imdeadpool/guardex 5.0.0

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

@@ -0,0 +1,389 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_BRANCH=""
+BASE_BRANCH_EXPLICIT=0
+SOURCE_BRANCH=""
+PUSH_ENABLED=1
+DELETE_REMOTE_BRANCH=1
+MERGE_MODE="auto"
+GH_BIN="${MUSAFETY_GH_BIN:-gh}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      BASE_BRANCH="${2:-}"
+      BASE_BRANCH_EXPLICIT=1
+      shift 2
+      ;;
+    --branch)
+      SOURCE_BRANCH="${2:-}"
+      shift 2
+      ;;
+    --no-push)
+      PUSH_ENABLED=0
+      shift
+      ;;
+    --keep-remote-branch)
+      DELETE_REMOTE_BRANCH=0
+      shift
+      ;;
+    --mode)
+      MERGE_MODE="${2:-auto}"
+      shift 2
+      ;;
+    --via-pr)
+      MERGE_MODE="pr"
+      shift
+      ;;
+    --direct-only)
+      MERGE_MODE="direct"
+      shift
+      ;;
+    *)
+      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
+      exit 1
+      ;;
+  esac
+done
+
+case "$MERGE_MODE" in
+  auto|direct|pr) ;;
+  *)
+    echo "[agent-branch-finish] Invalid --mode value: ${MERGE_MODE} (expected auto|direct|pr)" >&2
+    exit 1
+    ;;
+esac
+
+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)"
+current_worktree="$(pwd -P)"
+
+if [[ -z "$SOURCE_BRANCH" ]]; then
+  SOURCE_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+fi
+
+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"
+  fi
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  branch_stored_base="$(git -C "$repo_root" config --get "branch.${SOURCE_BRANCH}.musafetyBase" || true)"
+  if [[ -n "$branch_stored_base" ]]; then
+    BASE_BRANCH="$branch_stored_base"
+  fi
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  source_upstream="$(git -C "$repo_root" for-each-ref --format='%(upstream:short)' "refs/heads/${SOURCE_BRANCH}" | head -n 1)"
+  source_upstream="${source_upstream:-}"
+  if [[ "$source_upstream" == */* ]]; then
+    BASE_BRANCH="${source_upstream#*/}"
+  fi
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  if [[ -n "$current_branch" && "$current_branch" != "HEAD" && "$current_branch" != "$SOURCE_BRANCH" ]]; then
+    BASE_BRANCH="$current_branch"
+  fi
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  BASE_BRANCH="dev"
+fi
+
+if [[ "$SOURCE_BRANCH" == "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-finish] Source branch and base branch are both '$BASE_BRANCH'." >&2
+  echo "[agent-branch-finish] Switch to your agent branch or pass --branch <agent-branch>." >&2
+  exit 1
+fi
+
+if ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${SOURCE_BRANCH}"; then
+  echo "[agent-branch-finish] Local source branch does not exist: ${SOURCE_BRANCH}" >&2
+  exit 1
+fi
+
+get_worktree_for_branch() {
+  local branch="$1"
+  git -C "$repo_root" worktree list --porcelain | awk -v target="refs/heads/${branch}" '
+    $1 == "worktree" { wt = $2 }
+    $1 == "branch" && $2 == target { print wt; exit }
+  '
+}
+
+is_clean_worktree() {
+  local wt="$1"
+  git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
+    && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json"
+}
+
+source_worktree="$(get_worktree_for_branch "$SOURCE_BRANCH")"
+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)"
+  mkdir -p "$(dirname "$source_probe_path")"
+  git -C "$repo_root" worktree add "$source_probe_path" "$SOURCE_BRANCH" >/dev/null
+  source_worktree="$source_probe_path"
+  created_source_probe=1
+fi
+
+if ! is_clean_worktree "$source_worktree"; then
+  echo "[agent-branch-finish] Source worktree is not clean for '${SOURCE_BRANCH}': ${source_worktree}" >&2
+  echo "[agent-branch-finish] Commit/stash changes on the source branch before finishing." >&2
+  exit 1
+fi
+
+start_ref="$BASE_BRANCH"
+if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git -C "$repo_root" fetch origin "$BASE_BRANCH" --quiet
+  start_ref="origin/${BASE_BRANCH}"
+fi
+
+require_before_finish_raw="$(git -C "$repo_root" config --get multiagent.sync.requireBeforeFinish || true)"
+if [[ -z "$require_before_finish_raw" ]]; then
+  require_before_finish_raw="true"
+fi
+require_before_finish="$(printf '%s' "$require_before_finish_raw" | tr '[:upper:]' '[:lower:]')"
+should_require_sync=0
+case "$require_before_finish" in
+  1|true|yes|on) should_require_sync=1 ;;
+  0|false|no|off) should_require_sync=0 ;;
+  *) should_require_sync=1 ;;
+esac
+
+if [[ "$should_require_sync" -eq 1 ]] && git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  behind_count="$(git -C "$repo_root" rev-list --left-right --count "${SOURCE_BRANCH}...origin/${BASE_BRANCH}" 2>/dev/null | awk '{print $2}')"
+  behind_count="${behind_count:-0}"
+  if [[ "$behind_count" -gt 0 ]]; then
+    echo "[agent-sync-guard] Branch '${SOURCE_BRANCH}' is behind origin/${BASE_BRANCH} by ${behind_count} commit(s)." >&2
+    echo "[agent-sync-guard] Auto-syncing '${SOURCE_BRANCH}' onto origin/${BASE_BRANCH} before finish..." >&2
+    if ! git -C "$source_worktree" rebase "origin/${BASE_BRANCH}"; then
+      git_dir="$(git -C "$source_worktree" rev-parse --git-dir)"
+      rebase_active=0
+      if [[ -e "${git_dir}/rebase-merge" || -e "${git_dir}/rebase-apply" ]]; then
+        rebase_active=1
+      fi
+
+      echo "[agent-sync-guard] Auto-sync failed while rebasing '${SOURCE_BRANCH}' onto origin/${BASE_BRANCH}." >&2
+      if [[ "$rebase_active" -eq 1 ]]; then
+        echo "[agent-sync-guard] Resolve conflicts, then run: git -C \"$source_worktree\" rebase --continue" >&2
+        echo "[agent-sync-guard] Or abort: git -C \"$source_worktree\" rebase --abort" >&2
+      fi
+      exit 1
+    fi
+
+    behind_after="$(git -C "$repo_root" rev-list --left-right --count "${SOURCE_BRANCH}...origin/${BASE_BRANCH}" 2>/dev/null | awk '{print $2}')"
+    behind_after="${behind_after:-0}"
+    echo "[agent-sync-guard] Auto-sync complete (behind now: ${behind_after})." >&2
+  fi
+fi
+
+integration_worktree="${repo_root}/.omx/agent-worktrees/__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")"
+
+git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
+git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+
+cleanup() {
+  if [[ -d "$integration_worktree" ]]; then
+    git -C "$repo_root" worktree remove "$integration_worktree" --force >/dev/null 2>&1 || true
+  fi
+  if [[ "$created_source_probe" -eq 1 && -n "$source_probe_path" && -d "$source_probe_path" ]]; then
+    git -C "$repo_root" worktree remove "$source_probe_path" --force >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
+
+if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git -C "$source_worktree" fetch origin "$BASE_BRANCH" --quiet
+
+  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
+      done <<< "$conflict_files"
+    fi
+    echo "[agent-branch-finish] Rebase/merge '${BASE_BRANCH}' into '${SOURCE_BRANCH}' and resolve conflicts before finishing." >&2
+    exit 1
+  fi
+
+  git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
+fi
+
+if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+  echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+  git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
+  exit 1
+fi
+
+merge_completed=1
+merge_status="direct"
+direct_push_error=""
+pr_url=""
+
+is_local_branch_delete_error() {
+  local output="$1"
+  if [[ "$output" != *"failed to delete local branch"* ]]; then
+    return 1
+  fi
+  if [[ "$output" == *"cannot delete branch"* ]] || [[ "$output" == *"used by worktree"* ]]; then
+    return 0
+  fi
+  return 1
+}
+
+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
+    return 1
+  fi
+
+  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)"
+  if [[ -z "$pr_title" ]]; then
+    pr_title="Merge ${SOURCE_BRANCH} into ${BASE_BRANCH}"
+  fi
+  pr_body="Automated by scripts/agent-branch-finish.sh (PR flow)."
+
+  "$GH_BIN" pr create \
+    --base "$BASE_BRANCH" \
+    --head "$SOURCE_BRANCH" \
+    --title "$pr_title" \
+    --body "$pr_body" >/dev/null 2>&1 || true
+
+  pr_url="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json url --jq '.url' 2>/dev/null || true)"
+
+  merge_output=""
+  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
+
+  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
+    return 2
+  fi
+
+  if [[ -n "$merge_output" ]]; then
+    echo "[agent-branch-finish] PR merge not completed yet; leaving PR open." >&2
+    echo "${merge_output}" >&2
+  fi
+  if [[ -n "$auto_output" ]]; then
+    echo "${auto_output}" >&2
+  fi
+  return 2
+}
+
+if [[ "$PUSH_ENABLED" -eq 1 ]]; then
+  if [[ "$MERGE_MODE" != "pr" ]]; then
+    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
+    fi
+  else
+    merge_completed=0
+  fi
+
+  if [[ "$merge_completed" -eq 0 ]]; then
+    if [[ "$MERGE_MODE" == "direct" ]]; then
+      echo "[agent-branch-finish] Direct push/merge failed in --direct-only mode." >&2
+      if [[ -n "$direct_push_error" ]]; then
+        echo "$direct_push_error" >&2
+      fi
+      exit 1
+    fi
+
+    if run_pr_flow; then
+      merge_completed=1
+      merge_status="pr"
+    else
+      pr_exit=$?
+      if [[ "$pr_exit" -eq 2 ]]; then
+        echo "[agent-branch-finish] PR flow created/updated branch '${SOURCE_BRANCH}' against '${BASE_BRANCH}'." >&2
+        if [[ -n "$pr_url" ]]; then
+          echo "[agent-branch-finish] PR: ${pr_url}" >&2
+        fi
+        echo "[agent-branch-finish] Merge pending review/check policy. Branch cleanup skipped for now." >&2
+        exit 0
+      fi
+      echo "[agent-branch-finish] PR flow failed." >&2
+      if [[ -n "$direct_push_error" ]]; then
+        echo "[agent-branch-finish] Direct push failure details:" >&2
+        echo "$direct_push_error" >&2
+      fi
+      exit 1
+    fi
+  fi
+fi
+
+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
+    fi
+  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
+
+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"
+  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
+  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
+  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
+fi

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

@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TASK_NAME="task"
+AGENT_NAME="agent"
+BASE_BRANCH=""
+BASE_BRANCH_EXPLICIT=0
+WORKTREE_MODE=1
+ALLOW_IN_PLACE=0
+WORKTREE_ROOT_REL=".omx/agent-worktrees"
+POSITIONAL_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --task)
+      TASK_NAME="${2:-task}"
+      shift 2
+      ;;
+    --agent)
+      AGENT_NAME="${2:-agent}"
+      shift 2
+      ;;
+    --base)
+      BASE_BRANCH="${2:-}"
+      BASE_BRANCH_EXPLICIT=1
+      shift 2
+      ;;
+    --in-place)
+      WORKTREE_MODE=0
+      shift
+      ;;
+    --allow-in-place)
+      ALLOW_IN_PLACE=1
+      shift
+      ;;
+    --worktree-root)
+      WORKTREE_ROOT_REL="${2:-.omx/agent-worktrees}"
+      shift 2
+      ;;
+    --)
+      shift
+      while [[ $# -gt 0 ]]; do
+        POSITIONAL_ARGS+=("$1")
+        shift
+      done
+      break
+      ;;
+    -*)
+      echo "[agent-branch-start] Unknown option: $1" >&2
+      echo "Usage: $0 [task] [agent] [base] [--in-place --allow-in-place] [--worktree-root <path>]" >&2
+      exit 1
+      ;;
+    *)
+      POSITIONAL_ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "${#POSITIONAL_ARGS[@]}" -gt 3 ]]; then
+  echo "[agent-branch-start] Too many positional arguments." >&2
+  echo "Usage: $0 [task] [agent] [base] [--in-place --allow-in-place] [--worktree-root <path>]" >&2
+  exit 1
+fi
+
+if [[ "${#POSITIONAL_ARGS[@]}" -ge 1 ]]; then
+  TASK_NAME="${POSITIONAL_ARGS[0]}"
+fi
+
+if [[ "${#POSITIONAL_ARGS[@]}" -ge 2 ]]; then
+  AGENT_NAME="${POSITIONAL_ARGS[1]}"
+fi
+
+if [[ "${#POSITIONAL_ARGS[@]}" -ge 3 ]]; then
+  BASE_BRANCH="${POSITIONAL_ARGS[2]}"
+  BASE_BRANCH_EXPLICIT=1
+fi
+
+sanitize_slug() {
+  local raw="$1"
+  local fallback="${2:-task}"
+  local slug
+  slug="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  if [[ -z "$slug" ]]; then
+    slug="$fallback"
+  fi
+  printf '%s' "$slug"
+}
+
+resolve_active_codex_snapshot_name() {
+  local override="${MUSAFETY_CODEX_AUTH_SNAPSHOT:-}"
+  if [[ -n "$override" ]]; then
+    printf '%s' "$override"
+    return 0
+  fi
+
+  local codex_auth_bin="${MUSAFETY_CODEX_AUTH_BIN:-codex-auth}"
+  if ! command -v "$codex_auth_bin" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  "$codex_auth_bin" list 2>/dev/null \
+    | sed -n 's/^[[:space:]]*\*[[:space:]]\+//p' \
+    | head -n 1 \
+    | tr -d '\r' || true
+}
+
+has_local_changes() {
+  local root="$1"
+  if ! git -C "$root" diff --quiet; then
+    return 0
+  fi
+  if ! git -C "$root" diff --cached --quiet; then
+    return 0
+  fi
+  if [[ -n "$(git -C "$root" ls-files --others --exclude-standard)" ]]; then
+    return 0
+  fi
+  return 1
+}
+
+has_tracked_changes() {
+  local root="$1"
+  if ! git -C "$root" diff --quiet; then
+    return 0
+  fi
+  if ! git -C "$root" diff --cached --quiet; then
+    return 0
+  fi
+  return 1
+}
+
+resolve_protected_branches() {
+  local root="$1"
+  local raw
+  raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git -C "$root" config --get multiagent.protectedBranches || true)}"
+  if [[ -z "$raw" ]]; then
+    raw="dev main master"
+  fi
+  raw="${raw//,/ }"
+  printf '%s' "$raw"
+}
+
+is_protected_branch_name() {
+  local branch="$1"
+  local protected_raw="$2"
+  for protected_branch in $protected_raw; do
+    if [[ "$branch" == "$protected_branch" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+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
+fi
+
+repo_root="$(git rev-parse --show-toplevel)"
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-start] --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"
+  else
+    current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+    if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
+      BASE_BRANCH="$current_branch"
+    else
+      BASE_BRANCH="dev"
+    fi
+  fi
+fi
+
+if git show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git fetch origin "${BASE_BRANCH}" --quiet
+  start_ref="origin/${BASE_BRANCH}"
+else
+  if ! git show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
+    echo "[agent-branch-start] Base branch not found locally or on origin: ${BASE_BRANCH}" >&2
+    exit 1
+  fi
+  start_ref="${BASE_BRANCH}"
+fi
+
+task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+agent_slug="$(sanitize_slug "$AGENT_NAME" "agent")"
+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}"
+else
+  branch_name="agent/${agent_slug}/${timestamp}-${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
+
+if [[ "$WORKTREE_MODE" -eq 0 ]]; then
+  if [[ "$ALLOW_IN_PLACE" -ne 1 ]]; then
+    echo "[agent-branch-start] --in-place is blocked by default to prevent accidental edits on protected branches." >&2
+    echo "[agent-branch-start] If you really need it, pass both: --in-place --allow-in-place" >&2
+    exit 1
+  fi
+
+  if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "[agent-branch-start] Working tree is not clean. Commit/stash changes before starting an in-place branch." >&2
+    exit 1
+  fi
+
+  current_branch="$(git rev-parse --abbrev-ref HEAD)"
+  if [[ "$current_branch" != "$BASE_BRANCH" ]]; then
+    git checkout "$BASE_BRANCH"
+  fi
+
+  if git show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+    git pull --ff-only origin "$BASE_BRANCH"
+  fi
+
+  git checkout -b "$branch_name"
+  git -C "$repo_root" config "branch.${branch_name}.musafetyBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
+  echo "[agent-branch-start] Created in-place branch: ${branch_name}"
+  echo "$branch_name"
+  exit 0
+fi
+
+worktree_root="${repo_root}/${WORKTREE_ROOT_REL}"
+mkdir -p "$worktree_root"
+worktree_path="${worktree_root}/${branch_name//\//__}"
+
+if [[ -e "$worktree_path" ]]; then
+  echo "[agent-branch-start] Worktree path already exists: ${worktree_path}" >&2
+  exit 1
+fi
+
+auto_transfer_stash_ref=""
+auto_transfer_message=""
+current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+protected_branches_raw="$(resolve_protected_branches "$repo_root")"
+if [[ "$current_branch" == "$BASE_BRANCH" ]] && is_protected_branch_name "$BASE_BRANCH" "$protected_branches_raw"; then
+  if has_tracked_changes "$repo_root"; then
+    auto_transfer_message="musafety-auto-transfer-${timestamp}-${agent_slug}-${task_slug}"
+    if git -C "$repo_root" stash push --include-untracked --message "$auto_transfer_message" >/dev/null 2>&1; then
+      auto_transfer_stash_ref="$(
+        git -C "$repo_root" stash list \
+          | awk -v msg="$auto_transfer_message" '$0 ~ msg { ref=$1; sub(/:$/, "", ref); print ref; exit }'
+      )"
+      if [[ -n "$auto_transfer_stash_ref" ]]; then
+        echo "[agent-branch-start] Detected local changes on protected base '${BASE_BRANCH}'. Moving them to '${branch_name}'..."
+      fi
+    fi
+  fi
+fi
+
+git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref"
+git -C "$repo_root" config "branch.${branch_name}.musafetyBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
+
+if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git -C "$worktree_path" branch --set-upstream-to="origin/${BASE_BRANCH}" "$branch_name" >/dev/null 2>&1 || true
+fi
+
+if [[ -n "$auto_transfer_stash_ref" ]]; then
+  if git -C "$worktree_path" stash apply "$auto_transfer_stash_ref" >/dev/null 2>&1; then
+    git -C "$repo_root" stash drop "$auto_transfer_stash_ref" >/dev/null 2>&1 || true
+    echo "[agent-branch-start] Moved local changes from '${BASE_BRANCH}' into '${branch_name}'."
+  else
+    echo "[agent-branch-start] Failed to auto-apply moved changes in new worktree." >&2
+    echo "[agent-branch-start] Changes are preserved in ${auto_transfer_stash_ref} on ${BASE_BRANCH}." >&2
+    echo "[agent-branch-start] Apply manually with: git -C \"$worktree_path\" stash apply \"${auto_transfer_stash_ref}\"" >&2
+    exit 1
+  fi
+fi
+
+echo "[agent-branch-start] Created branch: ${branch_name}"
+echo "[agent-branch-start] Worktree: ${worktree_path}"
+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}\""