@imdeadpool/guardex 6.0.0 → 6.1.0

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

@@ -6,10 +6,17 @@ AGENT_NAME="agent"
 BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 WORKTREE_ROOT_REL=".omx/agent-worktrees"
-OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
+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_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
@@ -36,6 +43,31 @@ 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
@@ -46,7 +78,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     -*)
       echo "[agent-branch-start] Unknown option: $1" >&2
-      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&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
       exit 1
       ;;
     *)
@@ -58,7 +90,7 @@ done
 
 if [[ "${#POSITIONAL_ARGS[@]}" -gt 3 ]]; then
   echo "[agent-branch-start] Too many positional arguments." >&2
-  echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&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
   exit 1
 fi
 
@@ -131,23 +163,124 @@ checksum_slug_suffix() {
 }
 
 compose_branch_descriptor() {
-  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")"
+  local task_slug="$1"
+  local task_max task_part checksum_part
   task_max="$(normalize_positive_int "${GUARDEX_BRANCH_TASK_SLUG_MAX:-36}" "36")"
   task_part="$(shorten_slug "$task_slug" "$task_max")"
-  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
   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"
+    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"
+}
+
 normalize_bool() {
   local raw="${1:-}"
   local fallback="${2:-0}"
@@ -162,6 +295,63 @@ 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"
@@ -224,6 +414,54 @@ 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
@@ -246,6 +484,51 @@ 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"
@@ -303,7 +586,7 @@ initialize_openspec_plan_workspace() {
 
   hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh"
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "${OPENSPEC_PLAN_INIT:-$OPENSPEC_AUTO_INIT}" -ne 1 ]]; then
     return 0
   fi
 
@@ -338,6 +621,7 @@ 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"
 
@@ -358,7 +642,8 @@ initialize_openspec_change_workspace() {
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+    GUARDEX_OPENSPEC_MINIMAL="${OPENSPEC_CHANGE_MINIMAL:-0}" \
+      bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" "$branch_name" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[agent-branch-start] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
@@ -371,6 +656,459 @@ 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
@@ -386,20 +1124,39 @@ 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
-    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
+    if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
       BASE_BRANCH="$current_branch"
     else
-      BASE_BRANCH="dev"
+      BASE_BRANCH="$(resolve_default_base_branch_for_agent_subbranch "$repo_root" "$protected_branches_raw" || printf '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}"
@@ -412,72 +1169,74 @@ else
 fi
 
 task_slug="$(sanitize_slug "$TASK_NAME" "task")"
-agent_slug_raw="$(sanitize_slug "$AGENT_NAME" "agent")"
-agent_slug="$(shorten_slug "$agent_slug_raw" "${GUARDEX_BRANCH_AGENT_SLUG_MAX:-24}")"
+agent_type="$(normalize_agent_type "$AGENT_NAME")"
 snapshot_name="$(resolve_active_codex_snapshot_name)"
-snapshot_slug="$(sanitize_optional_slug "$snapshot_name" "snapshot")"
-branch_descriptor="$(compose_branch_descriptor "$snapshot_slug" "$task_slug")"
+nickname="$(extract_nickname "$snapshot_name")"
+agent_slug="${agent_type}-${nickname}"
+branch_descriptor="$(compose_branch_descriptor "$task_slug")"
 timestamp="$(date +%Y%m%d-%H%M%S)"
 branch_name_base="agent/${agent_slug}/${branch_descriptor}"
 
-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
+if [[ "$PRINT_NAME_ONLY" -eq 1 ]]; then
+  printf '%s\n' "$branch_name_base"
+  exit 0
+fi
 
+branch_name="$branch_name_base"
 worktree_root="${repo_root}/${WORKTREE_ROOT_REL}"
 mkdir -p "$worktree_root"
-worktree_path="${worktree_root}/${branch_name//\//__}"
+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
+
 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")"
 
-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)"
+primary_branch_before="$(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
+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 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="$(
-        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
+    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)."
     fi
   fi
 fi
 
-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 [[ "$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
 
-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
+  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
 fi
 
@@ -485,19 +1244,61 @@ 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"
-if ! initialize_openspec_change_workspace "$repo_root" "$worktree_path" "$openspec_change_slug" "$openspec_capability_slug"; then
-  exit 1
+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
-if ! initialize_openspec_plan_workspace "$repo_root" "$worktree_path" "$openspec_plan_slug"; then
-  exit 1
+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
+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
 fi
 
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
-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] 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] 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 dev --via-pr --wait-for-merge"
+echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup"