@mmerterden/multi-agent-pipeline 11.4.0 → 12.0.0

package/pipeline/scripts/phase-tracker.sh

@@ -289,6 +289,61 @@ save_state() {
   mv "${TRACKER_FILE}.tmp" "$TRACKER_FILE"
 }
 
+# --- read-modify-write lock ---------------------------------------------------
+# tmp+rename makes each save atomic, but two concurrent invocations (e.g. two
+# parallel Phase 4 reviewers reporting `tokens`) both load the same state and
+# the second save silently drops the first delta. Guard every load->save
+# sequence with a portable mkdir spinlock (macOS bash 3.2: no flock builtin).
+# The wait is bounded and the lock FAILS OPEN with a warning so a stuck lock
+# can never hang the pipeline; a dead owner pid or a lock older than 30s is
+# reclaimed.
+TRACKER_LOCK_DIR=""
+TRACKER_LOCK_HELD=0
+
+state_lock_stale() {
+  local pid mtime now age
+  pid=$(cat "$TRACKER_LOCK_DIR/pid" 2>/dev/null || true)
+  if [ -n "$pid" ]; then
+    kill -0 "$pid" 2>/dev/null && return 1
+    return 0
+  fi
+  mtime=$(stat -f %m "$TRACKER_LOCK_DIR" 2>/dev/null || stat -c %Y "$TRACKER_LOCK_DIR" 2>/dev/null || echo "")
+  [ -z "$mtime" ] && return 1
+  now=$(date +%s)
+  age=$((now - mtime))
+  [ "$age" -gt 30 ]
+}
+
+acquire_state_lock() {
+  TRACKER_LOCK_DIR="${TRACKER_FILE}.lock"
+  mkdir -p "$TRACKER_DIR" 2>/dev/null
+  local tries=0
+  # ~5s bound: 50 tries x 0.1s.
+  while ! mkdir "$TRACKER_LOCK_DIR" 2>/dev/null; do
+    if state_lock_stale; then
+      rm -rf "$TRACKER_LOCK_DIR" 2>/dev/null
+      continue
+    fi
+    tries=$((tries + 1))
+    if [ "$tries" -ge 50 ]; then
+      echo "phase-tracker: WARN  -  state lock busy ($TRACKER_LOCK_DIR); proceeding without lock" >&2
+      return 0
+    fi
+    sleep 0.1
+  done
+  echo "$$" > "$TRACKER_LOCK_DIR/pid" 2>/dev/null
+  TRACKER_LOCK_HELD=1
+}
+
+release_state_lock() {
+  if [ "$TRACKER_LOCK_HELD" = "1" ]; then
+    rm -rf "$TRACKER_LOCK_DIR" 2>/dev/null
+    TRACKER_LOCK_HELD=0
+  fi
+}
+# Never leave a lock behind if a mutating action dies mid-critical-section.
+trap release_state_lock EXIT
+
 render() {
   need_jq
   local state
@@ -509,8 +564,10 @@ case "$ACTION" in
     TRACKER_DIR="$(dirname "$TRACKER_FILE")"
     mkdir -p "$TRACKER_DIR" 2>/dev/null
     NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    acquire_state_lock
     save_state "$(jq -nc --arg id "$TASK_ID" --arg ts "$NOW" \
       '{task_id:$id,started_at:$ts,phases:[]}')"
+    release_state_lock
     # Update pointer so subsequent calls without env can find this tracker.
     # NOTE: the pointer is global; for concurrent runs on the same user account,
     # callers should set MULTI_AGENT_TASK_ID in their shell or prefix every
@@ -528,6 +585,7 @@ case "$ACTION" in
     need_jq
     [ "$#" -ge 2 ] || { echo "add needs <phase_id> <name>" >&2; exit 64; }
     PID="$1"; PNAME="$2"
+    acquire_state_lock
     state=$(load_state)
     # Idempotent: a phase id that already exists is a no-op (name, status, and
     # token history are preserved). This is what lets continuation commands
@@ -538,6 +596,7 @@ case "$ACTION" in
       else .phases += [{"id":$id,"name":$name,"status":"pending","subs":[]}]
       end')
     save_state "$new"
+    release_state_lock
     render
     ;;
 
@@ -550,6 +609,7 @@ case "$ACTION" in
       *) echo "bad status: $STATUS" >&2; exit 64 ;;
     esac
     NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    acquire_state_lock
     state=$(load_state)
     # Set status, stamp started_at on first transition to in_progress,
     # stamp completed_at on transition to terminal states (completed/failed/skipped).
@@ -563,6 +623,7 @@ case "$ACTION" in
       )
     ')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.update" "$PID" "$STATUS" "{\"multi_agent.status\": \"$STATUS\"}"
     render
     ;;
@@ -575,6 +636,7 @@ case "$ACTION" in
       pending|in_progress|completed|failed|skipped) ;;
       *) echo "bad status: $SSTATUS" >&2; exit 64 ;;
     esac
+    acquire_state_lock
     state=$(load_state)
     # If sub with this id exists under this phase, update; else append.
     new=$(echo "$state" | jq \
@@ -590,6 +652,7 @@ case "$ACTION" in
         else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.sub" "$PID" "$SNAME" "{\"multi_agent.sub_id\": \"$SID\", \"multi_agent.status\": \"$SSTATUS\"}"
     render
     ;;
@@ -602,6 +665,7 @@ case "$ACTION" in
     case "$T_IN$T_OUT$T_CACHED" in
       *[!0-9]*) echo "tokens: in/out/cached must be non-negative integers" >&2; exit 64 ;;
     esac
+    acquire_state_lock
     state=$(load_state)
     # Additive: add to existing totals so multiple LLM calls accumulate.
     new=$(echo "$state" | jq --arg id "$PID" --argjson ti "$T_IN" --argjson to "$T_OUT" --argjson tc "$T_CACHED" '
@@ -614,6 +678,7 @@ case "$ACTION" in
       )
     ')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.tokens" "$PID" "" "{\"multi_agent.tokens_in_delta\": $T_IN, \"multi_agent.tokens_out_delta\": $T_OUT, \"multi_agent.tokens_cached_delta\": $T_CACHED}"
     # Re-render so live token count is visible on the active phase. Callers
     # that want silent accumulation (e.g. tight loops) can suppress with
@@ -627,6 +692,7 @@ case "$ACTION" in
     need_jq
     [ "$#" -ge 3 ] || { echo "meta needs <phase_id> <key> <value>" >&2; exit 64; }
     PID="$1"; KEY="$2"; VALUE="$3"
+    acquire_state_lock
     state=$(load_state)
     new=$(echo "$state" | jq --arg id "$PID" --arg k "$KEY" --arg v "$VALUE" '
       .phases |= map(
@@ -635,6 +701,7 @@ case "$ACTION" in
         else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.meta" "$PID" "$KEY" "{\"multi_agent.meta_key\": \"$KEY\", \"multi_agent.meta_value\": \"$VALUE\"}"
     if [ "${TRACKER_QUIET:-0}" != "1" ]; then
       render
@@ -645,12 +712,14 @@ case "$ACTION" in
     need_jq
     [ "$#" -ge 2 ] || { echo "model needs <phase_id> <model_name>" >&2; exit 64; }
     PID="$1"; MODEL="$2"
+    acquire_state_lock
     state=$(load_state)
     new=$(echo "$state" | jq --arg id "$PID" --arg m "$MODEL" '
       .phases |= map(
         if .id == $id then .model = $m else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.model" "$PID" "" "{\"multi_agent.model\": \"$MODEL\"}"
     if [ "${TRACKER_QUIET:-0}" != "1" ]; then
       render
@@ -667,12 +736,14 @@ case "$ACTION" in
     if [ "${#TEXT}" -gt 60 ]; then
       TEXT="${TEXT:0:59}…"
     fi
+    acquire_state_lock
     state=$(load_state)
     new=$(echo "$state" | jq --arg id "$PID" --arg v "$TEXT" '
       .phases |= map(
         if .id == $id then .meta = ((.meta // {}) + {"Now": $v}) else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.now" "$PID" "$TEXT" "{}"
     ;;
 

package/pipeline/scripts/pre-commit-check.sh

@@ -5,6 +5,45 @@
 
 set -uo pipefail
 
+# Hook-mode fast exit. The Claude Code PreToolUse matcher is the tool name
+# ("Bash"), so this script now fires for EVERY Bash call and receives JSON on
+# stdin: {"tool_name":"Bash","tool_input":{"command":"..."}}. Extract the
+# command and exit 0 immediately unless it actually invokes `git commit`.
+# Direct invocations (empty/non-JSON stdin, e.g. smoke tests or manual runs)
+# fall through to the full scan. Extraction failure also falls through - the
+# only cost is an unnecessary scan, never a skipped one on a real commit.
+if [ ! -t 0 ]; then
+  HOOK_INPUT="$(cat 2>/dev/null || true)"
+  if [ -n "$HOOK_INPUT" ]; then
+    HOOK_COMMAND=""
+    if command -v python3 >/dev/null 2>&1; then
+      HOOK_COMMAND="$(printf '%s' "$HOOK_INPUT" | python3 -c '
+import json, sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("command", ""))
+except Exception:
+    pass
+' 2>/dev/null || true)"
+    elif command -v node >/dev/null 2>&1; then
+      HOOK_COMMAND="$(printf '%s' "$HOOK_INPUT" | node -e '
+let raw = "";
+process.stdin.on("data", (c) => (raw += c));
+process.stdin.on("end", () => {
+  try {
+    process.stdout.write(String(JSON.parse(raw)?.tool_input?.command ?? ""));
+  } catch { /* fall through to full scan */ }
+});
+' 2>/dev/null || true)"
+    fi
+    if [ -n "$HOOK_COMMAND" ]; then
+      if ! printf '%s\n' "$HOOK_COMMAND" \
+        | grep -qE '(^|[^[:alnum:]_./-])git[[:space:]]+([^|&;]*[[:space:]])?commit([^[:alnum:]_-]|$)'; then
+        exit 0
+      fi
+    fi
+  fi
+fi
+
 if [ -z "$(git diff --cached --name-only 2>/dev/null)" ]; then
   exit 0
 fi

package/pipeline/scripts/prune-logs.sh

@@ -7,17 +7,26 @@
 # These accumulate forever. This prunes whole task dirs, with optional age /
 # project / task filters.
 #
-# PRESERVED ALWAYS: the audit trail (audit.jsonl, audit.*.jsonl*) and the
-# metrics corpus (metrics.jsonl, metrics-summary.md) live at the log-root TOP
-# level, not inside task dirs - this only ever removes task dirs, so those are
-# never touched. .counter files (per-project task numbering) also survive.
+# PRESERVED ALWAYS: the audit trail (audit.jsonl + rotations), the metrics
+# corpus (metrics.jsonl, metrics-summary.md), and .counter files (per-project
+# task numbering). They live outside task dirs, and as a second line of
+# defense any directory carrying one of those reserved names is skipped even
+# if it looks like a task dir.
 #
-# SAFE BY DEFAULT: dry-run. Lists what WOULD be removed + space freed; deletes
-# nothing until you pass --yes.
+# SAFE BY DEFAULT:
+#   - dry-run: lists what WOULD be removed + space freed; deletes nothing
+#     until you pass --yes.
+#   - root guard: the log root must be an existing directory and is refused
+#     when it resolves to /, $HOME, or a git work tree (a repo checkout is
+#     never a log root).
+#   - active-task grace: task dirs with files modified in the last
+#     PRUNE_GRACE_MIN minutes (default 10) are spared, so pruning while a
+#     run is still writing its log dir cannot break resume. An explicit
+#     --task=ID bypasses the grace; PRUNE_GRACE_MIN=0 disables it.
 #
 # Usage:
-#   prune-logs.sh                       # dry-run: every task dir
-#   prune-logs.sh --yes                 # delete every task dir
+#   prune-logs.sh                       # dry-run: every idle task dir
+#   prune-logs.sh --yes                 # delete every idle task dir
 #   prune-logs.sh --older-than=30       # only task dirs older than 30 days
 #   prune-logs.sh --project=my-ios-app  # only one project's task dirs
 #   prune-logs.sh --task=PROJ-123       # only one task dir
@@ -25,12 +34,14 @@
 #
 # Env:
 #   PRUNE_LOG_ROOT   override the log root (default $HOME/.claude/logs/multi-agent)
+#   PRUNE_GRACE_MIN  active-task grace window in minutes (default 10, 0 = off)
 #
-# Exit: 0 on success, 2 on usage error.
+# Exit: 0 on success, 2 on usage error or refused log root.
 
 set -uo pipefail
 
 LOG_ROOT="${PRUNE_LOG_ROOT:-$HOME/.claude/logs/multi-agent}"
+GRACE_MIN="${PRUNE_GRACE_MIN:-10}"
 DELETE=0
 OLDER_DAYS=0
 PROJECT=""
@@ -40,6 +51,13 @@ usage() {
   grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
 }
 
+# --project / --task values are compared against path components; only plain
+# names are meaningful. Rejects empty, ".", "..", anything with a slash, and
+# anything starting with "." or "-".
+valid_id() {
+  printf '%s' "$1" | grep -qE '^[A-Za-z0-9][A-Za-z0-9._-]*$'
+}
+
 for arg in "$@"; do
   case "$arg" in
     --yes | --force) DELETE=1 ;;
@@ -50,8 +68,20 @@ for arg in "$@"; do
         exit 2
       fi
       ;;
-    --project=*) PROJECT="${arg#*=}" ;;
-    --task=*) TASK="${arg#*=}" ;;
+    --project=*)
+      PROJECT="${arg#*=}"
+      if ! valid_id "$PROJECT"; then
+        echo "prune-logs: --project needs a plain directory name (letters/digits then . _ -), got: '$PROJECT'" >&2
+        exit 2
+      fi
+      ;;
+    --task=*)
+      TASK="${arg#*=}"
+      if ! valid_id "$TASK"; then
+        echo "prune-logs: --task needs a plain directory name (letters/digits then . _ -), got: '$TASK'" >&2
+        exit 2
+      fi
+      ;;
     -h | --help)
       usage
       exit 0
@@ -63,11 +93,29 @@ for arg in "$@"; do
   esac
 done
 
+if ! printf '%s' "$GRACE_MIN" | grep -qE '^[0-9]+$'; then
+  echo "prune-logs: PRUNE_GRACE_MIN needs a whole number of minutes, got: $GRACE_MIN" >&2
+  exit 2
+fi
+
 if [ ! -d "$LOG_ROOT" ]; then
   echo "prune-logs: no log root at $LOG_ROOT  -  nothing to do"
   exit 0
 fi
 
+# Root guard: resolve symlinks, then refuse roots that can never be a log
+# root. Everything removed below sits strictly inside this resolved path.
+LOG_ROOT="$(cd "$LOG_ROOT" 2>/dev/null && pwd -P)"
+if [ -z "$LOG_ROOT" ]; then
+  echo "prune-logs: cannot resolve log root" >&2
+  exit 2
+fi
+HOME_REAL="$(cd "$HOME" 2>/dev/null && pwd -P || printf '%s' "$HOME")"
+if [ "$LOG_ROOT" = "/" ] || [ "$LOG_ROOT" = "$HOME_REAL" ] || [ -e "$LOG_ROOT/.git" ]; then
+  echo "prune-logs: refusing log root $LOG_ROOT (/, \$HOME, or a git work tree is never a log root)" >&2
+  exit 2
+fi
+
 # A task dir is any dir (depth 1-2 under the root) carrying a run marker.
 is_task_dir() {
   local d="$1"
@@ -75,23 +123,47 @@ is_task_dir() {
     [ -f "$d/agent-log.md" ] || [ -f "$d/otel-spans.jsonl" ]
 }
 
+# Names promised to survive pruning. A directory carrying one of these names
+# is never a legitimate task dir, so it is skipped outright.
+is_reserved_name() {
+  case "$1" in
+    audit.jsonl | audit.*.jsonl* | audit.jsonl.* | metrics.jsonl | metrics-summary.md | .counter | *.counter) return 0 ;;
+  esac
+  return 1
+}
+
 MTIME_ARGS=()
 if [ "$OLDER_DAYS" -gt 0 ]; then
   MTIME_ARGS=(-mtime "+$OLDER_DAYS")
 fi
 
 matches=()
+skipped_active=0
 while IFS= read -r -d '' d; do
+  base="$(basename "$d")"
+  if is_reserved_name "$base"; then continue; fi
   is_task_dir "$d" || continue
   # --task: dir name must equal the task id
-  if [ -n "$TASK" ] && [ "$(basename "$d")" != "$TASK" ]; then continue; fi
+  if [ -n "$TASK" ] && [ "$base" != "$TASK" ]; then continue; fi
   # --project: the immediate parent dir name must equal the project
   if [ -n "$PROJECT" ] && [ "$(basename "$(dirname "$d")")" != "$PROJECT" ]; then continue; fi
+  # Active-task grace: spare dirs a run touched in the last GRACE_MIN minutes
+  # so a concurrent run keeps a resumable log dir. --task is an explicit,
+  # deliberate target and bypasses the grace.
+  if [ "$GRACE_MIN" -gt 0 ] && [ -z "$TASK" ] &&
+    find "$d" -mmin "-$GRACE_MIN" -print 2>/dev/null | head -1 | grep -q .; then
+    skipped_active=$((skipped_active + 1))
+    continue
+  fi
   matches+=("$d")
 done < <(find "$LOG_ROOT" -mindepth 1 -maxdepth 2 -type d ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
 
 if [ "${#matches[@]}" -eq 0 ]; then
-  echo "prune-logs: no task logs matched under $LOG_ROOT  -  nothing to do"
+  if [ "$skipped_active" -gt 0 ]; then
+    echo "prune-logs: only active task dirs matched (touched in the last ${GRACE_MIN}m)  -  spared, nothing to do"
+  else
+    echo "prune-logs: no task logs matched under $LOG_ROOT  -  nothing to do"
+  fi
   exit 0
 fi
 
@@ -106,13 +178,26 @@ human="${total_kb} KB"
 if [ "$DELETE" -eq 0 ]; then
   echo "DRY-RUN  -  would remove ${#matches[@]} task log dir(s) (frees ~${human}):"
   for d in "${matches[@]}"; do echo "  ${d#"$LOG_ROOT"/}"; done
+  [ "$skipped_active" -gt 0 ] && echo "Spared $skipped_active active dir(s) touched in the last ${GRACE_MIN}m."
   echo "Audit trail + metrics corpus are preserved. Re-run with --yes to delete."
   exit 0
 fi
 
 removed=0
 for d in "${matches[@]}"; do
-  rm -rf "$d" 2>/dev/null && removed=$((removed + 1))
+  # Containment guard: resolve the target and require it strictly inside the
+  # resolved log root before rm -rf.
+  target="$(cd "$d" 2>/dev/null && pwd -P)" || continue
+  case "$target" in
+    "$LOG_ROOT"/*) ;;
+    *)
+      echo "prune-logs: skipping path outside log root: $d" >&2
+      continue
+      ;;
+  esac
+  rm -rf "$target" 2>/dev/null && removed=$((removed + 1))
 done
-echo "══ prune-logs: removed ${removed}/${#matches[@]} task log dir(s), freed ~${human} (audit + metrics preserved) ══"
+spared_note=""
+[ "$skipped_active" -gt 0 ] && spared_note=", spared $skipped_active active"
+echo "══ prune-logs: removed ${removed}/${#matches[@]} task log dir(s)${spared_note}, freed ~${human} (audit + metrics preserved) ══"
 exit 0

package/pipeline/scripts/purge.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# purge.sh  -  deletion backend for /multi-agent:purge (full reset).
+#
+# Wipes every multi-agent worktree under <repo>/.worktrees/ (registered or
+# orphaned), deletes the local branches those worktrees carried, and resets
+# the project's task counter at
+#   $HOME/.claude/logs/multi-agent/<project>/.counter
+#
+# The confirmation UX (double confirmation, remote-branch question) lives in
+# the /multi-agent:purge skill; this script is the mechanical part. Task log
+# dirs are /multi-agent:prune-logs territory (prune-logs.sh --project=<name>).
+#
+# PRESERVED ALWAYS:
+#   - the repo's main worktree, its checked-out branch, and main/master/develop
+#   - everything outside <repo>/.worktrees/ (symlinked entries are never
+#     followed; every rm target must resolve strictly inside .worktrees/)
+#   - the audit trail + metrics corpus at the log root (only the project's
+#     .counter file is removed there)
+#
+# SAFE BY DEFAULT: dry-run. Lists what WOULD be removed; deletes nothing until
+# you pass --yes. Remote branches are deleted only with --delete-remote AND
+# --yes; a missing/unreachable remote is a warning, not a failure.
+#
+# Usage:
+#   purge.sh                        # dry-run in the current repo
+#   purge.sh --yes                  # wipe worktrees + branches + counter
+#   purge.sh --repo <path>          # operate on another repo
+#   purge.sh --delete-remote --yes  # also delete the remote branches
+#
+# Env:
+#   PURGE_LOG_ROOT   override the log root (default $HOME/.claude/logs/multi-agent)
+#
+# Exit: 0 on success (including "nothing to do"), 2 on usage error or refused
+# repo.
+
+set -uo pipefail
+
+REPO="$PWD"
+DELETE=0
+DELETE_REMOTE=0
+LOG_ROOT="${PURGE_LOG_ROOT:-$HOME/.claude/logs/multi-agent}"
+
+usage() {
+  grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes | --force) DELETE=1; shift ;;
+    --delete-remote) DELETE_REMOTE=1; shift ;;
+    --repo)
+      REPO="${2:-}"
+      [ -z "$REPO" ] && { echo "purge: --repo needs a path" >&2; exit 2; }
+      shift 2
+      ;;
+    -h | --help) usage; exit 0 ;;
+    *) echo "purge: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "purge: $REPO is not a git work tree  -  nothing to do"
+  exit 0
+fi
+
+# Anchor everything on the MAIN worktree (first porcelain entry), so running
+# purge from inside a linked worktree still targets <repo>/.worktrees/.
+MAIN_WT="$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -1)"
+MAIN_WT="$(cd "$MAIN_WT" 2>/dev/null && pwd -P)"
+HOME_REAL="$(cd "$HOME" 2>/dev/null && pwd -P || printf '%s' "$HOME")"
+if [ -z "$MAIN_WT" ] || [ "$MAIN_WT" = "/" ] || [ "$MAIN_WT" = "$HOME_REAL" ]; then
+  echo "purge: refusing to operate on repo root '$MAIN_WT'" >&2
+  exit 2
+fi
+WT_ROOT="$MAIN_WT/.worktrees"
+CURRENT_BRANCH="$(git -C "$MAIN_WT" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+
+# Branches that must survive a purge no matter what a worktree carried.
+is_protected_branch() {
+  case "$1" in
+    "" | main | master | develop | "$CURRENT_BRANCH") return 0 ;;
+  esac
+  return 1
+}
+
+resolve_dir() {
+  cd "$1" 2>/dev/null && pwd -P
+}
+
+# Collect registered worktrees that live strictly inside .worktrees/, with
+# the branch each carries (empty when detached). bash 3.2: parallel arrays.
+wt_paths=()
+wt_branches=()
+cur_path=""
+cur_branch=""
+flush_block() {
+  [ -z "$cur_path" ] && { cur_branch=""; return 0; }
+  local resolved
+  resolved="$(resolve_dir "$cur_path")"
+  case "$resolved" in
+    "$WT_ROOT"/*)
+      wt_paths+=("$resolved")
+      wt_branches+=("$cur_branch")
+      ;;
+  esac
+  cur_path=""
+  cur_branch=""
+}
+while IFS= read -r line; do
+  case "$line" in
+    worktree\ *) flush_block; cur_path="${line#worktree }" ;;
+    branch\ refs/heads/*) cur_branch="${line#branch refs/heads/}" ;;
+  esac
+done <<EOF
+$(git -C "$MAIN_WT" worktree list --porcelain 2>/dev/null)
+EOF
+flush_block
+
+# Orphan dirs under .worktrees/ that git no longer registers.
+orphans=()
+if [ -d "$WT_ROOT" ]; then
+  for d in "$WT_ROOT"/*/; do
+    [ -d "$d" ] || continue
+    [ -L "${d%/}" ] && continue # never follow symlinked entries out of the tree
+    dir="$(resolve_dir "$d")"
+    [ -z "$dir" ] && continue
+    case "$dir" in "$WT_ROOT"/*) ;; *) continue ;; esac
+    reg=0
+    for p in ${wt_paths+"${wt_paths[@]}"}; do
+      [ "$p" = "$dir" ] && { reg=1; break; }
+    done
+    [ "$reg" -eq 1 ] && continue
+    orphans+=("$dir")
+  done
+fi
+
+# Counter file for this project.
+PROJECT="$(basename "$MAIN_WT")"
+COUNTER=""
+if [ -n "$PROJECT" ] && [ "$PROJECT" != "." ] && [ "$PROJECT" != ".." ] &&
+  [ -f "$LOG_ROOT/$PROJECT/.counter" ]; then
+  COUNTER="$LOG_ROOT/$PROJECT/.counter"
+fi
+
+total=$((${#wt_paths[@]} + ${#orphans[@]}))
+if [ "$total" -eq 0 ] && [ -z "$COUNTER" ]; then
+  echo "purge: no multi-agent worktrees, branches, or counter in $MAIN_WT  -  nothing to do"
+  exit 0
+fi
+
+if [ "$DELETE" -eq 0 ]; then
+  echo "DRY-RUN  -  purge would remove from $MAIN_WT:"
+  i=0
+  while [ "$i" -lt "${#wt_paths[@]}" ]; do
+    br="${wt_branches[$i]}"
+    echo "  worktree ${wt_paths[$i]#"$MAIN_WT"/} (branch: ${br:-detached})"
+    if ! is_protected_branch "$br"; then
+      echo "  local branch $br"
+      [ "$DELETE_REMOTE" -eq 1 ] && echo "  remote branch origin/$br"
+    fi
+    i=$((i + 1))
+  done
+  for d in ${orphans+"${orphans[@]}"}; do
+    echo "  orphan worktree dir ${d#"$MAIN_WT"/}"
+  done
+  [ -n "$COUNTER" ] && echo "  task counter $COUNTER"
+  echo "Main worktree, current branch, and main/master/develop are never touched."
+  echo "Re-run with --yes to delete."
+  exit 0
+fi
+
+removed_wt=0
+removed_br=0
+i=0
+while [ "$i" -lt "${#wt_paths[@]}" ]; do
+  p="${wt_paths[$i]}"
+  br="${wt_branches[$i]}"
+  i=$((i + 1))
+  wt_gone=0
+  if git -C "$MAIN_WT" worktree remove --force "$p" >/dev/null 2>&1; then
+    wt_gone=1
+  else
+    # Fall back to a guarded rm + prune when git refuses (locked, damaged).
+    case "$p" in
+      "$WT_ROOT"/*)
+        rm -rf "$p" 2>/dev/null && wt_gone=1
+        git -C "$MAIN_WT" worktree prune >/dev/null 2>&1
+        ;;
+      *) echo "purge: skipping worktree outside $WT_ROOT: $p" >&2 ;;
+    esac
+  fi
+  if [ "$wt_gone" -eq 1 ]; then
+    removed_wt=$((removed_wt + 1))
+    echo "→ removed worktree ${p#"$MAIN_WT"/}"
+  else
+    echo "purge: warning: could not remove worktree $p" >&2
+    continue
+  fi
+  if is_protected_branch "$br"; then
+    [ -n "$br" ] && echo "→ kept protected branch $br"
+    continue
+  fi
+  if git -C "$MAIN_WT" branch -D "$br" >/dev/null 2>&1; then
+    removed_br=$((removed_br + 1))
+    echo "→ deleted local branch $br"
+  fi
+  if [ "$DELETE_REMOTE" -eq 1 ]; then
+    if git -C "$MAIN_WT" push origin --delete "$br" >/dev/null 2>&1; then
+      echo "→ deleted remote branch origin/$br"
+    else
+      echo "purge: warning: could not delete remote branch origin/$br (no remote?)" >&2
+    fi
+  fi
+done
+
+for d in ${orphans+"${orphans[@]}"}; do
+  # Containment guard: resolve again right before rm.
+  dir="$(resolve_dir "$d")"
+  case "$dir" in
+    "$WT_ROOT"/*)
+      rm -rf "$dir" 2>/dev/null && { removed_wt=$((removed_wt + 1)); echo "→ removed orphan worktree dir ${dir#"$MAIN_WT"/}"; }
+      ;;
+    *) echo "purge: skipping orphan outside $WT_ROOT: $d" >&2 ;;
+  esac
+done
+
+if [ -n "$COUNTER" ]; then
+  rm -f "$COUNTER" 2>/dev/null && echo "→ reset task counter $COUNTER"
+fi
+
+# Drop the now-empty .worktrees/ shell (only when truly empty).
+[ -d "$WT_ROOT" ] && rmdir "$WT_ROOT" 2>/dev/null
+
+echo "══ purge: removed $removed_wt worktree(s) and $removed_br local branch(es) in $MAIN_WT ══"
+exit 0