@imdeadpool/guardex 6.1.0 → 7.0.0

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

@@ -6,17 +6,10 @@ AGENT_NAME="agent"
 BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 WORKTREE_ROOT_REL=".omx/agent-worktrees"
-OPENSPEC_AUTO_INIT_RAW="${GX_OPENSPEC_AUTO_INIT:-${GUARDEX_OPENSPEC_AUTO_INIT:-true}}"
-TIER_LEVEL_RAW="${GUARDEX_TIER:-}"
-TIER_LEVEL_EXPLICIT=0
-GH_SYNC_ON_START_RAW="${GUARDEX_GH_SYNC_ON_START:-true}"
-MIGRATE_PROTECTED_CHANGES_RAW="${GUARDEX_MIGRATE_PROTECTED_CHANGES:-true}"
+OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
-PR_REF="${GUARDEX_GH_PR_REF:-}"
-GH_REPO_REF="${GUARDEX_GH_REPO:-}"
-PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -43,31 +36,6 @@ while [[ $# -gt 0 ]]; do
       WORKTREE_ROOT_REL="${2:-.omx/agent-worktrees}"
       shift 2
       ;;
-    --pr)
-      PR_REF="${2:-}"
-      shift 2
-      ;;
-    --repo)
-      GH_REPO_REF="${2:-}"
-      shift 2
-      ;;
-    --gh-sync)
-      GH_SYNC_ON_START_RAW="true"
-      shift
-      ;;
-    --no-gh-sync)
-      GH_SYNC_ON_START_RAW="false"
-      shift
-      ;;
-    --print-name-only)
-      PRINT_NAME_ONLY=1
-      shift
-      ;;
-    --tier)
-      TIER_LEVEL_RAW="${2:-}"
-      TIER_LEVEL_EXPLICIT=1
-      shift 2
-      ;;
     --)
       shift
       while [[ $# -gt 0 ]]; do
@@ -78,7 +46,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     -*)
       echo "[agent-branch-start] Unknown option: $1" >&2
-      echo "Usage: $0 [task] [agent] [base] [--tier T0|T1|T2|T3] [--worktree-root <path>] [--pr <ref>] [--repo <owner/name>] [--gh-sync|--no-gh-sync]" >&2
+      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&2
       exit 1
       ;;
     *)
@@ -90,7 +58,7 @@ done
 
 if [[ "${#POSITIONAL_ARGS[@]}" -gt 3 ]]; then
   echo "[agent-branch-start] Too many positional arguments." >&2
-  echo "Usage: $0 [task] [agent] [base] [--tier T0|T1|T2|T3] [--worktree-root <path>] [--pr <ref>] [--repo <owner/name>] [--gh-sync|--no-gh-sync]" >&2
+  echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&2
   exit 1
 fi
 
@@ -163,122 +131,21 @@ checksum_slug_suffix() {
 }
 
 compose_branch_descriptor() {
-  local task_slug="$1"
-  local task_max task_part checksum_part
+  local snapshot_slug="$1"
+  local task_slug="$2"
+  local snapshot_max task_max task_part snapshot_part checksum_input checksum_part
+  snapshot_max="$(normalize_positive_int "${GUARDEX_BRANCH_SNAPSHOT_SLUG_MAX:-18}" "18")"
   task_max="$(normalize_positive_int "${GUARDEX_BRANCH_TASK_SLUG_MAX:-36}" "36")"
   task_part="$(shorten_slug "$task_slug" "$task_max")"
-  checksum_part="$(checksum_slug_suffix "$task_slug")"
-  printf '%s-%s' "$task_part" "$checksum_part"
-}
-
-normalize_agent_type() {
-  local raw="${1:-}"
-  local lowered
-  if [[ -n "${GUARDEX_AGENT_TYPE:-}" ]]; then
-    printf '%s' "${GUARDEX_AGENT_TYPE}"
-    return 0
-  fi
-  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
-  if [[ "$lowered" == *codex* ]]; then
-    printf 'codex'
-    return 0
-  fi
-  if [[ "$lowered" == *claude* ]]; then
-    printf 'claude'
-    return 0
-  fi
-  if [[ -n "${CLAUDECODE:-}" || -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
-    printf 'claude'
-    return 0
-  fi
-  if [[ -n "${CODEX_CLI:-}" ]]; then
-    printf 'codex'
-    return 0
-  fi
-  printf 'codex'
-}
-
-lookup_nickname_map() {
-  local key="$1"
-  local map_env="${GUARDEX_EMAIL_NICKNAME_MAP:-}"
-  local map_file="${repo_root:-$(pwd)}/.agents/nickname-map.json"
-  local value=""
-  if ! command -v python3 >/dev/null 2>&1; then
-    printf ''
-    return 0
-  fi
-  if [[ -n "$map_env" ]]; then
-    value="$(KEY="$key" MAP="$map_env" python3 -c '
-import json, os
-try:
-    data = json.loads(os.environ.get("MAP") or "{}")
-    print(data.get(os.environ.get("KEY", ""), ""))
-except Exception:
-    pass
-' 2>/dev/null || true)"
-  fi
-  if [[ -z "$value" && -f "$map_file" ]]; then
-    value="$(KEY="$key" FILE="$map_file" python3 -c '
-import json, os
-try:
-    with open(os.environ["FILE"]) as f:
-        data = json.load(f)
-    print(data.get(os.environ.get("KEY", ""), ""))
-except Exception:
-    pass
-' 2>/dev/null || true)"
-  fi
-  printf '%s' "$value"
-}
-
-time_fallback_nickname() {
-  # Current wall-clock HH-MM used when no codex-auth nickname is resolvable
-  # (typical for Claude sessions). Produces visually distinct, sortable
-  # branch slugs instead of the generic "none" marker. Tests override via
-  # GUARDEX_NICKNAME_TIME_FALLBACK.
-  if [[ -n "${GUARDEX_NICKNAME_TIME_FALLBACK:-}" ]]; then
-    printf '%s' "${GUARDEX_NICKNAME_TIME_FALLBACK}"
-    return 0
-  fi
-  printf '%s' "$(date +%H-%M)"
-}
-
-extract_nickname() {
-  local raw="${1:-}"
-  local lowered candidate mapped fallback use_account_raw use_account
-  fallback="$(time_fallback_nickname)"
-  # Default: always use the HH-MM time fallback so agent branches are
-  # distinguishable by creation time (e.g. `agent/claude-00-38/…`) instead of
-  # reflecting whichever codex-auth account happens to be active. Opt back in
-  # to the old account-nickname behavior with GUARDEX_USE_ACCOUNT_NICKNAME=1.
-  use_account_raw="${GUARDEX_USE_ACCOUNT_NICKNAME:-0}"
-  use_account="$(printf '%s' "$use_account_raw" | tr '[:upper:]' '[:lower:]')"
-  case "$use_account" in
-    1|true|yes|on) use_account=1 ;;
-    *) use_account=0 ;;
-  esac
-  if [[ "$use_account" -ne 1 || -z "$raw" ]]; then
-    printf '%s' "$fallback"
-    return 0
-  fi
-  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
-  mapped="$(lookup_nickname_map "$lowered")"
-  if [[ -n "$mapped" ]]; then
-    sanitize_slug "$mapped" "$fallback"
+  if [[ -n "$snapshot_slug" ]]; then
+    snapshot_part="$(shorten_slug "$snapshot_slug" "$snapshot_max")"
+    checksum_input="${snapshot_slug}--${task_slug}"
+    checksum_part="$(checksum_slug_suffix "$checksum_input")"
+    printf '%s-%s-%s' "$snapshot_part" "$task_part" "$checksum_part"
     return 0
   fi
-  if [[ "$lowered" == *"@"* ]]; then
-    candidate="${lowered%%@*}"
-  elif [[ "$lowered" == *-* ]]; then
-    candidate="${lowered%%-*}"
-  else
-    candidate="$lowered"
-  fi
-  candidate="$(sanitize_slug "$candidate" "$fallback")"
-  if [[ -z "$candidate" || "$candidate" == "none" ]]; then
-    candidate="$fallback"
-  fi
-  printf '%s' "$candidate"
+  checksum_part="$(checksum_slug_suffix "$task_slug")"
+  printf '%s-%s' "$task_part" "$checksum_part"
 }
 
 normalize_bool() {
@@ -295,63 +162,6 @@ normalize_bool() {
 }
 
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
-GH_SYNC_ON_START="$(normalize_bool "$GH_SYNC_ON_START_RAW" "1")"
-MIGRATE_PROTECTED_CHANGES="$(normalize_bool "$MIGRATE_PROTECTED_CHANGES_RAW" "1")"
-
-normalize_tier() {
-  local raw="${1:-}"
-  local upper
-  upper="$(printf '%s' "$raw" | tr '[:lower:]' '[:upper:]')"
-  case "$upper" in
-    T0|T1|T2|T3) printf '%s' "$upper" ;;
-    0) printf 'T0' ;;
-    1) printf 'T1' ;;
-    2) printf 'T2' ;;
-    3) printf 'T3' ;;
-    '') printf 'T3' ;;
-    *)
-      echo "[agent-branch-start] Unknown tier: ${raw} (expected T0|T1|T2|T3)" >&2
-      return 1
-      ;;
-  esac
-}
-
-if ! TIER_LEVEL="$(normalize_tier "$TIER_LEVEL_RAW")"; then
-  exit 1
-fi
-
-case "$TIER_LEVEL" in
-  T0)
-    OPENSPEC_CHANGE_INIT=0
-    OPENSPEC_PLAN_INIT=0
-    OPENSPEC_CHANGE_MINIMAL=0
-    ;;
-  T1)
-    OPENSPEC_CHANGE_INIT=1
-    OPENSPEC_PLAN_INIT=0
-    OPENSPEC_CHANGE_MINIMAL=1
-    ;;
-  T2)
-    OPENSPEC_CHANGE_INIT=1
-    OPENSPEC_PLAN_INIT=0
-    OPENSPEC_CHANGE_MINIMAL=0
-    ;;
-  T3)
-    OPENSPEC_CHANGE_INIT=1
-    OPENSPEC_PLAN_INIT=1
-    OPENSPEC_CHANGE_MINIMAL=0
-    ;;
-esac
-
-# Explicit tier overrides the legacy OPENSPEC_AUTO_INIT env var; otherwise keep legacy behavior.
-if [[ "$TIER_LEVEL_EXPLICIT" -eq 1 ]]; then
-  OPENSPEC_AUTO_INIT="$OPENSPEC_CHANGE_INIT"
-fi
-
-is_helper_agent_base_branch() {
-  local base_branch="$1"
-  [[ "$base_branch" == agent/* ]]
-}
 
 resolve_openspec_plan_slug() {
   local branch_name="$1"
@@ -414,54 +224,6 @@ has_local_changes() {
   return 1
 }
 
-migrate_local_changes_to_worktree() {
-  local root="$1"
-  local source_branch="$2"
-  local target_branch="$3"
-  local target_worktree="$4"
-  local stash_label stash_output stash_status apply_output apply_status
-  local stash_ref="stash@{0}"
-
-  if ! has_local_changes "$root"; then
-    return 0
-  fi
-
-  stash_label="guardex-migrate-${source_branch//\//-}-to-${target_branch//\//-}-$(date -u +%Y%m%dT%H%M%SZ)"
-
-  set +e
-  stash_output="$(git -C "$root" stash push --include-untracked --message "$stash_label" 2>&1)"
-  stash_status=$?
-  set -e
-  if [[ "$stash_status" -ne 0 ]]; then
-    echo "[agent-branch-start] Failed to stash protected-branch changes before migration." >&2
-    printf '%s\n' "$stash_output" >&2
-    return 1
-  fi
-
-  if printf '%s\n' "$stash_output" | grep -qi "No local changes to save"; then
-    return 0
-  fi
-
-  set +e
-  apply_output="$(git -C "$target_worktree" stash apply --index "$stash_ref" 2>&1)"
-  apply_status=$?
-  set -e
-  if [[ "$apply_status" -ne 0 ]]; then
-    echo "[agent-branch-start] Created stash ${stash_ref} but could not auto-apply into worktree '${target_worktree}'." >&2
-    printf '%s\n' "$apply_output" >&2
-    echo "[agent-branch-start] Manual recovery options:" >&2
-    echo "  # apply in sandbox worktree" >&2
-    echo "  git -C \"$target_worktree\" stash apply --index ${stash_ref}" >&2
-    echo "  # or restore on primary checkout if needed" >&2
-    echo "  git -C \"$root\" stash apply --index ${stash_ref}" >&2
-    return 1
-  fi
-
-  git -C "$root" stash drop "$stash_ref" >/dev/null 2>&1 || true
-  echo "[agent-branch-start] Migrated local changes from '${source_branch}' into '${target_branch}' (${target_worktree})."
-  return 0
-}
-
 resolve_protected_branches() {
   local root="$1"
   local raw
@@ -484,51 +246,6 @@ is_protected_branch_name() {
   return 1
 }
 
-branch_exists_locally_or_on_origin() {
-  local root="$1"
-  local branch="$2"
-  if git -C "$root" show-ref --verify --quiet "refs/heads/${branch}"; then
-    return 0
-  fi
-  if git -C "$root" show-ref --verify --quiet "refs/remotes/origin/${branch}"; then
-    return 0
-  fi
-  return 1
-}
-
-resolve_default_base_branch_for_agent_subbranch() {
-  local root="$1"
-  local protected_raw="$2"
-  local configured_base candidate
-
-  configured_base="$(git -C "$root" config --get multiagent.baseBranch || true)"
-  if [[ -n "$configured_base" ]] && branch_exists_locally_or_on_origin "$root" "$configured_base"; then
-    printf '%s' "$configured_base"
-    return 0
-  fi
-
-  for candidate in $protected_raw; do
-    if branch_exists_locally_or_on_origin "$root" "$candidate"; then
-      printf '%s' "$candidate"
-      return 0
-    fi
-  done
-
-  if branch_exists_locally_or_on_origin "$root" "dev"; then
-    printf 'dev'
-    return 0
-  fi
-  if branch_exists_locally_or_on_origin "$root" "main"; then
-    printf 'main'
-    return 0
-  fi
-  if branch_exists_locally_or_on_origin "$root" "master"; then
-    printf 'master'
-    return 0
-  fi
-  return 1
-}
-
 hydrate_local_helper_in_worktree() {
   local repo="$1"
   local worktree="$2"
@@ -586,7 +303,7 @@ initialize_openspec_plan_workspace() {
 
   hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh"
 
-  if [[ "${OPENSPEC_PLAN_INIT:-$OPENSPEC_AUTO_INIT}" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
     return 0
   fi
 
@@ -621,7 +338,6 @@ initialize_openspec_change_workspace() {
   local worktree="$2"
   local change_slug="$3"
   local capability_slug="$4"
-  local branch_name="${5:-}"
 
   hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-change-workspace.sh"
 
@@ -642,8 +358,7 @@ initialize_openspec_change_workspace() {
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    GUARDEX_OPENSPEC_MINIMAL="${OPENSPEC_CHANGE_MINIMAL:-0}" \
-      bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" "$branch_name" 2>&1
+    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[agent-branch-start] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
@@ -656,459 +371,6 @@ initialize_openspec_change_workspace() {
   echo "[agent-branch-start] OpenSpec change workspace: ${worktree}/openspec/changes/${change_slug}"
 }
 
-filtered_status_output() {
-  local wt="$1"
-  git -C "$wt" status --porcelain --untracked-files=normal -- \
-    . \
-    ":(exclude).omx/state/agent-file-locks.json" \
-    ":(exclude).dev-ports.json" \
-    ":(exclude)apps/logs/*.log"
-}
-
-resolve_worktree_git_dir() {
-  local wt="$1"
-  local git_dir=""
-  git_dir="$(git -C "$wt" rev-parse --git-dir 2>/dev/null || true)"
-  if [[ -z "$git_dir" ]]; then
-    return 1
-  fi
-  if [[ "$git_dir" == /* ]]; then
-    git_dir="$(cd "$git_dir" 2>/dev/null && pwd -P || true)"
-  else
-    git_dir="$(cd "$wt/$git_dir" 2>/dev/null && pwd -P || true)"
-  fi
-  if [[ -z "$git_dir" ]]; then
-    return 1
-  fi
-  printf '%s' "$git_dir"
-}
-
-bootstrap_manifest_path_for_worktree() {
-  local wt="$1"
-  local git_dir=""
-  git_dir="$(resolve_worktree_git_dir "$wt" || true)"
-  if [[ -z "$git_dir" ]]; then
-    return 1
-  fi
-  printf '%s/guardex-bootstrap-manifest.json' "$git_dir"
-}
-
-record_worktree_bootstrap_manifest() {
-  local worktree="$1"
-  local branch="$2"
-  local base_branch="$3"
-  local change_slug="$4"
-  local plan_slug="$5"
-  local tier="${6:-T3}"
-  local manifest_path=""
-  local status_output=""
-
-  manifest_path="$(bootstrap_manifest_path_for_worktree "$worktree" || true)"
-  if [[ -z "$manifest_path" ]]; then
-    return 0
-  fi
-
-  status_output="$(filtered_status_output "$worktree")"
-  STATUS_OUTPUT="$status_output" python3 - "$worktree" "$manifest_path" "$branch" "$base_branch" "$change_slug" "$plan_slug" "$tier" <<'PY'
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-
-def parse_status_paths(raw: str) -> list[str]:
-    paths: list[str] = []
-    for line in raw.splitlines():
-        if len(line) < 4:
-            continue
-        path_part = line[3:]
-        if " -> " in path_part:
-            path_part = path_part.split(" -> ", 1)[1]
-        path_part = path_part.strip()
-        if path_part:
-            paths.append(path_part)
-    return sorted(set(paths))
-
-
-def sha256_for_file(path: Path) -> str | None:
-    if not path.exists() or not path.is_file():
-        return None
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(65536), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-if len(sys.argv) != 8:
-    sys.exit(1)
-
-worktree_root = Path(sys.argv[1])
-manifest_path = Path(sys.argv[2])
-branch_name = sys.argv[3]
-base_branch = sys.argv[4]
-change_slug = sys.argv[5]
-plan_slug = sys.argv[6]
-tier = sys.argv[7] or "T3"
-
-status_paths = parse_status_paths(os.environ.get("STATUS_OUTPUT", ""))
-entries: list[dict[str, object]] = []
-for rel_path in status_paths:
-    file_path = worktree_root / rel_path
-    entries.append(
-        {
-            "path": rel_path,
-            "sha256": sha256_for_file(file_path),
-        }
-    )
-
-payload = {
-    "version": 1,
-    "generatedAt": datetime.now(timezone.utc).isoformat(),
-    "branch": branch_name,
-    "baseBranch": base_branch,
-    "changeSlug": change_slug,
-    "planSlug": plan_slug,
-    "tier": tier,
-    "files": entries,
-}
-
-manifest_path.parent.mkdir(parents=True, exist_ok=True)
-manifest_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
-PY
-  echo "[agent-branch-start] Bootstrap manifest: ${manifest_path}"
-}
-
-worktree_matches_bootstrap_manifest() {
-  local worktree="$1"
-  local manifest_path=""
-  local status_output=""
-
-  manifest_path="$(bootstrap_manifest_path_for_worktree "$worktree" || true)"
-  if [[ -z "$manifest_path" || ! -f "$manifest_path" ]]; then
-    return 1
-  fi
-
-  status_output="$(filtered_status_output "$worktree")"
-  if [[ -z "$status_output" ]]; then
-    return 1
-  fi
-
-  STATUS_OUTPUT="$status_output" python3 - "$worktree" "$manifest_path" <<'PY'
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import sys
-from pathlib import Path
-
-
-def parse_status_paths(raw: str) -> list[str]:
-    paths: list[str] = []
-    for line in raw.splitlines():
-        if len(line) < 4:
-            continue
-        path_part = line[3:]
-        if " -> " in path_part:
-            path_part = path_part.split(" -> ", 1)[1]
-        path_part = path_part.strip()
-        if path_part:
-            paths.append(path_part)
-    return sorted(set(paths))
-
-
-def sha256_for_file(path: Path) -> str | None:
-    if not path.exists() or not path.is_file():
-        return None
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(65536), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-if len(sys.argv) != 3:
-    sys.exit(1)
-
-worktree_root = Path(sys.argv[1])
-manifest_path = Path(sys.argv[2])
-
-status_paths = parse_status_paths(os.environ.get("STATUS_OUTPUT", ""))
-if not status_paths:
-    sys.exit(1)
-
-try:
-    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
-except Exception:
-    sys.exit(1)
-
-entries = payload.get("files")
-if not isinstance(entries, list):
-    sys.exit(1)
-
-manifest_by_path: dict[str, str | None] = {}
-for entry in entries:
-    if not isinstance(entry, dict):
-        continue
-    path_value = entry.get("path")
-    if not isinstance(path_value, str) or not path_value:
-        continue
-    sha_value = entry.get("sha256")
-    if sha_value is not None and not isinstance(sha_value, str):
-        continue
-    manifest_by_path[path_value] = sha_value
-
-if not manifest_by_path:
-    sys.exit(1)
-
-for rel_path in status_paths:
-    if rel_path not in manifest_by_path:
-        sys.exit(1)
-    current_sha = sha256_for_file(worktree_root / rel_path)
-    if current_sha != manifest_by_path.get(rel_path):
-        sys.exit(1)
-
-sys.exit(0)
-PY
-}
-
-get_worktree_for_branch() {
-  local branch="$1"
-  git -C "$repo_root" worktree list --porcelain | awk -v target="refs/heads/${branch}" '
-    $1 == "worktree" { wt = $2 }
-    $1 == "branch" && $2 == target { print wt; exit }
-  '
-}
-
-is_clean_worktree() {
-  local wt="$1"
-  git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
-    && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
-    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
-}
-
-json_escape() {
-  local raw="$1"
-  raw="${raw//\\/\\\\}"
-  raw="${raw//\"/\\\"}"
-  raw="${raw//$'\n'/\\n}"
-  printf '%s' "$raw"
-}
-
-link_worktree_mem0_compat_file() {
-  local mem0_file="$1"
-  local compat_file="$2"
-  local compat_target="$3"
-
-  mkdir -p "$(dirname "$compat_file")"
-  if [[ -e "$compat_file" ]]; then
-    return 0
-  fi
-
-  if ln -s "$compat_target" "$compat_file" >/dev/null 2>&1; then
-    return 0
-  fi
-
-  cp "$mem0_file" "$compat_file"
-}
-
-initialize_worktree_mem0_layer() {
-  local worktree="$1"
-  local branch="$2"
-  local base_branch="$3"
-  local task_slug="$4"
-  local agent_slug="$5"
-
-  local omx_dir="${worktree}/.omx"
-  local mem0_dir="${omx_dir}/mem0"
-  local notepad_path="${mem0_dir}/notepad.md"
-  local project_memory_path="${mem0_dir}/project-memory.json"
-  local scope_path="${mem0_dir}/worktree-scope.json"
-  local created_at
-  local now
-
-  mkdir -p "$mem0_dir"
-
-  if [[ ! -f "$notepad_path" ]]; then
-    cat >"$notepad_path" <<EOF
-# Mem0 Worktree Memory
-
-- Scope: worktree
-- Branch: ${branch}
-- Base: ${base_branch}
-- Task: ${task_slug}
-- Agent: ${agent_slug}
-
-## WORKING MEMORY
-EOF
-  fi
-
-  if [[ ! -f "$project_memory_path" ]]; then
-    created_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-    cat >"$project_memory_path" <<EOF
-{
-  "version": 1,
-  "scope": "worktree",
-  "branch": "$(json_escape "$branch")",
-  "baseBranch": "$(json_escape "$base_branch")",
-  "taskSlug": "$(json_escape "$task_slug")",
-  "agentSlug": "$(json_escape "$agent_slug")",
-  "createdAt": "$(json_escape "$created_at")",
-  "notes": [],
-  "directives": []
-}
-EOF
-  fi
-
-  now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  cat >"$scope_path" <<EOF
-{
-  "version": 1,
-  "scope": "worktree",
-  "branch": "$(json_escape "$branch")",
-  "baseBranch": "$(json_escape "$base_branch")",
-  "taskSlug": "$(json_escape "$task_slug")",
-  "agentSlug": "$(json_escape "$agent_slug")",
-  "worktreePath": "$(json_escape "$worktree")",
-  "updatedAt": "$(json_escape "$now")",
-  "notepadPath": ".omx/mem0/notepad.md",
-  "projectMemoryPath": ".omx/mem0/project-memory.json"
-}
-EOF
-
-  link_worktree_mem0_compat_file "$notepad_path" "${omx_dir}/notepad.md" "mem0/notepad.md"
-  link_worktree_mem0_compat_file "$project_memory_path" "${omx_dir}/project-memory.json" "mem0/project-memory.json"
-  echo "[agent-branch-start] Mem0 worktree memory: ${mem0_dir}"
-}
-
-run_startup_context_artifacts() {
-  local repo="$1"
-  local worktree="$2"
-  local branch="$3"
-  local base_branch="$4"
-  local pr_ref="$5"
-  local repo_ref="$6"
-  local branch_slug
-  local github_context_dir="${worktree}/.omx/context/github"
-  local merge_gate_dir="${worktree}/.omx/state/merge-gates"
-  local context_pack_dir="${worktree}/.omx/context/packs"
-  local context_json=""
-  local conflict_json=""
-  local context_pack_json=""
-  local conflict_passed=1
-
-  mkdir -p "$github_context_dir" "$merge_gate_dir" "$context_pack_dir"
-  branch_slug="$(sanitize_slug "${branch//\//-}" "context-pack")"
-
-  if [[ "$GH_SYNC_ON_START" -eq 1 ]]; then
-    if [[ -x "${repo}/scripts/omx-gh-sync.sh" ]]; then
-      local sync_args=(--branch "$branch" --output-dir "$github_context_dir")
-      if [[ -n "$pr_ref" ]]; then
-        sync_args+=(--pr "$pr_ref")
-      fi
-      if [[ -n "$repo_ref" ]]; then
-        sync_args+=(--repo "$repo_ref")
-      fi
-      local sync_output=""
-      if sync_output="$(bash "${repo}/scripts/omx-gh-sync.sh" "${sync_args[@]}" 2>&1)"; then
-        printf '%s\n' "$sync_output"
-        context_json="$(printf '%s\n' "$sync_output" | sed -n 's/^Context JSON: //p' | tail -n1)"
-      else
-        echo "[agent-branch-start] Warning: GitHub context sync failed; continuing with local-only startup context." >&2
-        printf '%s\n' "$sync_output" >&2
-      fi
-    else
-      echo "[agent-branch-start] Warning: scripts/omx-gh-sync.sh is missing; skipping GitHub context sync." >&2
-    fi
-  else
-    echo "[agent-branch-start] GitHub context sync disabled (--no-gh-sync)."
-  fi
-
-  if [[ -x "${repo}/scripts/agent-conflict-predict.sh" ]]; then
-    local conflict_output=""
-    local conflict_args=(--branch "$branch" --base "$base_branch" --output-dir "$merge_gate_dir")
-    if conflict_output="$(bash "${repo}/scripts/agent-conflict-predict.sh" "${conflict_args[@]}" 2>&1)"; then
-      printf '%s\n' "$conflict_output"
-      conflict_json="$(printf '%s\n' "$conflict_output" | sed -n 's/^Conflict JSON: //p' | tail -n1)"
-    else
-      conflict_passed=0
-      echo "[agent-branch-start] Warning: conflict predictor reported overlaps/locks before coding begins." >&2
-      printf '%s\n' "$conflict_output" >&2
-    fi
-  fi
-
-  if [[ -x "${repo}/scripts/omx-context-pack.sh" ]]; then
-    local pack_args=(
-      --slug "$branch_slug"
-      --branch "$branch"
-      --base "$base_branch"
-      --output-dir "$context_pack_dir"
-    )
-    if [[ -n "$context_json" ]]; then
-      pack_args+=(--context-file "$context_json")
-    fi
-    if [[ -n "$conflict_json" ]]; then
-      pack_args+=(--conflict-file "$conflict_json")
-    fi
-    local pack_output=""
-    if pack_output="$(bash "${repo}/scripts/omx-context-pack.sh" "${pack_args[@]}" 2>&1)"; then
-      printf '%s\n' "$pack_output"
-      context_pack_json="$(printf '%s\n' "$pack_output" | sed -n 's/^Context pack JSON: //p' | tail -n1)"
-    else
-      echo "[agent-branch-start] Warning: context pack assembly failed; continuing without startup pack." >&2
-      printf '%s\n' "$pack_output" >&2
-    fi
-  fi
-
-  python3 - "${github_context_dir}/sandbox-startup-latest.json" "$branch" "$base_branch" "$pr_ref" "$repo_ref" "$GH_SYNC_ON_START" "$conflict_passed" "$context_json" "$conflict_json" "$context_pack_json" <<'PY'
-from __future__ import annotations
-
-import json
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-(
-    _,
-    output_path,
-    branch_name,
-    base_name,
-    pr_value,
-    repo_value,
-    gh_sync_value,
-    conflict_value,
-    context_json_path,
-    conflict_json_path,
-    context_pack_path,
-) = sys.argv
-
-payload = {
-    "version": 1,
-    "generated_at": datetime.now(timezone.utc).isoformat(),
-    "branch": branch_name,
-    "base_branch": base_name,
-    "pr": pr_value,
-    "repo": repo_value,
-    "gh_sync_enabled": int(gh_sync_value),
-    "conflict_passed": int(conflict_value),
-    "context_json": context_json_path,
-    "conflict_json": conflict_json_path,
-    "context_pack_json": context_pack_path,
-}
-
-target = Path(output_path)
-target.parent.mkdir(parents=True, exist_ok=True)
-target.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
-PY
-
-  echo "[agent-branch-start] Startup metadata: ${github_context_dir}/sandbox-startup-latest.json"
-}
-
 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
@@ -1124,39 +386,20 @@ fi
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
   protected_branches_raw="$(resolve_protected_branches "$repo_root")"
-  configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
   if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
     BASE_BRANCH="$current_branch"
-  elif [[ -n "$current_branch" && "$current_branch" == agent/* ]]; then
-    BASE_BRANCH="$current_branch"
-    echo "[agent-branch-start] Using current agent branch '${BASE_BRANCH}' as helper base."
-  elif [[ -n "$configured_base" ]]; then
-    BASE_BRANCH="$configured_base"
   else
-    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="$(resolve_default_base_branch_for_agent_subbranch "$repo_root" "$protected_branches_raw" || printf 'dev')"
+      BASE_BRANCH="dev"
     fi
   fi
 fi
 
-helper_branch_assist_mode=0
-if is_helper_agent_base_branch "$BASE_BRANCH"; then
-  helper_branch_assist_mode=1
-  OPENSPEC_AUTO_INIT=0
-  OPENSPEC_CHANGE_INIT=0
-  OPENSPEC_PLAN_INIT=0
-  OPENSPEC_CHANGE_MINIMAL=0
-  echo "[agent-branch-start] Helper branch base '${BASE_BRANCH}' detected; skipping OpenSpec auto-init for joined-agent assist."
-elif [[ "$TIER_LEVEL_EXPLICIT" -eq 1 && "$TIER_LEVEL" == "T0" ]]; then
-  echo "[agent-branch-start] Tier T0: skipping OpenSpec change + plan workspace scaffolding."
-elif [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
-  echo "[agent-branch-start] OpenSpec auto-init is mandatory for non-helper agent branches; ignoring disabled override." >&2
-  OPENSPEC_AUTO_INIT=1
-  OPENSPEC_CHANGE_INIT=1
-fi
-
 if git show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
   git fetch origin "${BASE_BRANCH}" --quiet
   start_ref="origin/${BASE_BRANCH}"
@@ -1169,74 +412,72 @@ else
 fi
 
 task_slug="$(sanitize_slug "$TASK_NAME" "task")"
-agent_type="$(normalize_agent_type "$AGENT_NAME")"
+agent_slug_raw="$(sanitize_slug "$AGENT_NAME" "agent")"
+agent_slug="$(shorten_slug "$agent_slug_raw" "${GUARDEX_BRANCH_AGENT_SLUG_MAX:-24}")"
 snapshot_name="$(resolve_active_codex_snapshot_name)"
-nickname="$(extract_nickname "$snapshot_name")"
-agent_slug="${agent_type}-${nickname}"
-branch_descriptor="$(compose_branch_descriptor "$task_slug")"
+snapshot_slug="$(sanitize_optional_slug "$snapshot_name" "snapshot")"
+branch_descriptor="$(compose_branch_descriptor "$snapshot_slug" "$task_slug")"
 timestamp="$(date +%Y%m%d-%H%M%S)"
 branch_name_base="agent/${agent_slug}/${branch_descriptor}"
 
-if [[ "$PRINT_NAME_ONLY" -eq 1 ]]; then
-  printf '%s\n' "$branch_name_base"
-  exit 0
-fi
-
 branch_name="$branch_name_base"
+branch_suffix=2
+while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
+  branch_name="${branch_name_base}-${branch_suffix}"
+  branch_suffix=$((branch_suffix + 1))
+done
+
 worktree_root="${repo_root}/${WORKTREE_ROOT_REL}"
 mkdir -p "$worktree_root"
-worktree_path=""
-reused_existing_worktree=0
-
-if git show-ref --verify --quiet "refs/heads/${branch_name_base}"; then
-  existing_worktree_path="$(get_worktree_for_branch "$branch_name_base" || true)"
-  if [[ -n "$existing_worktree_path" && -d "$existing_worktree_path" ]] \
-    && git -C "$repo_root" merge-base --is-ancestor "$branch_name_base" "$start_ref" >/dev/null 2>&1; then
-    if is_clean_worktree "$existing_worktree_path" || worktree_matches_bootstrap_manifest "$existing_worktree_path"; then
-      worktree_path="$existing_worktree_path"
-      reused_existing_worktree=1
-      echo "[agent-branch-start] Reusing untouched sandbox branch/worktree: ${branch_name_base} (${worktree_path})"
-    fi
-  fi
-fi
-
-if [[ "$reused_existing_worktree" -eq 0 ]]; then
-  branch_suffix=2
-  while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
-    branch_name="${branch_name_base}-${branch_suffix}"
-    branch_suffix=$((branch_suffix + 1))
-  done
-  worktree_path="${worktree_root}/${branch_name//\//__}"
-  if [[ -e "$worktree_path" ]]; then
-    echo "[agent-branch-start] Worktree path already exists: ${worktree_path}" >&2
-    exit 1
-  fi
-fi
-
+worktree_path="${worktree_root}/${branch_name//\//__}"
 openspec_plan_slug="$(resolve_openspec_plan_slug "$branch_name" "$task_slug")"
 openspec_change_slug="$(resolve_openspec_change_slug "$branch_name" "$task_slug")"
 openspec_capability_slug="$(resolve_openspec_capability_slug "$task_slug")"
 
-primary_branch_before="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ -e "$worktree_path" ]]; then
+  echo "[agent-branch-start] Worktree path already exists: ${worktree_path}" >&2
+  exit 1
+fi
+
+auto_transfer_stash_ref=""
+auto_transfer_message=""
+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")"
-should_migrate_protected_changes=0
-if [[ -n "$primary_branch_before" && "$primary_branch_before" != "HEAD" ]] && is_protected_branch_name "$primary_branch_before" "$protected_branches_raw"; 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
-    if [[ "$MIGRATE_PROTECTED_CHANGES" -eq 1 ]]; then
-      should_migrate_protected_changes=1
-      echo "[agent-branch-start] Detected local changes on protected branch '${primary_branch_before}'. Scheduling migration into sandbox worktree."
-    else
-      echo "[agent-branch-start] Detected local changes on protected branch '${primary_branch_before}'. Leaving them in place (GUARDEX_MIGRATE_PROTECTED_CHANGES=0)."
+    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="$(
+        git -C "$repo_root" stash list \
+          | awk -v msg="$auto_transfer_message" '$0 ~ msg { ref=$1; sub(/:$/, "", ref); print ref; exit }'
+      )"
+      if [[ -n "$auto_transfer_stash_ref" ]]; then
+        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
 fi
 
-if [[ "$reused_existing_worktree" -eq 0 ]]; then
-  git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref"
-  git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
+git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref"
+git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$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
+if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git -C "$worktree_path" branch --set-upstream-to="origin/${BASE_BRANCH}" "$branch_name" >/dev/null 2>&1 || true
+fi
+
+if [[ -n "$auto_transfer_stash_ref" ]]; then
+  if git -C "$worktree_path" stash apply "$auto_transfer_stash_ref" >/dev/null 2>&1; then
+    git -C "$repo_root" stash drop "$auto_transfer_stash_ref" >/dev/null 2>&1 || true
+    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
+    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
 
@@ -1244,61 +485,19 @@ hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-ag
 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"
-hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" ".venv"
-if [[ "$reused_existing_worktree" -eq 0 ]]; then
-  if ! initialize_openspec_change_workspace "$repo_root" "$worktree_path" "$openspec_change_slug" "$openspec_capability_slug" "$branch_name"; then
-    exit 1
-  fi
-  if ! initialize_openspec_plan_workspace "$repo_root" "$worktree_path" "$openspec_plan_slug"; then
-    exit 1
-  fi
-fi
-initialize_worktree_mem0_layer "$worktree_path" "$branch_name" "$BASE_BRANCH" "$task_slug" "$agent_slug"
-
-if [[ "$should_migrate_protected_changes" -eq 1 ]]; then
-  if ! migrate_local_changes_to_worktree "$repo_root" "$primary_branch_before" "$branch_name" "$worktree_path"; then
-    echo "[agent-branch-start] Warning: automatic protected-branch change migration did not fully complete." >&2
-  fi
+if ! initialize_openspec_change_workspace "$repo_root" "$worktree_path" "$openspec_change_slug" "$openspec_capability_slug"; then
+  exit 1
 fi
-
-run_startup_context_artifacts "$repo_root" "$worktree_path" "$branch_name" "$BASE_BRANCH" "$PR_REF" "$GH_REPO_REF"
-record_worktree_bootstrap_manifest "$worktree_path" "$branch_name" "$BASE_BRANCH" "$openspec_change_slug" "$openspec_plan_slug" "$TIER_LEVEL"
-
-primary_branch_after="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-if [[ -n "$primary_branch_before" && "$primary_branch_before" != "HEAD" && "$primary_branch_after" != "$primary_branch_before" ]]; then
-  echo "[agent-branch-start] Warning: primary checkout moved from '${primary_branch_before}' to '${primary_branch_after}'. Restoring '${primary_branch_before}'."
-  git -C "$repo_root" checkout -q "$primary_branch_before"
-  primary_branch_after="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-  if [[ "$primary_branch_after" != "$primary_branch_before" ]]; then
-    echo "[agent-branch-start] Failed to restore primary checkout branch '${primary_branch_before}'." >&2
-    exit 1
-  fi
+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] Tier: ${TIER_LEVEL}"
-if [[ "$helper_branch_assist_mode" -eq 1 ]]; then
-  echo "[agent-branch-start] OpenSpec change: skipped (helper branch assisting ${BASE_BRANCH})"
-  echo "[agent-branch-start] OpenSpec plan: skipped (helper branch assisting ${BASE_BRANCH})"
-else
-  if [[ "$OPENSPEC_CHANGE_INIT" -eq 1 ]]; then
-    if [[ "$OPENSPEC_CHANGE_MINIMAL" -eq 1 ]]; then
-      echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug} (minimal / notes-only)"
-    else
-      echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
-    fi
-  else
-    echo "[agent-branch-start] OpenSpec change: skipped (tier ${TIER_LEVEL})"
-  fi
-  if [[ "$OPENSPEC_PLAN_INIT" -eq 1 ]]; then
-    echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
-  else
-    echo "[agent-branch-start] OpenSpec plan: skipped (tier ${TIER_LEVEL})"
-  fi
-fi
+echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
+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...>"
 echo "  # implement + commit"
-echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup"
+echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base dev --via-pr --wait-for-merge"