@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/scripts/gc-abandoned.sh

@@ -14,10 +14,15 @@
 #   1. A run WAITING FOR YOU is never reaped. An open PR, the Commit or Report
 #      phase, or `status: awaiting_input` means the work landed and the pipeline
 #      is holding for an answer by design. That is finished work, not residue.
+#      A run parked with `verificationFailed` or `waitingFor` is held the same
+#      way, even though a rejected verification records `status: failed`.
 #   2. A path that is not strictly inside `<repo>/.worktrees/` is never removed.
 #      This is not theoretical: four state files on that machine record
 #      `worktreePath` as the REPO ROOT, so a sweep that trusted the field would
-#      have deleted the checkout.
+#      have deleted the checkout. Inside `.worktrees/`, only a path that
+#      `git worktree list --porcelain` reports as a worktree top level is a
+#      candidate, and it is removed only by `git worktree remove`; when git
+#      refuses, the directory stays and the report says `remove-failed`.
 #   3. Uncommitted work is never destroyed. It goes into a STASH ENTRY labelled
 #      `autopilot/abandoned/<task-id>` - `git stash list` finds it - and the
 #      directory is left in place, which costs disk and keeps the work. Losing a
@@ -53,6 +58,14 @@
 #
 # SAFE BY DEFAULT: dry-run. Removes nothing until you pass --yes.
 #
+# `--only <file>` narrows both passes to the worktree paths listed in the file,
+# one per line. The continuous-mode runner uses it to hand over the worktrees it
+# created and nothing else: a run it did not start is neither reported nor
+# touched, its state included. Pass 2 then walks the listed paths instead of
+# `--repos`, because a runner's repos can live anywhere on the disk.
+# `--report <file>` appends one JSON line per candidate - task, path, action,
+# reason, idle days, size - for a caller that renders its own report.
+#
 # Usage:
 #   gc-abandoned.sh                      # dry-run, default ages
 #   gc-abandoned.sh --yes                # apply
@@ -61,6 +74,8 @@
 #   gc-abandoned.sh --logs <dir>         # another state root (tests)
 #   gc-abandoned.sh --repos <dir>        # another checkout root (tests)
 #   gc-abandoned.sh --state-only         # pass 1 only
+#   gc-abandoned.sh --only <file>        # only the worktree paths listed in <file>
+#   gc-abandoned.sh --report <file>      # also append one JSON line per candidate
 #
 # Exit: 0 on success (including "nothing to do"), 2 on usage error.
 
@@ -72,6 +87,8 @@ DELETE=0
 DAYS=7
 PHASE0_DAYS=1
 STATE_ONLY=0
+ONLY=""
+REPORT=""
 
 usage() {
   grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
@@ -85,6 +102,8 @@ while [ "$#" -gt 0 ]; do
     --logs) LOGS="${2:-}"; shift 2 ;;
     --repos) REPOS="${2:-}"; shift 2 ;;
     --state-only) STATE_ONLY=1; shift ;;
+    --only) ONLY="${2:-}"; shift 2 ;;
+    --report) REPORT="${2:-}"; shift 2 ;;
     --abandoned) shift ;; # accepted so the command can forward its own flag
     -h | --help) usage; exit 0 ;;
     *) echo "gc-abandoned: unknown option $1" >&2; exit 2 ;;
@@ -94,6 +113,31 @@ done
 case "$DAYS$PHASE0_DAYS" in *[!0-9]*) echo "gc-abandoned: --days and --phase0-days take whole days" >&2; exit 2 ;; esac
 
 command -v jq >/dev/null 2>&1 || { echo "gc-abandoned: jq is required"; exit 0; }
+if [ -n "$ONLY" ] && [ ! -f "$ONLY" ]; then echo "gc-abandoned: --only file not found: $ONLY" >&2; exit 2; fi
+
+# Real paths, so a symlinked prefix (/var vs /private/var) cannot hide a match.
+ONLY_LIST=""
+if [ -n "$ONLY" ]; then
+  while IFS= read -r p || [ -n "$p" ]; do
+    [ -n "$p" ] || continue
+    r=$(cd "$p" 2>/dev/null && pwd -P) || r="$p"
+    ONLY_LIST="$ONLY_LIST
+$r"
+  done < "$ONLY"
+fi
+listed_only() { # $1 = real path; true when no --only list was given
+  [ -z "$ONLY" ] && return 0
+  [ -n "$1" ] || return 1
+  printf '%s\n' "$ONLY_LIST" | grep -qxF "$1"
+}
+
+emit() { # task path action reason idle_days size_kb pass
+  [ -n "$REPORT" ] || return 0
+  jq -nc --arg task "$1" --arg path "$2" --arg action "$3" --arg reason "$4" \
+    --argjson idle "${5:-0}" --argjson kb "${6:-0}" --argjson pass "$7" \
+    '{task:$task, path:$path, action:$action, reason:$reason, idleDays:$idle, sizeKb:$kb, pass:$pass}' \
+    >> "$REPORT" 2>/dev/null || true
+}
 [ -d "$LOGS" ] || { echo "gc-abandoned: nothing to do (no state at $LOGS)"; exit 0; }
 
 # The phase from which a stopped run is "waiting on you", not residue, is the
@@ -109,12 +153,35 @@ case "$WAITING_FROM" in *[!0-9]*|"") WAITING_FROM=4 ;; esac
 # and are load-bearing; it is the ordering that matters, not the platform.
 _mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo "$NOW"; }
 
+# A run gate-ledger.mjs parked for a person: `verificationFailed` (its own gate
+# rejected the work, written with `status: failed`) or `waitingFor` (a question).
+# Either holds its worktree for the person who looks, whatever `status` says.
+# True when $1 (a physical path) is the top level of a worktree registered with
+# the repo that holds its `.worktrees/` directory. Only such a path is ever
+# removed, and only through `git worktree remove`: a subdirectory of a worktree
+# or a directory made by hand under `.worktrees/` is not ours to delete, and git
+# run inside one would act on the parent checkout.
+registered_top() {
+  local repo="${1%%/.worktrees/*}" line top
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*)
+        top=$(cd "${line#worktree }" 2>/dev/null && pwd -P) || continue
+        [ "$top" = "$1" ] && return 0 ;;
+    esac
+  done < <(git -C "$repo" worktree list --porcelain 2>/dev/null)
+  return 1
+}
+
+HELD_JQ='if (.verificationFailed != null) or ((.waitingFor // "") != "") then "held" else "" end'
+
 NOW=$(date +%s)
 removed=0
 freed_kb=0
 kept_dirty=0
 skipped_waiting=0
 skipped_unsafe=0
+skipped_unregistered=0
 listed=0
 # Paths pass 1 has already decided about. Pass 2 must not revisit them: pass 1
 # stashes a dirty worktree and KEEPS it, which leaves the tree clean, and pass 2
@@ -147,9 +214,10 @@ while IFS= read -r state; do
   # and reaped. Read the shape, do not assume it.
   pr=$(jq -r 'if (.pr|type)=="string" then .pr elif (.pr|type)=="object" then (.pr.url // .pr.number // "") else "" end | tostring' "$state" 2>/dev/null || true)
   wt=$(jq -r '.worktreePath // ""' "$state" 2>/dev/null || true)
+  held=$(jq -r "$HELD_JQ" "$state" 2>/dev/null || true)
 
   # Rule 1: waiting for you is not residue.
-  if [ "$status" = "awaiting_input" ] || [ -n "$pr" ] || { [ "$phase" != "?" ] && [ "$phase" -ge "$WAITING_FROM" ] 2>/dev/null; }; then
+  if [ "$status" = "awaiting_input" ] || [ -n "$held" ] || [ -n "$pr" ] || { [ "$phase" != "?" ] && [ "$phase" -ge "$WAITING_FROM" ] 2>/dev/null; }; then
     skipped_waiting=$((skipped_waiting + 1))
     continue
   fi
@@ -171,11 +239,20 @@ while IFS= read -r state; do
     # A worktree path that no longer resolves is the ordinary case here.
     real=$(cd "$wt" 2>/dev/null && pwd -P || true)
     case "$real" in
-      */.worktrees/*) safe_wt="$real" ;;
+      */.worktrees/*)
+        if registered_top "$real"; then
+          safe_wt="$real"
+        else
+          skipped_unregistered=$((skipped_unregistered + 1))
+        fi ;;
       *) skipped_unsafe=$((skipped_unsafe + 1)) ;;
     esac
   fi
 
+  # --only: a run whose worktree is not on the list is not ours to judge,
+  # and that includes marking its state.
+  listed_only "$safe_wt" || continue
+
   size_kb=0
   [ -n "$safe_wt" ] && size_kb=$(du -sk "$safe_wt" 2>/dev/null | cut -f1)
 
@@ -192,10 +269,13 @@ $safe_wt"
   if [ "$DELETE" -eq 0 ]; then
     if [ "$dirty" -eq 1 ]; then
       printf '  would stash (uncommitted work): %s - %s, idle %sd, %s\n' "$task" "$kind" "$age_days" "$human"
+      emit "$task" "$safe_wt" would-stash "$kind" "$age_days" "${size_kb:-0}" 1
     elif [ -n "$safe_wt" ]; then
       printf '  would remove: %s - %s, idle %sd, %s\n' "$task" "$kind" "$age_days" "$human"
+      emit "$task" "$safe_wt" would-remove "$kind" "$age_days" "${size_kb:-0}" 1
     else
       printf '  would mark abandoned (no reapable worktree): %s - %s, idle %sd\n' "$task" "$kind" "$age_days"
+      emit "$task" "" would-mark "$kind" "$age_days" 0 1
     fi
     continue
   fi
@@ -219,19 +299,26 @@ $safe_wt"
     git -C "$safe_wt" stash push -u -m "$br" >/dev/null 2>&1 &&
       printf '→ stashed uncommitted work, worktree kept: %s (%s)\n' "$task" "$br" ||
       printf '→ could NOT stash, worktree kept untouched: %s\n' "$task"
+    emit "$task" "$safe_wt" stashed "$kind" "$age_days" "${size_kb:-0}" 1
     kept_dirty=$((kept_dirty + 1))
     continue
   fi
 
   if [ -n "$safe_wt" ]; then
     repo=${safe_wt%%/.worktrees/*}
-    git -C "$repo" worktree remove --force "$safe_wt" >/dev/null 2>&1 || rm -rf "$safe_wt"
+    if ! git -C "$repo" worktree remove --force "$safe_wt" >/dev/null 2>&1; then
+      printf '→ could NOT remove, worktree kept: %s\n' "$task"
+      emit "$task" "$safe_wt" remove-failed "$kind" "$age_days" "${size_kb:-0}" 1
+      continue
+    fi
     # Forgiven: one flaky prune must not end the sweep before its summary line.
     git -C "$repo" worktree prune >/dev/null 2>&1 || true
     printf '→ removed: %s (%s, idle %sd)\n' "$task" "$human" "$age_days"
+    emit "$task" "$safe_wt" removed "$kind" "$age_days" "${size_kb:-0}" 1
     freed_kb=$((freed_kb + ${size_kb:-0}))
   else
     printf '→ marked abandoned, no reapable worktree: %s\n' "$task"
+    emit "$task" "" marked "$kind" "$age_days" 0 1
   fi
   removed=$((removed + 1))
 done <<EOF
@@ -255,20 +342,37 @@ if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
       # a jq failure inside this subshell ends the loop, and the entries after
       # it would silently not exist - which reads as "no worktree matches" and
       # protects nothing.
-      jq -r '[(.worktreePath // ""), (.taskId // .jiraId // ""), (.status // ""), (if (.pr|type)=="string" then .pr elif (.pr|type)=="object" then (.pr.url // .pr.number // "") else "" end | tostring), ((.currentPhase // "") | tostring)] | @tsv' "$f" 2>/dev/null || true
+      jq -r '[(.worktreePath // ""), (.taskId // .jiraId // ""), (.status // ""), (if (.pr|type)=="string" then .pr elif (.pr|type)=="object" then (.pr.url // .pr.number // "") else "" end | tostring), ((.currentPhase // "") | tostring), ('"$HELD_JQ"')] | @tsv' "$f" 2>/dev/null || true
     done)
 
-  for wtroot in "$REPOS"/*/.worktrees; do
-    [ -d "$wtroot" ] || continue
-    [ -L "$wtroot" ] && continue
-    repo=$(dirname "$wtroot")
-    for d in "$wtroot"/*; do
+  # The candidates: every `<repo>/.worktrees/*` under --repos, or exactly the
+  # --only list. Both go through the same guards below.
+  candidates=""
+  if [ -n "$ONLY" ]; then
+    candidates="$ONLY_LIST"
+  else
+    for wtroot in "$REPOS"/*/.worktrees; do
+      [ -d "$wtroot" ] || continue
+      [ -L "$wtroot" ] && continue
+      for d in "$wtroot"/*; do
+        candidates="$candidates
+$d"
+      done
+    done
+  fi
+  while IFS= read -r d; do
+      [ -n "$d" ] || continue
       [ -d "$d" ] || continue
       [ -L "$d" ] && continue
       real=$(cd "$d" 2>/dev/null && pwd -P) || continue
+      repo=${real%%/.worktrees/*}
       # The namespace guard again, unconditionally: nothing outside a
       # `.worktrees/` directory is a candidate, whatever any record claims.
       case "$real" in */.worktrees/*) ;; *) continue ;; esac
+      if ! registered_top "$real"; then
+        skipped_unregistered=$((skipped_unregistered + 1))
+        continue
+      fi
       printf '%s\n' "$HANDLED" | grep -qxF "$real" && continue
       id=$(basename "$real")
 
@@ -276,6 +380,10 @@ if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
       st=$(printf '%s' "$row" | cut -f3)
       pr=$(printf '%s' "$row" | cut -f4)
       ph=$(printf '%s' "$row" | cut -f5)
+      hd=$(printf '%s' "$row" | cut -f6)
+      if [ -n "$hd" ]; then
+        skipped_waiting=$((skipped_waiting + 1)); continue
+      fi
 
       # Rule 1 again: landed work is not residue, whichever pass finds it. Order
       # matters here - the waiting-phase test is a proxy for "still waiting", and
@@ -323,6 +431,7 @@ if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
         printf '  %s %s - %s, idle %sd, %s\n' \
           "$([ "$DELETE" -eq 0 ] && echo "unattributed:" || echo "left alone:")" \
           "$id" "$why" "$age_days" "$human"
+        emit "$id" "$real" unattributed "$why" "$age_days" "${size_kb:-0}" 2
         continue
       fi
 
@@ -330,8 +439,10 @@ if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
       if [ "$DELETE" -eq 0 ]; then
         if [ "$dirty" -eq 1 ]; then
           printf '  would stash (uncommitted work): %s - %s, idle %sd, %s\n' "$id" "$why" "$age_days" "$human"
+          emit "$id" "$real" would-stash "$why" "$age_days" "${size_kb:-0}" 2
         else
           printf '  would remove worktree: %s - %s, idle %sd, %s\n' "$id" "$why" "$age_days" "$human"
+          emit "$id" "$real" would-remove "$why" "$age_days" "${size_kb:-0}" 2
         fi
         continue
       fi
@@ -340,23 +451,31 @@ if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
         git -C "$real" stash push -u -m "autopilot/abandoned/$id" >/dev/null 2>&1 &&
           printf '→ stashed uncommitted work, worktree kept: %s\n' "$id" ||
           printf '→ could NOT stash, worktree kept untouched: %s\n' "$id"
+        emit "$id" "$real" stashed "$why" "$age_days" "${size_kb:-0}" 2
         kept_dirty=$((kept_dirty + 1))
         continue
       fi
-      git -C "$repo" worktree remove --force "$real" >/dev/null 2>&1 || rm -rf "$real"
+      if ! git -C "$repo" worktree remove --force "$real" >/dev/null 2>&1; then
+        printf '→ could NOT remove, worktree kept: %s\n' "$id"
+        emit "$id" "$real" remove-failed "$why" "$age_days" "${size_kb:-0}" 2
+        continue
+      fi
       # Same reason as the first pass: a failed prune is not a reason to stop.
       git -C "$repo" worktree prune >/dev/null 2>&1 || true
       printf '→ removed worktree: %s (%s, %s, idle %sd)\n' "$id" "$why" "$human" "$age_days"
+      emit "$id" "$real" removed "$why" "$age_days" "${size_kb:-0}" 2
       freed_kb=$((freed_kb + ${size_kb:-0}))
       removed=$((removed + 1))
-    done
-  done
+  done <<EOF_CANDIDATES
+$candidates
+EOF_CANDIDATES
 fi
 listed=$((listed + stale_wt))
 
 note=""
 [ "$skipped_waiting" -gt 0 ] && note="$note, $skipped_waiting waiting on you (kept)"
 [ "$skipped_unsafe" -gt 0 ] && note="$note, $skipped_unsafe path(s) outside .worktrees/ (kept)"
+[ "$skipped_unregistered" -gt 0 ] && note="$note, $skipped_unregistered path(s) not a registered worktree (kept)"
 [ "$kept_dirty" -gt 0 ] && note="$note, $kept_dirty stashed and kept"
 if [ "$unattributed" -gt 0 ]; then
   uh=$(printf '%s' "$unattributed_kb" | awk '{printf "%.1fG", $1/1048576}')

package/pipeline/scripts/gen-facts.mjs

@@ -94,7 +94,10 @@ try {
 let toolCount = null;
 let toolCategories = null;
 let toolkitVersion = null;
-const toolkitDir = join(ROOT, "..", "multi-agent-toolkit-mcp");
+// Sibling checkouts are looked up beside this repo; GEN_FACTS_SIBLINGS_DIR
+// names another parent directory (a test points it at an empty one).
+const siblingsDir = process.env.GEN_FACTS_SIBLINGS_DIR || join(ROOT, "..");
+const toolkitDir = join(siblingsDir, "multi-agent-toolkit-mcp");
 if (existsSync(join(toolkitDir, "package.json"))) {
   try {
     toolkitVersion =
@@ -102,11 +105,10 @@ if (existsSync(join(toolkitDir, "package.json"))) {
   } catch {
     toolkitVersion = null;
   }
-  // Asked of the server, not counted out of its source. Three tool families
+  // Asked of the server, not counted out of its source: three tool families
   // are defined in modules the main file only spreads in, so a regex over
-  // index.js returns a number that looks plausible and is wrong - the first
-  // version of this script said 2 when the answer was 99. tools/list is what
-  // a client actually receives, which is the number the site should print.
+  // index.js misses them. tools/list is what a client actually receives,
+  // which is the number the site should print.
   try {
     const req =
       [
@@ -164,7 +166,7 @@ if (existsSync(join(toolkitDir, "package.json"))) {
 // next to the pipeline's own skill counts, and three different skill
 // populations on one page is exactly the shape that drifts.
 let pluginSkillCount = null;
-const pluginsDir = join(ROOT, "..", "multi-agent-plugins", "plugins");
+const pluginsDir = join(siblingsDir, "multi-agent-plugins", "plugins");
 if (existsSync(pluginsDir)) {
   let n = 0;
   const walk = (d) => {
@@ -191,17 +193,14 @@ const facts = {
   phaseCount: contract.phases.length,
   modes: Object.fromEntries(Object.entries(contract.modes).map(([k, v]) => [k, v.phases])),
   commandCount: countSkillDirs("pipeline/commands/multi-agent"),
-  // Two populations, and conflating them is how the site came to show a stale
-  // "212 Skills" chip next to a correct "216 skills" sentence. `skillCount` is
-  // the external set a user installs; `skillCountAll` is every SKILL.md the
-  // repo ships, mirrors included. Both are stated on the site, so both are
-  // generated here rather than counted by hand at the other end.
+  // Two populations: `skillCount` is the external set a user installs;
+  // `skillCountAll` is every SKILL.md the repo ships, mirrors included. The site
+  // states both, so both are generated here rather than counted by hand at the
+  // other end.
   skillCount: countSkillDirs("pipeline/skills/shared/external"),
   skillCountAll: countSkillsDeep("pipeline/skills"),
-  // The site shows both of these as headline figures and had typed both by
-  // hand: a "9 Sub-agents" that happened to be right and a host list that had
-  // gone stale, naming Claude Code and Copilot CLI while install/codex.mjs had
-  // been shipping a third target for releases.
+  // Both are headline figures on the site; generated from pipeline/agents and
+  // install/, so the sub-agent count and the host list follow what ships.
   agentCount: readdirSync(join(ROOT, "pipeline", "agents")).filter((f) => f.endsWith(".md")).length,
   hosts: readdirSync(join(ROOT, "install"))
     .filter((f) => f.endsWith(".mjs") && !f.startsWith("_") && f !== "index.mjs")
@@ -257,6 +256,23 @@ if (process.argv.includes("--check")) {
   // generatedAt is a timestamp, not a fact: comparing it would fail every day.
   delete onDisk.generatedAt;
   delete fresh.generatedAt;
+  // A number read from a sibling checkout cannot be checked without it. Those
+  // fields are left out of the comparison and named, so a clean clone checks
+  // everything it can and says what it could not.
+  const unchecked = [];
+  if (!existsSync(join(toolkitDir, "package.json"))) {
+    unchecked.push("toolCount", "toolCategories", "toolkitVersion");
+  }
+  if (!existsSync(pluginsDir)) unchecked.push("pluginSkillCount");
+  for (const k of unchecked) {
+    delete onDisk[k];
+    delete fresh[k];
+  }
+  if (unchecked.length) {
+    console.log(
+      `gen-facts: not checked, no sibling checkout in ${siblingsDir}: ${unchecked.join(", ")}`,
+    );
+  }
   if (JSON.stringify(onDisk) !== JSON.stringify(fresh)) {
     console.error(
       "gen-facts: docs/facts.json is stale  -  run: node pipeline/scripts/gen-facts.mjs",

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -2,17 +2,17 @@
 import { readFileSync } from "node:fs";
 /**
  * gen-mode-dispatch.mjs  -  emit the canonical Phase Tracker Contract block
- * for a given mode dispatch file (full / local / autopilot / analysis).
+ * for a given mode dispatch file (full / autopilot / analysis, the modes in
+ * pipeline/schemas/phases.json).
  *
  * v8.0.0 introduced this generator as the single source of truth for the
  * "## Required: Phase Tracker Contract" section embedded in every mode
  * dispatch file under pipeline/commands/multi-agent/. Each mode declares its
- * own phase list (full / fast / local), but the tracker call shape, render
+ * own phase list, but the tracker call shape, render
  * call, anti-pattern warning, and ref link are identical.
  *
  * Usage:
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=full         # 0..5
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=local        # 0..5 + local-mode caveat
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=autopilot    # 0..5
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=analysis     # 0/1/3/4/5 (no Dev)
  *