@imdeadpool/guardex 5.0.8 → 5.0.11

package/package.json

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

package/templates/AGENTS.multiagent-safety.md

@@ -1,5 +1,5 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Execution Contract (multiagent-safety)
+## Multi-Agent Execution Contract (GX)
 
 0. Session plan comment + read gate (required)
 
@@ -13,6 +13,7 @@
 - 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).
+- OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR for those changes (via `codex-agent` or `agent-branch-finish`).
 - 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.
@@ -45,9 +46,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/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

@@ -6,6 +6,8 @@ AGENT_NAME="agent"
 BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=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
@@ -82,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
@@ -114,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
@@ -177,6 +193,63 @@ hydrate_local_helper_in_worktree() {
   echo "[agent-branch-start] Hydrated local helper in worktree: ${relative_path}"
 }
 
+hydrate_dependency_dir_symlink_in_worktree() {
+  local repo="$1"
+  local worktree="$2"
+  local relative_path="$3"
+  local source_path="${repo}/${relative_path}"
+  local target_path="${worktree}/${relative_path}"
+
+  if [[ ! -d "$source_path" ]]; then
+    return 0
+  fi
+
+  if [[ -e "$target_path" ]]; then
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$target_path")"
+  ln -s "$source_path" "$target_path"
+  echo "[agent-branch-start] Linked dependency dir 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
@@ -190,12 +263,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"
@@ -235,6 +311,7 @@ done
 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
@@ -243,10 +320,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="$(
@@ -254,7 +332,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
@@ -270,19 +349,28 @@ 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"
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "node_modules"
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/frontend/node_modules"
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/backend/node_modules"
+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/agent-worktree-prune.sh

@@ -9,6 +9,10 @@ DELETE_BRANCHES=0
 DELETE_REMOTE_BRANCHES=0
 ONLY_DIRTY_WORKTREES=0
 TARGET_BRANCH=""
+IDLE_MINUTES=0
+NOW_EPOCH_RAW="${MUSAFETY_PRUNE_NOW_EPOCH:-}"
+IDLE_SECONDS=0
+NOW_EPOCH=0
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -45,9 +49,13 @@ while [[ $# -gt 0 ]]; do
       TARGET_BRANCH="${2:-}"
       shift 2
       ;;
+    --idle-minutes)
+      IDLE_MINUTES="${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] [--only-dirty-worktrees] [--branch <agent/...>]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>] [--idle-minutes <minutes>]" >&2
       exit 1
       ;;
   esac
@@ -103,6 +111,16 @@ if [[ -n "$TARGET_BRANCH" && "$TARGET_BRANCH" != agent/* ]]; then
   exit 1
 fi
 
+if [[ ! "$IDLE_MINUTES" =~ ^[0-9]+$ ]]; then
+  echo "[agent-worktree-prune] --idle-minutes must be an integer >= 0." >&2
+  exit 1
+fi
+
+if [[ -n "$NOW_EPOCH_RAW" && ! "$NOW_EPOCH_RAW" =~ ^[0-9]+$ ]]; then
+  echo "[agent-worktree-prune] MUSAFETY_PRUNE_NOW_EPOCH must be a unix timestamp integer." >&2
+  exit 1
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   BASE_BRANCH="$(resolve_base_branch)"
 fi
@@ -117,6 +135,13 @@ if ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${BASE_BRANCH}";
   exit 1
 fi
 
+IDLE_SECONDS=$((IDLE_MINUTES * 60))
+if [[ -n "$NOW_EPOCH_RAW" ]]; then
+  NOW_EPOCH="$NOW_EPOCH_RAW"
+else
+  NOW_EPOCH="$(date +%s)"
+fi
+
 run_cmd() {
   if [[ "$DRY_RUN" -eq 1 ]]; then
     echo "[agent-worktree-prune] [dry-run] $*"
@@ -167,6 +192,71 @@ select_unique_worktree_path() {
   printf '%s' "$candidate"
 }
 
+read_branch_activity_epoch() {
+  local branch="$1"
+  local wt="${2:-}"
+  local activity_epoch=""
+
+  activity_epoch="$(
+    git -C "$repo_root" reflog show --format='%ct' -n 1 "refs/heads/${branch}" 2>/dev/null \
+      | head -n 1 \
+      | tr -d '[:space:]'
+  )"
+  if [[ -z "$activity_epoch" ]]; then
+    activity_epoch="$(
+      git -C "$repo_root" log -1 --format='%ct' "$branch" 2>/dev/null \
+        | head -n 1 \
+        | tr -d '[:space:]'
+    )"
+  fi
+
+  if [[ -n "$wt" && -d "$wt" ]]; then
+    local lock_file="${wt}/.omx/state/agent-file-locks.json"
+    if [[ -f "$lock_file" ]]; then
+      local lock_mtime=""
+      lock_mtime="$(stat -c %Y "$lock_file" 2>/dev/null || stat -f %m "$lock_file" 2>/dev/null || true)"
+      if [[ "$lock_mtime" =~ ^[0-9]+$ ]]; then
+        if [[ -z "$activity_epoch" || "$lock_mtime" -gt "$activity_epoch" ]]; then
+          activity_epoch="$lock_mtime"
+        fi
+      fi
+    fi
+  fi
+
+  printf '%s' "$activity_epoch"
+}
+
+skipped_recent=0
+
+branch_idle_gate() {
+  local branch="$1"
+  local wt="$2"
+  local reason="$3"
+  if [[ "$IDLE_SECONDS" -le 0 ]]; then
+    return 0
+  fi
+  if [[ -z "$branch" ]]; then
+    return 0
+  fi
+
+  local last_activity_epoch=""
+  last_activity_epoch="$(read_branch_activity_epoch "$branch" "$wt")"
+  if [[ ! "$last_activity_epoch" =~ ^[0-9]+$ ]]; then
+    return 0
+  fi
+
+  local idle_age=$((NOW_EPOCH - last_activity_epoch))
+  if [[ "$idle_age" -lt 0 ]]; then
+    idle_age=0
+  fi
+  if [[ "$idle_age" -lt "$IDLE_SECONDS" ]]; then
+    skipped_recent=$((skipped_recent + 1))
+    echo "[agent-worktree-prune] Skipping recent branch (${reason}): ${branch} (idle=${idle_age}s < ${IDLE_SECONDS}s)"
+    return 1
+  fi
+  return 0
+}
+
 relocated_foreign=0
 skipped_foreign=0
 
@@ -273,6 +363,10 @@ process_entry() {
     return
   fi
 
+  if ! branch_idle_gate "$branch" "$wt" "$remove_reason"; then
+    return
+  fi
+
   if [[ "$FORCE_DIRTY" -ne 1 ]] && ! is_clean_worktree "$wt"; then
     skipped_dirty=$((skipped_dirty + 1))
     echo "[agent-worktree-prune] Skipping dirty worktree (${remove_reason}): ${wt}"
@@ -339,6 +433,9 @@ if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
     if branch_has_worktree "$branch"; then
       continue
     fi
+    if ! branch_idle_gate "$branch" "" "stale-merged-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))
@@ -356,7 +453,7 @@ 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}"
+echo "[agent-worktree-prune] Summary: base=${BASE_BRANCH}, idle_minutes=${IDLE_MINUTES}, removed_worktrees=${removed_worktrees}, removed_branches=${removed_branches}, skipped_active=${skipped_active}, skipped_dirty=${skipped_dirty}, skipped_recent=${skipped_recent}"
 if [[ "$relocated_foreign" -gt 0 || "$skipped_foreign" -gt 0 ]]; then
   echo "[agent-worktree-prune] Foreign routing: relocated=${relocated_foreign}, skipped=${skipped_foreign}"
 fi
@@ -366,3 +463,6 @@ fi
 if [[ "$skipped_dirty" -gt 0 ]]; then
   echo "[agent-worktree-prune] Tip: dirty worktrees were preserved. Clean/finish them first, or pass --force-dirty to remove anyway." >&2
 fi
+if [[ "$IDLE_SECONDS" -gt 0 && "$skipped_recent" -gt 0 ]]; then
+  echo "[agent-worktree-prune] Tip: recent branches were preserved by --idle-minutes=${IDLE_MINUTES}. Re-run later or lower the threshold." >&2
+fi

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
@@ -136,6 +139,46 @@ sanitize_slug() {
   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"
@@ -239,7 +282,7 @@ initial_repo_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/nu
 start_output=""
 start_status=0
 set +e
-start_output="$(bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
+start_output="$(MUSAFETY_OPENSPEC_AUTO_INIT=0 bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
 start_status=$?
 set -e
 
@@ -363,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
@@ -579,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
@@ -590,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."