@imdeadpool/guardex 7.0.41 → 7.0.43

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

@@ -9,13 +9,16 @@ WORKTREE_ROOT_REL=""
 WORKTREE_ROOT_EXPLICIT=0
 NODE_BIN="${GUARDEX_NODE_BIN:-node}"
 CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
-OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
+OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-true}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
 OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 OPENSPEC_TIER_RAW="${GUARDEX_OPENSPEC_TIER:-T3}"
 REUSE_EXISTING_RAW="${GUARDEX_BRANCH_START_REUSE_EXISTING:-true}"
+AUTO_TRANSFER_ENABLED_RAW="${GUARDEX_AUTO_TRANSFER:-true}"
+AUTO_TRANSFER_EXCLUDE_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+AUTO_TRANSFER_EXCLUDE_RAW="${GUARDEX_AUTO_TRANSFER_EXCLUDE-$AUTO_TRANSFER_EXCLUDE_DEFAULT}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
@@ -67,6 +70,18 @@ while [[ $# -gt 0 ]]; do
       REUSE_EXISTING_RAW="false"
       shift
       ;;
+    --no-transfer)
+      AUTO_TRANSFER_ENABLED_RAW="false"
+      shift
+      ;;
+    --transfer)
+      AUTO_TRANSFER_ENABLED_RAW="true"
+      shift
+      ;;
+    --transfer-exclude)
+      AUTO_TRANSFER_EXCLUDE_RAW="${2:-}"
+      shift 2
+      ;;
     --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
@@ -389,11 +404,27 @@ print_reused_agent_worktree() {
   echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
   echo "[agent-branch-start] OpenSpec change: existing worktree"
   echo "[agent-branch-start] OpenSpec plan: existing worktree"
-  echo "[agent-branch-start] Next steps:"
-  echo "  cd \"${worktree_path}\""
-  echo "  gx locks claim --branch \"${branch_name}\" <file...>"
-  echo "  # continue work in this existing sandbox"
-  echo "  gx branch finish --branch \"${branch_name}\" --via-pr --wait-for-merge"
+  print_agent_next_steps "$branch_name" "$worktree_path" "continue work in this existing sandbox" "$BASE_BRANCH"
+}
+
+print_agent_next_steps() {
+  local branch_name="$1"
+  local worktree_path="$2"
+  local work_step="$3"
+  local base_branch="${4:-main}"
+
+  if [[ -z "$base_branch" ]]; then
+    base_branch="main"
+  fi
+
+  echo "[agent-branch-start] Ready:"
+  echo "  branch:   ${branch_name}"
+  echo "  worktree: ${worktree_path}"
+  echo "  next:"
+  echo "    cd \"${worktree_path}\""
+  echo "    gx locks claim --branch \"${branch_name}\" <file...>"
+  echo "    # ${work_step}"
+  echo "    gx branch finish --branch \"${branch_name}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
 }
 
 has_local_changes() {
@@ -419,7 +450,7 @@ meaningful_slug_tokens() {
     | awk '
       length($0) < 4 { next }
       $0 ~ /^[0-9]+$/ { next }
-      $0 ~ /^(agent|agents|branch|codex|claude|continue|dirty|existing|fix|from|implement|make|matching|reuse|start|task|that|this|update|with|worktree|worktrees)$/ { next }
+      $0 ~ /^(agent|agents|branch|codex|claude|continue|dirty|existing|fix|from|implement|make|matching|openspec|reuse|start|task|that|this|update|with|worktree|worktrees)$/ { next }
       !seen[$0]++ { print }
     '
 }
@@ -774,18 +805,54 @@ restore_auto_transfer_stash_on_failure() {
 
 trap 'restore_auto_transfer_stash_on_failure "$?"' EXIT
 
+auto_transfer_enabled_lc="$(printf '%s' "$AUTO_TRANSFER_ENABLED_RAW" | tr '[:upper:]' '[:lower:]')"
+case "$auto_transfer_enabled_lc" in
+  0|false|no|off) AUTO_TRANSFER_ENABLED=0 ;;
+  *) AUTO_TRANSFER_ENABLED=1 ;;
+esac
+
+build_auto_transfer_stash_argv() {
+  # Emit NUL-separated argv: --include-untracked --message <msg> [-- :/ :(exclude,glob)PAT ...]
+  local msg="$1"
+  printf '%s\0' --include-untracked --message "$msg"
+  if [[ -z "${AUTO_TRANSFER_EXCLUDE_RAW:-}" ]]; then
+    return 0
+  fi
+  printf '%s\0' '--' ':/'
+  local -a patterns=()
+  IFS=':' read -ra patterns <<< "$AUTO_TRANSFER_EXCLUDE_RAW"
+  local pattern
+  for pattern in "${patterns[@]}"; do
+    [[ -z "$pattern" ]] && continue
+    printf '%s\0' ":(exclude,glob)${pattern}"
+  done
+}
+
 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
   if has_local_changes "$repo_root"; then
-    auto_transfer_message="guardex-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="$(resolve_stash_ref_by_message "$repo_root" "$auto_transfer_message")"
-      if [[ -n "$auto_transfer_stash_ref" ]]; then
-        auto_transfer_source_branch="$current_branch"
-        echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}'..."
-        if ! maybe_fail_after_auto_transfer_stash; then
-          exit 1
+    if [[ "$AUTO_TRANSFER_ENABLED" -eq 0 ]]; then
+      echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'; --no-transfer set, leaving them in place." >&2
+      echo "[agent-branch-start] If you intended those changes for '${branch_name}', stash them manually and apply inside the worktree." >&2
+    else
+      auto_transfer_message="guardex-auto-transfer-${timestamp}-${agent_slug}-${task_slug}"
+      stash_argv=()
+      while IFS= read -r -d '' arg; do
+        stash_argv+=("$arg")
+      done < <(build_auto_transfer_stash_argv "$auto_transfer_message")
+      if git -C "$repo_root" stash push "${stash_argv[@]}" >/dev/null 2>&1; then
+        auto_transfer_stash_ref="$(resolve_stash_ref_by_message "$repo_root" "$auto_transfer_message")"
+        if [[ -n "$auto_transfer_stash_ref" ]]; then
+          auto_transfer_source_branch="$current_branch"
+          echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}' (state-file globs excluded)..."
+          if ! maybe_fail_after_auto_transfer_stash; then
+            exit 1
+          fi
+        else
+          if has_local_changes "$repo_root"; then
+            echo "[agent-branch-start] Local changes on '${current_branch}' all match the auto-transfer exclude list; leaving them in place on '${current_branch}'." >&2
+          fi
         fi
       fi
     fi
@@ -832,18 +899,18 @@ fi
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
 echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
-if [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
+if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  echo "[agent-branch-start] OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)"
+elif [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
   echo "[agent-branch-start] OpenSpec change: skipped by tier ${OPENSPEC_TIER}"
 else
   echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
 fi
-if [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
+if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  echo "[agent-branch-start] OpenSpec plan: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)"
+elif [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
   echo "[agent-branch-start] OpenSpec plan: skipped by tier ${OPENSPEC_TIER}"
 else
   echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
 fi
-echo "[agent-branch-start] Next steps:"
-echo "  cd \"${worktree_path}\""
-echo "  gx locks claim --branch \"${branch_name}\" <file...>"
-echo "  # implement + commit"
-echo "  gx branch finish --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"
+print_agent_next_steps "$branch_name" "$worktree_path" "implement + commit" "$BASE_BRANCH"

package/templates/scripts/agent-preflight.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Pre-flight verification gate for gitguardex-managed projects.
+#
+# Runs in the agent's worktree from `gx branch finish` BEFORE the push
+# happens. Returns non-zero to refuse the push so a broken commit
+# never reaches the PR / CI / merge funnel.
+#
+# Auto-detects the project's stack and runs conventional verification:
+#   - Node/pnpm:   pnpm typecheck && pnpm lint && pnpm test (each only
+#                  if the script exists in package.json)
+#   - Node/npm:    npm test (only if defined)
+#   - Rust:        cargo check
+#   - Python:      ruff check (only if ruff is installed)
+#
+# Override per-project by replacing this file (delete the symlink under
+# scripts/agent-preflight.sh and write your own).
+#
+# Skip a single run with `gx branch finish --no-preflight`.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+ran=0
+fail=0
+run_step() {
+  local label="$1"
+  shift
+  echo "[agent-preflight] -> $label"
+  if "$@"; then
+    ran=$((ran + 1))
+    echo "[agent-preflight]    ok"
+  else
+    echo "[agent-preflight] FAIL: $label" >&2
+    fail=1
+  fi
+}
+
+has_package_script() {
+  local script_name="$1"
+  [[ -f package.json ]] || return 1
+  grep -E "\"${script_name}\"\\s*:" package.json >/dev/null 2>&1
+}
+
+# Node detection
+if [[ -f package.json ]]; then
+  pkg_manager=""
+  if command -v pnpm >/dev/null 2>&1 && [[ -f pnpm-lock.yaml ]]; then
+    pkg_manager="pnpm"
+  elif command -v npm >/dev/null 2>&1 && [[ -f package-lock.json ]]; then
+    pkg_manager="npm"
+  fi
+
+  case "$pkg_manager" in
+    pnpm)
+      has_package_script typecheck && run_step "pnpm typecheck" pnpm typecheck
+      has_package_script lint && run_step "pnpm lint" pnpm lint
+      has_package_script test && run_step "pnpm test" pnpm test
+      ;;
+    npm)
+      has_package_script test && run_step "npm test" npm test
+      ;;
+  esac
+fi
+
+# Rust detection
+if [[ -f Cargo.toml ]] && command -v cargo >/dev/null 2>&1; then
+  run_step "cargo check" cargo check --quiet
+fi
+
+# Python detection (ruff if available; pytest is too project-specific to default)
+if [[ -f pyproject.toml ]] && command -v ruff >/dev/null 2>&1; then
+  run_step "ruff check" ruff check .
+fi
+
+if [[ "$ran" -eq 0 ]]; then
+  echo "[agent-preflight] No recognized project stack detected; skipping checks." >&2
+  exit 0
+fi
+
+if [[ "$fail" -ne 0 ]]; then
+  echo "[agent-preflight] Verification failed; refusing push." >&2
+  echo "[agent-preflight] Fix the issues, or re-run with: gx branch finish --no-preflight ..." >&2
+  exit 1
+fi
+
+echo "[agent-preflight] ${ran} step(s) passed."
+exit 0

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

@@ -82,7 +82,12 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
 fi
 
 repo_root="$(git rev-parse --show-toplevel)"
-current_pwd="$(pwd -P)"
+current_pwd="${GUARDEX_PRUNE_ACTIVE_CWD:-$(pwd -P)}"
+if [[ -d "$current_pwd" ]]; then
+  current_pwd="$(cd "$current_pwd" && pwd -P)"
+else
+  current_pwd=""
+fi
 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 } }'
@@ -244,11 +249,71 @@ branch_has_worktree() {
   git -C "$repo_root" worktree list --porcelain | grep -q "^branch refs/heads/${branch}$"
 }
 
+# Globs treated as agent state, not real work. Worktrees whose only "dirty"
+# content matches these are considered clean for prune purposes. Mirrors the
+# auto-transfer + auto-resolve allowlist from PRs #546/#547 (state-file globs
+# never carry authoritative content out of an agent branch).
+WORKTREE_STATE_EXCLUDE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+WORKTREE_STATE_EXCLUDE_GLOBS_RAW="${GUARDEX_PRUNE_STATE_EXCLUDE_GLOBS-$WORKTREE_STATE_EXCLUDE_GLOBS_DEFAULT}"
+
+build_state_exclude_pathspec_args() {
+  # Emit one ':(exclude,glob)<pat>' arg per non-empty pattern.
+  if [[ -z "$WORKTREE_STATE_EXCLUDE_GLOBS_RAW" ]]; then
+    return 0
+  fi
+  local -a globs=()
+  IFS=':' read -ra globs <<< "$WORKTREE_STATE_EXCLUDE_GLOBS_RAW"
+  local pattern
+  for pattern in "${globs[@]}"; do
+    [[ -z "$pattern" ]] && continue
+    printf '%s\0' ":(exclude,glob)${pattern}"
+  done
+}
+
+# Capture the state-exclude pathspecs once; reused by is_clean_worktree and
+# the dirt-summary logger below.
+STATE_EXCLUDE_PATHSPEC_ARGS=()
+while IFS= read -r -d '' arg; do
+  STATE_EXCLUDE_PATHSPEC_ARGS+=("$arg")
+done < <(build_state_exclude_pathspec_args)
+
 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" \
-    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
+  git -C "$wt" diff --quiet -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" \
+    && git -C "$wt" diff --cached --quiet -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" \
+    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}")" ]]
+}
+
+# Returns a short, human-readable summary of why a worktree is considered dirty:
+# up to 3 modified-tracked paths + up to 3 untracked paths + a "(+N more)" tail.
+# Used to surface actionable context next to "Skipping dirty worktree" log lines
+# (previously gave no clue what was actually dirty).
+summarize_worktree_dirt() {
+  local wt="$1"
+  local modified_paths untracked_paths
+  modified_paths="$(git -C "$wt" diff --name-only --diff-filter=AMDR -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | head -3)"
+  local modified_count
+  modified_count="$(git -C "$wt" diff --name-only --diff-filter=AMDR -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | wc -l | tr -d ' ')"
+  untracked_paths="$(git -C "$wt" ls-files --others --exclude-standard -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | head -3)"
+  local untracked_count
+  untracked_count="$(git -C "$wt" ls-files --others --exclude-standard -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | wc -l | tr -d ' ')"
+
+  if [[ -n "$modified_paths" ]]; then
+    while IFS= read -r p; do
+      [[ -n "$p" ]] && echo "    modified: ${p}"
+    done <<< "$modified_paths"
+    if [[ "$modified_count" -gt 3 ]]; then
+      echo "    modified: (+$((modified_count - 3)) more)"
+    fi
+  fi
+  if [[ -n "$untracked_paths" ]]; then
+    while IFS= read -r p; do
+      [[ -n "$p" ]] && echo "    untracked: ${p}"
+    done <<< "$untracked_paths"
+    if [[ "$untracked_count" -gt 3 ]]; then
+      echo "    untracked: (+$((untracked_count - 3)) more)"
+    fi
+  fi
 }
 
 resolve_worktree_common_dir() {
@@ -317,6 +382,26 @@ read_branch_activity_epoch() {
 
 skipped_recent=0
 
+has_live_process_in_worktree() {
+  local wt="$1"
+  local proc_cwd=""
+
+  [[ -d /proc ]] || return 1
+
+  for proc_cwd in /proc/[0-9]*/cwd; do
+    [[ -e "$proc_cwd" ]] || continue
+    local live_cwd=""
+    live_cwd="$(readlink "$proc_cwd" 2>/dev/null || true)"
+    [[ -n "$live_cwd" ]] || continue
+    live_cwd="${live_cwd% (deleted)}"
+    if [[ "$live_cwd" == "$wt" || "$live_cwd" == "${wt}"/* ]]; then
+      return 0
+    fi
+  done
+
+  return 1
+}
+
 branch_idle_gate() {
   local branch="$1"
   local wt="$2"
@@ -431,11 +516,16 @@ process_entry() {
     return
   fi
 
-  if [[ "$wt" == "$current_pwd" ]]; then
+  if [[ -n "$current_pwd" && ( "$wt" == "$current_pwd" || "$current_pwd" == "${wt}"/* ) ]]; then
     skipped_active=$((skipped_active + 1))
     echo "[agent-worktree-prune] Skipping active cwd worktree: ${wt}"
     return
   fi
+  if has_live_process_in_worktree "$wt"; then
+    skipped_active=$((skipped_active + 1))
+    echo "[agent-worktree-prune] Skipping live process worktree: ${wt}"
+    return
+  fi
 
   local remove_reason=""
   local branch_delete_mode="safe"
@@ -477,6 +567,7 @@ process_entry() {
   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}"
+    summarize_worktree_dirt "$wt"
     return
   fi
 

package/templates/scripts/codex-agent.sh

@@ -6,6 +6,7 @@ AGENT_NAME="${GUARDEX_AGENT_NAME:-agent}"
 BASE_BRANCH="${GUARDEX_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 CODEX_BIN="${GUARDEX_CODEX_BIN:-codex}"
+CODEX_APPROVAL_POLICY="${GUARDEX_CODEX_APPROVAL_POLICY-never}"
 NODE_BIN="${GUARDEX_NODE_BIN:-node}"
 CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 AUTO_FINISH_RAW="${GUARDEX_CODEX_AUTO_FINISH:-true}"
@@ -67,6 +68,29 @@ normalize_tier() {
   esac
 }
 
+codex_args_include_approval_policy() {
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      -a|--ask-for-approval|--approval-policy|--dangerously-bypass-approvals-and-sandbox)
+        return 0
+        ;;
+      --ask-for-approval=*|--approval-policy=*)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+build_codex_launch_args() {
+  CODEX_LAUNCH_ARGS=()
+  if [[ -n "$CODEX_APPROVAL_POLICY" ]] && ! codex_args_include_approval_policy "$@"; then
+    CODEX_LAUNCH_ARGS+=("-a" "$CODEX_APPROVAL_POLICY")
+  fi
+  CODEX_LAUNCH_ARGS+=("$@")
+}
+
 string_contains_any() {
   local haystack="$1"
   shift
@@ -735,9 +759,14 @@ print_takeover_prompt() {
 
   finish_cmd="gx branch finish --branch \"${branch}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
 
-  echo "[codex-agent] Takeover sandbox: ${wt}"
-  echo "[codex-agent] Takeover routing: $(describe_task_routing) (${TASK_ROUTING_REASON})"
-  echo "[codex-agent] Takeover prompt: Continue \`${change_slug}\` on branch \`${branch}\`. Work inside \`${wt}\`, review \`${change_artifact}\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`${finish_cmd}\`."
+  echo "[codex-agent] Resume this sandbox:"
+  echo "  change:   ${change_slug}"
+  echo "  branch:   ${branch}"
+  echo "  worktree: ${wt}"
+  echo "  spec:     ${change_artifact}"
+  echo "  routing:  $(describe_task_routing) (${TASK_ROUTING_REASON})"
+  echo "  rule:     continue current state; do not create a new sandbox"
+  echo "  finish:   ${finish_cmd}"
 }
 
 sync_worktree_with_base() {
@@ -1034,7 +1063,8 @@ run_finish_flow() {
     (
       cd "$wt"
       set +e
-      "$CODEX_BIN" "$review_prompt"
+      build_codex_launch_args "$review_prompt"
+      "$CODEX_BIN" "${CODEX_LAUNCH_ARGS[@]}"
       review_exit="$?"
       set -e
       if [[ "$review_exit" -ne 0 ]]; then
@@ -1092,10 +1122,11 @@ trap cleanup_active_session_state_on_exit EXIT INT TERM
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
+build_codex_launch_args "$@"
 GUARDEX_TASK_MODE="$TASK_MODE" \
 GUARDEX_OPENSPEC_TIER="$OPENSPEC_TIER" \
 GUARDEX_TASK_ROUTING_REASON="$TASK_ROUTING_REASON" \
-  "$CODEX_BIN" "$@"
+  "$CODEX_BIN" "${CODEX_LAUNCH_ARGS[@]}"
 codex_exit="$?"
 set -e
 
@@ -1161,7 +1192,11 @@ else
       echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     else
       print_takeover_prompt "$worktree_path" "$worktree_branch"
-      echo "[codex-agent] If finished, merge with: gx branch finish --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
+      finish_base_branch="$(resolve_worktree_base_branch "$worktree_path")"
+      if [[ -z "$finish_base_branch" ]]; then
+        finish_base_branch="dev"
+      fi
+      echo "[codex-agent] If finished, merge with: gx branch finish --branch \"${worktree_branch}\" --base ${finish_base_branch} --via-pr --wait-for-merge --cleanup"
       echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     fi
   fi

package/templates/scripts/openspec/init-plan-workspace.sh

@@ -84,6 +84,7 @@ if [[ ! -f "$PLAN_DIR/README.md" ]]; then
     echo
     echo "Each role folder contains OpenSpec-style artifacts:"
     echo "- \`.openspec.yaml\`"
+    echo "- \`prompt.md\` (copy/paste role prompt)"
     echo "- \`proposal.md\`"
     echo "- \`tasks.md\` (Spec / Tests / Implementation / Checkpoints checklists)"
     echo "- \`specs/<role>/spec.md\`"
@@ -108,6 +109,7 @@ Drive this plan from draft to execution-ready status with strict checkpoint disc
 - \`openspec/plan/${PLAN_SLUG}/checkpoints.md\`
 - \`openspec/plan/${PLAN_SLUG}/open-questions.md\`
 - \`openspec/plan/${PLAN_SLUG}/planner/plan.md\`
+- role \`prompt.md\` files for copy/paste helper startup
 - role \`tasks.md\` files for planner/architect/critic/executor/writer/verifier
 
 ## Coordinator responsibilities
@@ -282,6 +284,7 @@ Role workspace for \`${role}\`.
 
 Default artifacts:
 - \`.openspec.yaml\`
+- \`prompt.md\`
 - \`proposal.md\`
 - \`tasks.md\`
 - \`specs/<role>/spec.md\`
@@ -302,12 +305,52 @@ plan: ${PLAN_SLUG}
 role: ${role}
 status: draft
 artifacts:
+  prompt: prompt.md
   proposal: proposal.md
   tasks: tasks.md
   spec: specs/${ROLE_SPEC_SLUG}/spec.md
 ROLEYAMLEOF
   fi
 
+  if [[ ! -f "$ROLE_DIR/prompt.md" ]]; then
+    cat > "$ROLE_DIR/prompt.md" <<ROLEPROMPTEOF
+# ${role} Prompt
+
+You are the \`${role}\` role for OpenSpec plan \`${PLAN_SLUG}\`.
+
+## Objective
+
+Complete only this role's assigned checklist and leave compact evidence for the coordinator.
+
+## Source of truth
+
+- \`openspec/plan/${PLAN_SLUG}/summary.md\`
+- \`openspec/plan/${PLAN_SLUG}/checkpoints.md\`
+- \`openspec/plan/${PLAN_SLUG}/open-questions.md\`
+- \`openspec/plan/${PLAN_SLUG}/${role}/tasks.md\`
+- \`openspec/plan/${PLAN_SLUG}/${role}/proposal.md\`
+
+## Before edits
+
+1. Confirm branch/worktree with \`git status --short --branch\`.
+2. Claim every touched file before editing:
+   - Prefer Colony \`task_claim_file\` when an active task exists.
+   - Otherwise run \`gx locks claim --branch <agent-branch> <file...>\`.
+3. Stay inside assigned files/modules; coordinate before touching shared paths.
+
+## Working rules
+
+- Update \`${role}/tasks.md\` as each item completes.
+- Record durable unresolved questions in \`open-questions.md\`.
+- Keep handoffs short: files changed, behavior touched, verification, risks.
+- Do not revert another agent's edits.
+
+## Cleanup
+
+Only the owner/finalizer lane runs \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`. If blocked, append \`BLOCKED:\` with branch, task, blocker, next, evidence.
+ROLEPROMPTEOF
+  fi
+
   if [[ ! -f "$ROLE_DIR/proposal.md" ]]; then
     cat > "$ROLE_DIR/proposal.md" <<ROLEPROPOSALEOF
 # Proposal: ${role} (${PLAN_SLUG})

package/templates/scripts/review-bot-watch.sh

@@ -64,6 +64,36 @@ normalize_bool() {
   esac
 }
 
+gh_api_probe_looks_like_network_failure() {
+  local probe_output="$1"
+  [[ "$probe_output" =~ error[[:space:]]connecting[[:space:]]to[[:space:]]api\.github\.com|Could[[:space:]]not[[:space:]]resolve[[:space:]]host|could[[:space:]]not[[:space:]]resolve[[:space:]]host|Failed[[:space:]]to[[:space:]]connect|failed[[:space:]]to[[:space:]]connect|Network[[:space:]]is[[:space:]]unreachable|network[[:space:]]is[[:space:]]unreachable|Connection[[:space:]]timed[[:space:]]out|connection[[:space:]]timed[[:space:]]out|Temporary[[:space:]]failure[[:space:]]in[[:space:]]name[[:space:]]resolution|temporary[[:space:]]failure[[:space:]]in[[:space:]]name[[:space:]]resolution ]]
+}
+
+ensure_gh_auth_or_explain() {
+  local auth_output probe_output
+  if auth_output="$(gh auth status 2>&1)"; then
+    return 0
+  fi
+
+  if probe_output="$(gh api user --jq .login 2>&1)"; then
+    echo "[review-bot-watch] gh auth status failed, but gh api user succeeded; continuing with usable GitHub auth." >&2
+    return 0
+  fi
+
+  if gh_api_probe_looks_like_network_failure "$probe_output"; then
+    echo "[review-bot-watch] GitHub API is unreachable, so gh cannot validate the stored token." >&2
+    echo "[review-bot-watch] This is a network or Codex sandbox connectivity problem, not proof that the token is invalid." >&2
+    echo "$probe_output" >&2
+    return 1
+  fi
+
+  echo "[review-bot-watch] gh is not authenticated. Run: gh auth login" >&2
+  if [[ -n "$auth_output" ]]; then
+    echo "$auth_output" >&2
+  fi
+  return 1
+}
+
 ONCE=0
 
 while [[ $# -gt 0 ]]; do
@@ -153,8 +183,7 @@ if ! command -v codex >/dev/null 2>&1; then
   exit 127
 fi
 
-if ! gh auth status >/dev/null 2>&1; then
-  echo "[review-bot-watch] gh is not authenticated. Run: gh auth login" >&2
+if ! ensure_gh_auth_or_explain; then
   exit 1
 fi