@imdeadpool/guardex 5.0.7 → 5.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.7",
+  "version": "5.0.9",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,

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.
@@ -44,9 +45,17 @@
 - Verification commands + results
 - Risks / follow-ups
 
-## OpenSpec Plan Workspace (recommended)
+## OpenSpec Plan Workspace (required for agent sub-branch changes)
 
-When work needs a durable planning phase, scaffold a plan workspace before implementation:
+OMX Codex execution flows must use OpenSpec. `scripts/codex-agent.sh` bootstraps a
+per-branch plan workspace automatically under:
+
+```text
+openspec/plan/<agent-branch-slug>/
+```
+
+For manual `scripts/agent-branch-start.sh` usage, enable auto-bootstrap with
+`MUSAFETY_OPENSPEC_AUTO_INIT=true` or scaffold manually before implementation:
 
 ```bash
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"

package/templates/githooks/pre-commit

@@ -24,13 +24,13 @@ 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="false"
+  allow_vscode_protected_raw="true"
 fi
 allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
 
@@ -55,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"
@@ -124,8 +133,10 @@ MSG
 fi
 
 if [[ "$is_protected_branch" == "1" ]]; then
-  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" && "$allow_vscode_protected_branch_writes" == "1" ]]; then
-    exit 0
+  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
+    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
@@ -144,8 +155,11 @@ Use an agent branch first:
 After finishing work:
   bash scripts/agent-branch-finish.sh
 
-Optional repo override for manual VS Code protected-branch commits:
-  git config multiagent.allowVscodeProtectedBranchWrites true
+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 ...

package/templates/githooks/pre-push

@@ -12,7 +12,7 @@ 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="false"
+  allow_vscode_protected_raw="true"
 fi
 allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
 
@@ -77,8 +77,8 @@ if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
     echo "[agent-branch-guard] Push to protected branch blocked."
     echo "[agent-branch-guard] Protected target(s): ${blocked_refs[*]}"
     echo "[agent-branch-guard] Use an agent branch and merge via PR."
-    echo "[agent-branch-guard] Optional VS Code override:"
-    echo "  git config multiagent.allowVscodeProtectedBranchWrites true"
+    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

@@ -338,7 +338,7 @@ is_local_branch_delete_error() {
 
 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)"
+  state_line="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json state,mergedAt,url --jq '[.state, (.mergedAt // ""), (.url // "")] | join("\u001f")' 2>/dev/null || true)"
   if [[ -z "$state_line" ]]; then
     return 1
   fi
@@ -346,7 +346,7 @@ read_pr_state() {
   local parsed_state=""
   local parsed_merged_at=""
   local parsed_url=""
-  IFS=$'\t' read -r parsed_state parsed_merged_at parsed_url <<< "$state_line"
+  IFS=$'\x1f' 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

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

@@ -5,9 +5,9 @@ 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"
+OPENSPEC_AUTO_INIT_RAW="${MUSAFETY_OPENSPEC_AUTO_INIT:-false}"
+OPENSPEC_PLAN_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_PLAN_SLUG:-}"
 POSITIONAL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -25,13 +25,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 +44,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 +56,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
 
@@ -87,6 +84,31 @@ sanitize_slug() {
   printf '%s' "$slug"
 }
 
+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
+}
+
+OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
+
+resolve_openspec_plan_slug() {
+  local branch_name="$1"
+  local task_slug="$2"
+  if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "${branch_name//\//-}" "$task_slug"
+}
+
 resolve_active_codex_snapshot_name() {
   local override="${MUSAFETY_CODEX_AUTH_SNAPSHOT:-}"
   if [[ -n "$override" ]]; then
@@ -119,17 +141,6 @@ has_local_changes() {
   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
@@ -182,6 +193,43 @@ hydrate_local_helper_in_worktree() {
   echo "[agent-branch-start] Hydrated local helper in worktree: ${relative_path}"
 }
 
+initialize_openspec_plan_workspace() {
+  local repo="$1"
+  local worktree="$2"
+  local plan_slug="$3"
+
+  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh"
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+    return 0
+  fi
+
+  local openspec_script="${worktree}/scripts/openspec/init-plan-workspace.sh"
+  if [[ ! -f "$openspec_script" ]]; then
+    echo "[agent-branch-start] OpenSpec init script is missing in sandbox worktree." >&2
+    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
+    return 1
+  fi
+  if [[ ! -x "$openspec_script" ]]; then
+    chmod +x "$openspec_script" 2>/dev/null || true
+  fi
+
+  local init_output=""
+  if ! init_output="$(
+    cd "$worktree"
+    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+  )"; then
+    printf '%s\n' "$init_output" >&2
+    echo "[agent-branch-start] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
+    return 1
+  fi
+
+  if [[ -n "$init_output" ]]; then
+    printf '%s\n' "$init_output"
+  fi
+  echo "[agent-branch-start] OpenSpec plan workspace: ${worktree}/openspec/plan/${plan_slug}"
+}
+
 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,12 +243,15 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
 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"
+  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  protected_branches_raw="$(resolve_protected_branches "$repo_root")"
+  if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
+    BASE_BRANCH="$current_branch"
   else
-    current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-    if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
+    configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
+    if [[ -n "$configured_base" ]]; then
+      BASE_BRANCH="$configured_base"
+    elif [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
       BASE_BRANCH="$current_branch"
     else
       BASE_BRANCH="dev"
@@ -237,37 +288,10 @@ 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//\//__}"
+openspec_plan_slug="$(resolve_openspec_plan_slug "$branch_name" "$task_slug")"
 
 if [[ -e "$worktree_path" ]]; then
   echo "[agent-branch-start] Worktree path already exists: ${worktree_path}" >&2
@@ -276,10 +300,11 @@ fi
 
 auto_transfer_stash_ref=""
 auto_transfer_message=""
+auto_transfer_source_branch=""
 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
+if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
+  if has_local_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="$(
@@ -287,7 +312,8 @@ if [[ "$current_branch" == "$BASE_BRANCH" ]] && is_protected_branch_name "$BASE_
           | 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}'..."
+        auto_transfer_source_branch="$current_branch"
+        echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}'..."
       fi
     fi
   fi
@@ -303,19 +329,25 @@ 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}'."
+    transfer_label="${auto_transfer_source_branch:-$BASE_BRANCH}"
+    echo "[agent-branch-start] Moved local changes from '${transfer_label}' 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
+    transfer_label="${auto_transfer_source_branch:-$BASE_BRANCH}"
+    echo "[agent-branch-start] Changes are preserved in ${auto_transfer_stash_ref} on ${transfer_label}." >&2
     echo "[agent-branch-start] Apply manually with: git -C \"$worktree_path\" stash apply \"${auto_transfer_stash_ref}\"" >&2
     exit 1
   fi
 fi
 
 hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh"
+if ! initialize_openspec_plan_workspace "$repo_root" "$worktree_path" "$openspec_plan_slug"; then
+  exit 1
+fi
 
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
+echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
 echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
 echo "  python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" <file...>"

package/templates/scripts/codex-agent.sh

@@ -10,6 +10,8 @@ AUTO_FINISH_RAW="${MUSAFETY_CODEX_AUTO_FINISH:-true}"
 AUTO_REVIEW_ON_CONFLICT_RAW="${MUSAFETY_CODEX_AUTO_REVIEW_ON_CONFLICT:-true}"
 AUTO_CLEANUP_RAW="${MUSAFETY_CODEX_AUTO_CLEANUP:-true}"
 AUTO_WAIT_FOR_MERGE_RAW="${MUSAFETY_CODEX_WAIT_FOR_MERGE:-true}"
+OPENSPEC_AUTO_INIT_RAW="${MUSAFETY_OPENSPEC_AUTO_INIT:-true}"
+OPENSPEC_PLAN_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_PLAN_SLUG:-}"
 
 normalize_bool() {
   local raw="${1:-}"
@@ -28,6 +30,7 @@ AUTO_FINISH="$(normalize_bool "$AUTO_FINISH_RAW" "1")"
 AUTO_REVIEW_ON_CONFLICT="$(normalize_bool "$AUTO_REVIEW_ON_CONFLICT_RAW" "1")"
 AUTO_CLEANUP="$(normalize_bool "$AUTO_CLEANUP_RAW" "1")"
 AUTO_WAIT_FOR_MERGE="$(normalize_bool "$AUTO_WAIT_FOR_MERGE_RAW" "1")"
+OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -125,6 +128,146 @@ 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_openspec_plan_slug() {
+  local branch_name="$1"
+  local task_slug
+  task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+  if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "${branch_name//\//-}" "$task_slug"
+}
+
+hydrate_local_helper_in_worktree() {
+  local worktree="$1"
+  local relative_path="$2"
+  local worktree_target="${worktree}/${relative_path}"
+  local source_path=""
+
+  if [[ -e "$worktree_target" ]]; then
+    return 0
+  fi
+
+  if [[ -f "${repo_root}/${relative_path}" ]]; then
+    source_path="${repo_root}/${relative_path}"
+  elif [[ -f "${repo_root}/templates/${relative_path}" ]]; then
+    source_path="${repo_root}/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 "[codex-agent] Hydrated local helper in sandbox: ${relative_path}"
+}
+
+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 +278,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="$(MUSAFETY_OPENSPEC_AUTO_INIT=0 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
 
@@ -222,6 +406,43 @@ sync_worktree_with_base() {
   return 0
 }
 
+ensure_openspec_plan_workspace() {
+  local wt="$1"
+  local branch="$2"
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+    return 0
+  fi
+
+  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-plan-workspace.sh"
+
+  local openspec_script="${wt}/scripts/openspec/init-plan-workspace.sh"
+  if [[ ! -f "$openspec_script" ]]; then
+    echo "[codex-agent] Missing OpenSpec init script in sandbox: ${openspec_script}" >&2
+    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
+    return 1
+  fi
+  if [[ ! -x "$openspec_script" ]]; then
+    chmod +x "$openspec_script" 2>/dev/null || true
+  fi
+
+  local plan_slug
+  plan_slug="$(resolve_openspec_plan_slug "$branch")"
+  local init_output=""
+  if ! init_output="$(
+    cd "$wt"
+    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+  )"; then
+    printf '%s\n' "$init_output" >&2
+    echo "[codex-agent] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
+    return 1
+  fi
+  if [[ -n "$init_output" ]]; then
+    printf '%s\n' "$init_output"
+  fi
+  echo "[codex-agent] OpenSpec plan workspace: ${wt}/openspec/plan/${plan_slug}"
+}
+
 worktree_has_changes() {
   local wt="$1"
   if ! git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json"; then
@@ -438,6 +659,16 @@ if ! sync_worktree_with_base "$worktree_path"; then
   exit 1
 fi
 
+worktree_branch="$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ -z "$worktree_branch" || "$worktree_branch" == "HEAD" ]]; then
+  echo "[codex-agent] Could not determine sandbox branch for worktree: $worktree_path" >&2
+  exit 1
+fi
+
+if ! ensure_openspec_plan_workspace "$worktree_path" "$worktree_branch"; then
+  exit 1
+fi
+
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
@@ -449,8 +680,6 @@ cd "$repo_root"
 final_exit="$codex_exit"
 auto_finish_completed=0
 
-worktree_branch="$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-
 if [[ "$AUTO_FINISH" -eq 1 && -n "$worktree_branch" && "$worktree_branch" != "HEAD" ]]; then
   if [[ "$AUTO_WAIT_FOR_MERGE" -eq 1 && "$AUTO_CLEANUP" -eq 1 ]]; then
     echo "[codex-agent] Auto-finish enabled: commit -> push/PR -> wait for merge -> cleanup."