@imdeadpool/guardex 5.0.5 → 5.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.5",
+  "version": "5.0.8",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -28,7 +28,8 @@
     "agent:safety:setup": "gx setup",
     "agent:safety:scan": "gx scan",
     "agent:safety:fix": "gx fix",
-    "agent:safety:doctor": "gx doctor"
+    "agent:safety:doctor": "gx doctor",
+    "agent:review:watch": "bash ./scripts/review-bot-watch.sh"
   },
   "engines": {
     "node": ">=18"

package/templates/AGENTS.multiagent-safety.md

@@ -10,6 +10,7 @@
 - Before deleting/replacing code, each agent must read the latest session comments/handoffs first and confirm the target code is in their owned scope.
 - 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>"`.
+- In-place branch mode is disallowed: never switch the active local/base checkout to an agent branch.
 - Treat the base branch (`main` or the user's current local base branch) as read-only while the agent branch is active.
 - 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.
@@ -17,7 +18,8 @@
 - 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.
+- For every new task, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch; otherwise create a fresh one from the current local base snapshot with `scripts/agent-branch-start.sh`.
+- Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 - 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/githooks/pre-commit

@@ -24,10 +24,23 @@ if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}"
 fi
 
 is_vscode_git_context=0
-if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" || "${TERM_PROGRAM:-}" == "vscode" ]]; then
+if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" ]]; then
   is_vscode_git_context=1
 fi
 
+allow_vscode_protected_raw="${MUSAFETY_ALLOW_VSCODE_PROTECTED_BRANCH_WRITES:-$(git config --get multiagent.allowVscodeProtectedBranchWrites || true)}"
+if [[ -z "$allow_vscode_protected_raw" ]]; then
+  allow_vscode_protected_raw="true"
+fi
+allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
+
+allow_vscode_protected_branch_writes=0
+case "$allow_vscode_protected" in
+  1|true|yes|on) allow_vscode_protected_branch_writes=1 ;;
+  0|false|no|off) allow_vscode_protected_branch_writes=0 ;;
+  *) allow_vscode_protected_branch_writes=0 ;;
+esac
+
 protected_branches_raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
 if [[ -z "$protected_branches_raw" ]]; then
   protected_branches_raw="dev main master"
@@ -42,6 +55,15 @@ for protected_branch in $protected_branches_raw; do
   fi
 done
 
+is_local_only_branch=0
+if [[ "$is_protected_branch" == "1" ]]; then
+  upstream_ref="$(git for-each-ref --format='%(upstream:short)' "refs/heads/${branch}" | head -n 1)"
+  remote_branch_ref="$(git for-each-ref --format='%(refname:short)' "refs/remotes/*/${branch}" | head -n 1)"
+  if [[ -z "$upstream_ref" && -z "$remote_branch_ref" ]]; then
+    is_local_only_branch=1
+  fi
+fi
+
 codex_require_agent_branch_raw="${MUSAFETY_CODEX_REQUIRE_AGENT_BRANCH:-$(git config --get multiagent.codexRequireAgentBranch || true)}"
 if [[ -z "$codex_require_agent_branch_raw" ]]; then
   codex_require_agent_branch_raw="true"
@@ -112,7 +134,9 @@ fi
 
 if [[ "$is_protected_branch" == "1" ]]; then
   if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
-    exit 0
+    if [[ "$allow_vscode_protected_branch_writes" == "1" || "$is_local_only_branch" == "1" ]]; then
+      exit 0
+    fi
   fi
 
   if [[ "$is_unborn_branch" == "1" && "$is_codex_session" != "1" ]]; then
@@ -131,6 +155,12 @@ Use an agent branch first:
 After finishing work:
   bash scripts/agent-branch-finish.sh
 
+Optional repo hard-block for VS Code protected-branch commits:
+  git config multiagent.allowVscodeProtectedBranchWrites false
+
+VS Code Source Control commits on protected local-only branches
+(no upstream and no remote branch) are allowed automatically.
+
 Temporary bypass (not recommended):
   ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
 MSG

package/templates/githooks/pre-push

@@ -10,6 +10,19 @@ if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n
   is_vscode_git_context=1
 fi
 
+allow_vscode_protected_raw="${MUSAFETY_ALLOW_VSCODE_PROTECTED_BRANCH_WRITES:-$(git config --get multiagent.allowVscodeProtectedBranchWrites || true)}"
+if [[ -z "$allow_vscode_protected_raw" ]]; then
+  allow_vscode_protected_raw="true"
+fi
+allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
+
+allow_vscode_protected_branch_writes=0
+case "$allow_vscode_protected" in
+  1|true|yes|on) allow_vscode_protected_branch_writes=1 ;;
+  0|false|no|off) allow_vscode_protected_branch_writes=0 ;;
+  *) allow_vscode_protected_branch_writes=0 ;;
+esac
+
 is_codex_session=0
 if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}" == "1" ]]; then
   is_codex_session=1
@@ -56,14 +69,16 @@ if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
     exit 1
   fi
 
-  if [[ "$is_vscode_git_context" == "1" ]]; then
+  if [[ "$is_vscode_git_context" == "1" && "$allow_vscode_protected_branch_writes" == "1" ]]; then
     exit 0
   fi
 
   {
-    echo "[agent-branch-guard] Push to protected branch blocked outside VS Code Git context."
+    echo "[agent-branch-guard] Push to protected branch blocked."
     echo "[agent-branch-guard] Protected target(s): ${blocked_refs[*]}"
-    echo "[agent-branch-guard] Use VS Code Source Control for protected-branch push, or push from an agent branch and merge via PR."
+    echo "[agent-branch-guard] Use an agent branch and merge via PR."
+    echo "[agent-branch-guard] Optional repo hard-block for VS Code protected-branch push:"
+    echo "  git config multiagent.allowVscodeProtectedBranchWrites false"
     echo
     echo "Temporary bypass (not recommended):"
     echo "  ALLOW_PUSH_ON_PROTECTED_BRANCH=1 git push ..."

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

@@ -545,7 +545,7 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
   fi
 
   if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-    prune_args=(--base "$BASE_BRANCH" --delete-branches)
+    prune_args=(--base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
     if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
       prune_args+=(--delete-remote-branches)
     fi

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

@@ -5,8 +5,6 @@ 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=()
 
@@ -25,13 +23,10 @@ while [[ $# -gt 0 ]]; do
       BASE_BRANCH_EXPLICIT=1
       shift 2
       ;;
-    --in-place)
-      WORKTREE_MODE=0
-      shift
-      ;;
-    --allow-in-place)
-      ALLOW_IN_PLACE=1
-      shift
+    --in-place|--allow-in-place)
+      echo "[agent-branch-start] In-place branch mode is disabled." >&2
+      echo "[agent-branch-start] This command always creates an isolated worktree to keep your active checkout unchanged." >&2
+      exit 1
       ;;
     --worktree-root)
       WORKTREE_ROOT_REL="${2:-.omx/agent-worktrees}"
@@ -47,7 +42,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     -*)
       echo "[agent-branch-start] Unknown option: $1" >&2
-      echo "Usage: $0 [task] [agent] [base] [--in-place --allow-in-place] [--worktree-root <path>]" >&2
+      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&2
       exit 1
       ;;
     *)
@@ -59,7 +54,7 @@ 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
+  echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&2
   exit 1
 fi
 
@@ -237,34 +232,6 @@ while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
   branch_suffix=$((branch_suffix + 1))
 done
 
-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//\//__}"

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

@@ -7,6 +7,7 @@ DRY_RUN=0
 FORCE_DIRTY=0
 DELETE_BRANCHES=0
 DELETE_REMOTE_BRANCHES=0
+ONLY_DIRTY_WORKTREES=0
 TARGET_BRANCH=""
 
 if [[ -n "$BASE_BRANCH" ]]; then
@@ -36,13 +37,17 @@ while [[ $# -gt 0 ]]; do
       DELETE_REMOTE_BRANCHES=1
       shift
       ;;
+    --only-dirty-worktrees)
+      ONLY_DIRTY_WORKTREES=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] [--delete-branches] [--delete-remote-branches] [--branch <agent/...>]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>]" >&2
       exit 1
       ;;
   esac
@@ -56,6 +61,11 @@ 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_base_branch() {
   local configured=""
@@ -127,11 +137,98 @@ is_clean_worktree() {
     && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
 }
 
+resolve_worktree_common_dir() {
+  local wt="$1"
+  local common_dir=""
+  common_dir="$(git -C "$wt" rev-parse --git-common-dir 2>/dev/null || true)"
+  if [[ -z "$common_dir" ]]; then
+    return 1
+  fi
+  if [[ "$common_dir" == /* ]]; then
+    common_dir="$(cd "$common_dir" 2>/dev/null && pwd -P || true)"
+  else
+    common_dir="$(cd "$wt/$common_dir" 2>/dev/null && pwd -P || true)"
+  fi
+  if [[ -z "$common_dir" ]]; then
+    return 1
+  fi
+  printf '%s' "$common_dir"
+}
+
+select_unique_worktree_path() {
+  local root="$1"
+  local name="$2"
+  local candidate="${root}/${name}"
+  local suffix=2
+  while [[ -e "$candidate" ]]; do
+    candidate="${root}/${name}-${suffix}"
+    suffix=$((suffix + 1))
+  done
+  printf '%s' "$candidate"
+}
+
+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
+
+    if [[ "$entry_common_dir" == "$repo_common_dir" ]]; then
+      continue
+    fi
+
+    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
+
+    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 [[ "$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
+
+    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
+}
+
 removed_worktrees=0
 removed_branches=0
 skipped_active=0
 skipped_dirty=0
 
+relocate_foreign_worktree_entries
+
 process_entry() {
   local wt="$1"
   local branch_ref="$2"
@@ -165,6 +262,8 @@ process_entry() {
       if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
         remove_reason="merged-agent-branch"
       fi
+    elif [[ "$ONLY_DIRTY_WORKTREES" -eq 1 ]] && is_clean_worktree "$wt"; then
+      remove_reason="clean-agent-worktree"
     fi
   elif [[ "$branch" == __agent_integrate_* || "$branch" == __source-probe-* ]]; then
     remove_reason="temporary-worktree"
@@ -258,6 +357,9 @@ fi
 run_cmd git -C "$repo_root" worktree prune
 
 echo "[agent-worktree-prune] Summary: base=${BASE_BRANCH}, removed_worktrees=${removed_worktrees}, removed_branches=${removed_branches}, skipped_active=${skipped_active}, skipped_dirty=${skipped_dirty}"
+if [[ "$relocated_foreign" -gt 0 || "$skipped_foreign" -gt 0 ]]; then
+  echo "[agent-worktree-prune] Foreign routing: relocated=${relocated_foreign}, skipped=${skipped_foreign}"
+fi
 if [[ "$skipped_active" -gt 0 ]]; then
   echo "[agent-worktree-prune] Tip: leave active agent worktree directories, then run this command again for full cleanup." >&2
 fi

package/templates/scripts/codex-agent.sh

@@ -125,6 +125,106 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
 fi
 repo_root="$(git rev-parse --show-toplevel)"
 
+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_start_base_branch() {
+  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -n "$BASE_BRANCH" ]]; then
+    printf '%s' "$BASE_BRANCH"
+    return 0
+  fi
+
+  local configured_base
+  configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
+  if [[ -n "$configured_base" ]]; then
+    printf '%s' "$configured_base"
+    return 0
+  fi
+
+  local current_branch
+  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
+    printf '%s' "$current_branch"
+    return 0
+  fi
+
+  printf 'dev'
+}
+
+resolve_start_ref() {
+  local base_branch="$1"
+  git -C "$repo_root" fetch origin "$base_branch" --quiet >/dev/null 2>&1 || true
+  if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${base_branch}"; then
+    printf 'origin/%s' "$base_branch"
+    return 0
+  fi
+  if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${base_branch}"; then
+    printf '%s' "$base_branch"
+    return 0
+  fi
+  return 1
+}
+
+restore_repo_branch_if_changed() {
+  local expected_branch="$1"
+  if [[ -z "$expected_branch" || "$expected_branch" == "HEAD" ]]; then
+    return 0
+  fi
+  local current_branch
+  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  if [[ -z "$current_branch" || "$current_branch" == "$expected_branch" ]]; then
+    return 0
+  fi
+  git -C "$repo_root" checkout "$expected_branch" >/dev/null 2>&1
+}
+
+start_sandbox_fallback() {
+  local base_branch start_ref timestamp task_slug agent_slug branch_name_base branch_name suffix
+  local worktree_root worktree_path
+
+  base_branch="$(resolve_start_base_branch)"
+  if ! start_ref="$(resolve_start_ref "$base_branch")"; then
+    echo "[codex-agent] Unable to resolve base ref for fallback sandbox start: ${base_branch}" >&2
+    return 1
+  fi
+
+  timestamp="$(date +%Y%m%d-%H%M%S)"
+  task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+  agent_slug="$(sanitize_slug "$AGENT_NAME" "agent")"
+  branch_name_base="agent/${agent_slug}/${timestamp}-${task_slug}"
+  branch_name="$branch_name_base"
+  suffix=2
+  while git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch_name}"; do
+    branch_name="${branch_name_base}-${suffix}"
+    suffix=$((suffix + 1))
+  done
+
+  worktree_root="${repo_root}/.omx/agent-worktrees"
+  mkdir -p "$worktree_root"
+  worktree_path="${worktree_root}/${branch_name//\//__}"
+  if [[ -e "$worktree_path" ]]; then
+    echo "[codex-agent] Fallback worktree path already exists: $worktree_path" >&2
+    return 1
+  fi
+
+  git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref" >/dev/null
+  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
+
+  printf '[agent-branch-start] Created branch: %s\n' "$branch_name"
+  printf '[agent-branch-start] Worktree: %s\n' "$worktree_path"
+}
+
 if [[ ! -x "${repo_root}/scripts/agent-branch-start.sh" ]]; then
   echo "[codex-agent] Missing scripts/agent-branch-start.sh. Run: gx setup" >&2
   exit 1
@@ -135,12 +235,53 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
   start_args+=("$BASE_BRANCH")
 fi
 
-start_output="$(bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}")"
-printf '%s\n' "$start_output"
+initial_repo_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+start_output=""
+start_status=0
+set +e
+start_output="$(bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
+start_status=$?
+set -e
 
 worktree_path="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | tail -n1)"
+current_repo_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+resolved_repo_root="$(cd "$repo_root" && pwd -P)"
+resolved_worktree_path=""
+if [[ -n "$worktree_path" && -d "$worktree_path" ]]; then
+  resolved_worktree_path="$(cd "$worktree_path" && pwd -P)"
+fi
+
+fallback_reason=""
+if [[ "$start_status" -ne 0 ]]; then
+  fallback_reason="starter exited with status ${start_status}"
+elif [[ -z "$worktree_path" ]]; then
+  fallback_reason="starter did not report worktree path"
+elif [[ -n "$resolved_worktree_path" && "$resolved_worktree_path" == "$resolved_repo_root" ]]; then
+  fallback_reason="starter pointed to active checkout path"
+elif [[ -n "$initial_repo_branch" && -n "$current_repo_branch" && "$current_repo_branch" != "$initial_repo_branch" ]]; then
+  fallback_reason="starter switched active checkout branch"
+fi
+
+if [[ -n "$fallback_reason" ]]; then
+  if ! restore_repo_branch_if_changed "$initial_repo_branch"; then
+    echo "[codex-agent] agent-branch-start changed the active checkout branch and restore failed." >&2
+    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and 'gx doctor --target ${repo_root}', then retry." >&2
+    exit 1
+  fi
+  if [[ -n "$start_output" ]]; then
+    printf '%s\n' "$start_output" >&2
+  fi
+  echo "[codex-agent] Unsafe starter output (${fallback_reason}); creating sandbox worktree directly." >&2
+  start_output="$(start_sandbox_fallback)"
+  printf '%s\n' "$start_output"
+  worktree_path="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | tail -n1)"
+else
+  printf '%s\n' "$start_output"
+fi
+
 if [[ -z "$worktree_path" ]]; then
-  echo "[codex-agent] Could not determine sandbox worktree path from agent-branch-start output." >&2
+  echo "[codex-agent] Could not determine sandbox worktree path from sandbox startup output." >&2
+  echo "[codex-agent] Run 'gx setup --target ${repo_root}' and 'gx doctor --target ${repo_root}', then retry." >&2
   exit 1
 fi
 
@@ -285,13 +426,84 @@ auto_commit_worktree_changes() {
 
   local default_message="Auto-finish: ${TASK_NAME}"
   local commit_message="${MUSAFETY_CODEX_AUTO_COMMIT_MESSAGE:-$default_message}"
+  local commit_output=""
+
+  if commit_output="$(git -C "$wt" commit -m "$commit_message" 2>&1)"; then
+    echo "[codex-agent] Auto-committed sandbox changes on '${branch}'."
+    return 0
+  fi
+
+  if auto_sync_for_commit_retry "$wt" "$branch"; then
+    claim_changed_files "$wt" "$branch"
+    git -C "$wt" add -A
+    if commit_output="$(git -C "$wt" commit -m "$commit_message" 2>&1)"; then
+      echo "[codex-agent] Auto-committed sandbox changes on '${branch}' after sync retry."
+      return 0
+    fi
+  fi
+
+  echo "[codex-agent] Auto-commit failed in sandbox. Keeping branch for manual review: $branch" >&2
+  if [[ -n "$commit_output" ]]; then
+    printf '%s\n' "$commit_output" >&2
+  fi
+  return 1
+}
+
+auto_sync_for_commit_retry() {
+  local wt="$1"
+  local branch="$2"
+
+  if ! has_origin_remote; then
+    return 1
+  fi
+
+  local base_branch
+  base_branch="$(resolve_worktree_base_branch "$wt")"
+  if [[ -z "$base_branch" ]]; then
+    return 1
+  fi
 
-  if ! git -C "$wt" commit -m "$commit_message" >/dev/null 2>&1; then
-    echo "[codex-agent] Auto-commit failed in sandbox. Keeping branch for manual review: $branch" >&2
+  if ! git -C "$wt" fetch origin "$base_branch" --quiet; then
+    return 1
+  fi
+
+  if ! git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/${base_branch}"; then
     return 1
   fi
 
-  echo "[codex-agent] Auto-committed sandbox changes on '${branch}'."
+  local behind_count
+  behind_count="$(git -C "$wt" rev-list --left-right --count "HEAD...origin/${base_branch}" 2>/dev/null | awk '{print $2}')"
+  behind_count="${behind_count:-0}"
+  if [[ "$behind_count" -le 0 ]]; then
+    return 1
+  fi
+
+  echo "[codex-agent] Auto-commit retry: '${branch}' is behind origin/${base_branch} by ${behind_count} commit(s). Syncing and retrying..."
+
+  local stash_ref=""
+  local stash_output=""
+  if worktree_has_changes "$wt"; then
+    if ! stash_output="$(git -C "$wt" stash push --include-untracked -m "codex-agent-autocommit-sync-${branch}-$(date +%s)" 2>&1)"; then
+      return 1
+    fi
+    stash_ref="$(printf '%s\n' "$stash_output" | grep -o 'stash@{[0-9]\+}' | head -n 1 || true)"
+  fi
+
+  if ! git -C "$wt" rebase "origin/${base_branch}" >/dev/null 2>&1; then
+    git -C "$wt" rebase --abort >/dev/null 2>&1 || true
+    if [[ -n "$stash_ref" ]]; then
+      git -C "$wt" stash pop "$stash_ref" >/dev/null 2>&1 || true
+    fi
+    return 1
+  fi
+
+  if [[ -n "$stash_ref" ]]; then
+    if ! git -C "$wt" stash pop "$stash_ref" >/dev/null 2>&1; then
+      echo "[codex-agent] Auto-commit retry could not re-apply local changes after sync. Manual resolution required in: $wt" >&2
+      return 1
+    fi
+  fi
+
   return 0
 }
 
@@ -419,7 +631,7 @@ if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
     prune_args+=(--base "$BASE_BRANCH")
   fi
   if [[ "$AUTO_CLEANUP" -eq 1 && "$auto_finish_completed" -eq 1 ]]; then
-    prune_args+=(--delete-branches --delete-remote-branches)
+    prune_args+=(--only-dirty-worktrees --delete-branches --delete-remote-branches)
   fi
   if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
     echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2