@mmerterden/multi-agent-pipeline 16.31.0 → 17.0.0

package/pipeline/scripts/capture-resume.sh

@@ -29,20 +29,70 @@ LOGS="$HOME/.claude/logs/multi-agent"
 PIPELINE_MEM="$HOME/.claude/memory/multi-agent/_pipeline"
 REVIEW_DAYS=7
 
+# Three buckets, not one line. Measured on the development machine: 22 runs read
+# `in_progress` and every one was over a day old, but they are not one failure.
+# 13 stopped at Phase 0, which is almost entirely questions - those runs never
+# started. 3 had their PR already open and were waiting at Phase 6/7, where the
+# pipeline pauses ON PURPOSE for channel selection. 4 died mid-development.
+#
+# Reporting the newest one of those as "stopped at Phase N" told the truth about
+# one run and hid twenty-one, and it read the same whether the pipeline was
+# waiting for the user or had crashed. A finished job and a dead one should not
+# share a sentence.
+AWAITING_N=0; AWAITING_TASK=""; AWAITING_PHASE=""
+DIED_N=0;     DIED_TASK="";     DIED_PHASE=""
+UNSTARTED_N=0; UNSTARTED_TASK=""
 STALE_TASK=""
 STALE_PHASE=""
 
 if [ -d "$LOGS" ] && command -v jq >/dev/null 2>&1; then
-  # Newest by mtime, not by name: task ids do not sort chronologically.
-  NEWEST=$(find "$LOGS" -name agent-state.json -type f -maxdepth 4 -print0 2>/dev/null \
-    | xargs -0 ls -t 2>/dev/null | head -1)
-  if [ -n "$NEWEST" ] && [ -f "$NEWEST" ]; then
-    P7=$(jq -r '[.phases[]? | select((.id // "") == "7") | .status] | first // ""' "$NEWEST" 2>/dev/null)
-    STATUS=$(jq -r '.status // ""' "$NEWEST" 2>/dev/null)
-    if [ "$P7" != "completed" ] && [ "$STATUS" != "completed" ]; then
-      STALE_TASK=$(jq -r '.taskId // .jiraId // ""' "$NEWEST" 2>/dev/null)
-      STALE_PHASE=$(jq -r '.currentPhase // "?"' "$NEWEST" 2>/dev/null)
+  # Newest first, so the first hit in each bucket is the one worth naming.
+  # Both layouts are walked: state is written flat as <task-id>/ by
+  # phase-tracker.sh and nested as <project>/<task-id>/ by Phase 0, and a
+  # reader that knows only one of them under-reports by the size of the other.
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    STATUS=$(jq -r '.status // ""' "$f" 2>/dev/null)
+    # Only runs that CLAIM to be running are bucketed. A file with no status is
+    # unknown - eight of them here, six with no currentPhase either - and
+    # reporting unknown as "stopped mid-development" is the same false claim
+    # this change exists to remove, just pointed the other way. If that hides a
+    # real run, the fix is for its writer to record a status.
+    # `complete` is the schema spelling and `completed` is in the wild too, so
+    # both are excluded; a reader that knows one calls finished runs stale.
+    case "$STATUS" in in_progress | paused | awaiting_input) ;; *) continue ;; esac
+    PHASE=$(jq -r '.currentPhase // "?"' "$f" 2>/dev/null)
+    TASK=$(jq -r '.taskId // .jiraId // ""' "$f" 2>/dev/null)
+    [ -n "$TASK" ] || continue
+    # `.pr` is an object in the schema and a bare URL string in three state files
+    # on disk. `jq '.pr.url'` on a string errors, and with stderr suppressed that
+    # reads as "no PR" - so a run whose PR is already open would be classed as dead
+    # 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' "$f" 2>/dev/null)
+
+    # Waiting for you, not broken: an open PR means the work landed, and
+    # Phase 7 pauses for channel selection by design (modes.md).
+    if [ "$STATUS" = "awaiting_input" ] || [ -n "$PR" ] ||
+      [ "$PHASE" = "6" ] || [ "$PHASE" = "7" ]; then
+      AWAITING_N=$((AWAITING_N + 1))
+      [ -z "$AWAITING_TASK" ] && { AWAITING_TASK="$TASK"; AWAITING_PHASE="$PHASE"; }
+    elif [ "$PHASE" = "0" ]; then
+      # Phase 0 is almost all questions. Nothing was built, so there is nothing
+      # to resume and nothing to lose.
+      UNSTARTED_N=$((UNSTARTED_N + 1))
+      [ -z "$UNSTARTED_TASK" ] && UNSTARTED_TASK="$TASK"
+    else
+      DIED_N=$((DIED_N + 1))
+      [ -z "$DIED_TASK" ] && { DIED_TASK="$TASK"; DIED_PHASE="$PHASE"; }
     fi
+  done <<EOF
+$(find "$LOGS" -name agent-state.json -type f -maxdepth 4 -print0 2>/dev/null | xargs -0 ls -t 2>/dev/null)
+EOF
+  # Kept for the JSON consumers that read staleTask/stalePhase.
+  if [ -n "$AWAITING_TASK" ]; then
+    STALE_TASK="$AWAITING_TASK"; STALE_PHASE="$AWAITING_PHASE"
+  elif [ -n "$DIED_TASK" ]; then
+    STALE_TASK="$DIED_TASK"; STALE_PHASE="$DIED_PHASE"
   fi
 fi
 
@@ -71,14 +121,26 @@ if [ -d "$PIPELINE_MEM/observations" ]; then
 fi
 
 if [ "$JSON" -eq 1 ]; then
-  printf '{"staleTask":"%s","stalePhase":"%s","openObservations":%s,"reviewDue":%s}\n' \
-    "$STALE_TASK" "$STALE_PHASE" "${OPEN_OBS:-0}" "$REVIEW_DUE"
+  printf '{"staleTask":"%s","stalePhase":"%s","awaiting":%s,"died":%s,"unstarted":%s,"openObservations":%s,"reviewDue":%s}\n' \
+    "$STALE_TASK" "$STALE_PHASE" "$AWAITING_N" "$DIED_N" "$UNSTARTED_N" "${OPEN_OBS:-0}" "$REVIEW_DUE"
   exit 0
 fi
 
-if [ -n "$STALE_TASK" ]; then
-  printf 'multi-agent: %s stopped at Phase %s - `/multi-agent:resume` to continue, `/multi-agent:kill` to drop it.\n' \
-    "$STALE_TASK" "$STALE_PHASE"
+# One line per bucket, each naming its own next action, because they are
+# different actions. Counts are printed even when they are 1: "1 run" and
+# "13 runs" call for different reactions and the old line could not tell them
+# apart.
+if [ "$AWAITING_N" -gt 0 ]; then
+  printf 'multi-agent: %s run(s) waiting on you, oldest %s at Phase %s - `/multi-agent:resume` to finish.\n' \
+    "$AWAITING_N" "$AWAITING_TASK" "$AWAITING_PHASE"
+fi
+if [ "$DIED_N" -gt 0 ]; then
+  printf 'multi-agent: %s run(s) stopped mid-development, oldest %s at Phase %s - `/multi-agent:resume` or `/multi-agent:kill`.\n' \
+    "$DIED_N" "$DIED_TASK" "$DIED_PHASE"
+fi
+if [ "$UNSTARTED_N" -gt 0 ]; then
+  printf 'multi-agent: %s run(s) left at a Phase 0 question, nothing built - `/multi-agent:garbage-collect --abandoned` to clear.\n' \
+    "$UNSTARTED_N"
 fi
 if [ "$REVIEW_DUE" -eq 1 ]; then
   printf 'multi-agent: %s open pipeline observation(s), last review %s+ days ago - `/multi-agent:refactor backlog` when convenient.\n' \

package/pipeline/scripts/doctor.mjs

@@ -70,6 +70,7 @@ const TASK_TOOLS = taskFlag ? taskFlag.split("=")[1] : null;
 // the two are equal in BOTH directions: a check cannot ship without its entry,
 // and an entry cannot outlive its check.
 const CHECK_IDS = [
+  "host-platform",
   "install-present",
   "install-version",
   "script-surface",
@@ -87,10 +88,11 @@ const CHECK_IDS = [
   "worktree-residue",
 ];
 
-// Only these five may return BLOCK. Enforced below, not merely documented: a
+// Only these six may return BLOCK. Enforced below, not merely documented: a
 // check that returns BLOCK without being listed here is downgraded and the
 // downgrade is reported, because an unenforced rule is a comment.
 const MAY_BLOCK = new Set([
+  "host-platform",
   "install-present",
   "script-surface",
   "state-writable",
@@ -153,6 +155,25 @@ function readJson(path) {
 // one step silently fails is worse than no step. Rule: smoke-npm-scope-pinning.sh.
 const SUBTREES = ["commands", "multi-agent-refs", "scripts", "lib", "schemas"];
 
+// Runs before everything else so a non-darwin host gets one honest line instead
+// of a cascade of failures whose common cause is never stated. This blocks
+// rather than warns because a run there does not degrade, it fails: every
+// credential read shells `security`, every iOS build `xcodebuild`, every piece
+// of visual evidence `simctl`.
+function checkHostPlatform() {
+  if (process.platform === "darwin") {
+    ok("host-platform");
+    return true;
+  }
+  report(
+    "host-platform",
+    "BLOCK",
+    `this host reports "${process.platform}"; the pipeline supports macOS only`,
+    "install on macOS, or set MULTI_AGENT_ALLOW_NON_DARWIN=1 to proceed untested",
+  );
+  return false;
+}
+
 function checkInstallPresent() {
   if (!existsSync(CLAUDE)) {
     report(
@@ -718,18 +739,20 @@ function main() {
     return;
   }
 
+  checkHostPlatform();
+
   const resolved = checkInstallPresent();
   if (!resolved) {
     // Indeterminate, not healthy and not merely degraded: nothing after this
     // could be checked, and saying "blocked" would claim a verdict on checks
     // that never ran.
-    const line = results[0];
+    const line = results[results.length - 1];
     if (JSON_OUT) {
       process.stdout.write(`${JSON.stringify({ exit: 4, checks: results }, null, 2)}\n`);
     } else {
       process.stdout.write(`${line.severity} ${line.id}  -  ${line.problem}  -  ${line.step}\n`);
       process.stdout.write(
-        `\n-> indeterminate: the layout did not resolve, so ${CHECK_IDS.length - 1} checks did not run\n`,
+        `\n-> indeterminate: the layout did not resolve, so ${CHECK_IDS.length - results.length} checks did not run\n`,
       );
     }
     process.exitCode = 4;

package/pipeline/scripts/gc-abandoned.sh

@@ -0,0 +1,352 @@
+#!/usr/bin/env bash
+# gc-abandoned.sh  -  reap runs that stopped and were never picked back up.
+#
+# The gap this fills: gc-worktrees.sh deliberately skips REGISTERED worktrees,
+# because a registered worktree belongs to a live run. That is right, and it
+# means nothing at all collects a run that simply stopped - its worktree stays
+# registered forever. Measured on one machine: 20 runs reading `in_progress`,
+# every one more than a day old, one of them 157 days, holding 28 worktrees
+# across 7 repos and 22.8 GB.
+#
+# Three things keep this from being a foot-gun, and each is a rule rather than a
+# heuristic:
+#
+#   1. A run WAITING FOR YOU is never reaped. An open PR, Phase 6 or 7, or
+#      `status: awaiting_input` means the work landed and the pipeline is
+#      holding for an answer by design. That is finished work, not residue.
+#   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.
+#   3. Uncommitted work is never destroyed. The branch is stashed to
+#      `autopilot/abandoned/<task-id>` and the directory is left in place, which
+#      costs disk and keeps the work. Losing a day of edits is worse than 750 MB.
+#
+# TWO PASSES, because the state files are not where the disk is. Measured across
+# 28 worktrees holding 23 GB: only 5 of them (1.5 GB) belong to a run that still
+# reads `in_progress`. 19 of them (15.6 GB) have NO state file at all, and 3 more
+# (5.1 GB) belong to runs that finished and whose worktree outlived them. A
+# state-driven sweep alone reaps 4% of the problem, so pass 2 walks the worktrees
+# themselves and asks each one what its run is doing.
+#
+# Pass 2 keeps every rule above and adds the one that matters most: **a worktree
+# with no run state on record is REPORTED, never removed.** `.worktrees/` is not
+# exclusively ours - the measured machine holds `174`, `pr-4051`, `task-1` and
+# `create-screen` there, all hand-made by the user, one of them in active use.
+# Nothing distinguishes those from a pipeline worktree whose log was pruned, so
+# the honest move is to show them with their size and let the user decide. They
+# are the 15.6 GB, and pointing at them is worth more than a rule that guesses.
+#
+# So --yes removes exactly two things: a worktree whose run is recorded as
+# finished, and one whose run is recorded as stopped past its age limit.
+#
+# Two ages, because two different things are being reaped. A run left at a Phase
+# 0 question never started - Phase 0 is almost entirely questions - so there is
+# no code to lose and a short window is safe. A run that died mid-development
+# may hold real edits, so it gets a long one and the stash rule above.
+#
+# State is moved to `<run-dir>/artifacts/` before the worktree goes, so the log,
+# the findings and the phase history survive the sweep. The same recovery
+# contract Phase 6 uses when it removes a finished worktree.
+#
+# SAFE BY DEFAULT: dry-run. Removes nothing until you pass --yes.
+#
+# Usage:
+#   gc-abandoned.sh                      # dry-run, default ages
+#   gc-abandoned.sh --yes                # apply
+#   gc-abandoned.sh --days=14            # mid-development runs idle > 14 days
+#   gc-abandoned.sh --phase0-days=3      # Phase 0 leftovers idle > 3 days
+#   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
+#
+# Exit: 0 on success (including "nothing to do"), 2 on usage error.
+
+set -uo pipefail
+
+LOGS="$HOME/.claude/logs/multi-agent"
+REPOS="$HOME"
+DELETE=0
+DAYS=7
+PHASE0_DAYS=1
+STATE_ONLY=0
+
+usage() {
+  grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --yes | -y) DELETE=1; shift ;;
+    --days=*) DAYS="${1#*=}"; shift ;;
+    --phase0-days=*) PHASE0_DAYS="${1#*=}"; shift ;;
+    --logs) LOGS="${2:-}"; shift 2 ;;
+    --repos) REPOS="${2:-}"; shift 2 ;;
+    --state-only) STATE_ONLY=1; shift ;;
+    --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 ;;
+  esac
+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; }
+[ -d "$LOGS" ] || { echo "gc-abandoned: nothing to do (no state at $LOGS)"; exit 0; }
+
+# GNU form FIRST. `stat -f` is a valid GNU flag (--file-system) that succeeds and
+# prints a mount point, so BSD-first silently returns a number that is not a
+# timestamp. ADR-0012 lists this among the constructs that look cross-platform
+# 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"; }
+
+NOW=$(date +%s)
+removed=0
+freed_kb=0
+kept_dirty=0
+skipped_waiting=0
+skipped_unsafe=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
+# would then see a clean worktree whose run pass 1 just marked `failed` and
+# remove the very thing that was preserved. The two passes are complementary,
+# not sequential filters over the same set.
+HANDLED=""
+
+# Both layouts: phase-tracker.sh writes <task-id>/ and Phase 0 writes
+# <project>/<task-id>/. Six task ids on the measured machine exist in both, so a
+# sweep that walks one layout leaves the other copy claiming the run is live.
+while IFS= read -r state; do
+  [ -f "$state" ] || continue
+  status=$(jq -r '.status // ""' "$state" 2>/dev/null)
+  # Only runs that CLAIM to be running. A file with no status is unknown, and
+  # unknown is not a licence to delete.
+  case "$status" in in_progress | paused | awaiting_input) ;; *) continue ;; esac
+
+  task=$(jq -r '.taskId // .jiraId // ""' "$state" 2>/dev/null)
+  [ -n "$task" ] || continue
+  phase=$(jq -r '.currentPhase // "?"' "$state" 2>/dev/null)
+  # `.pr` is an object in the schema and a bare URL string in three state files
+  # on disk. `jq '.pr.url'` on a string errors, and with stderr suppressed that
+  # reads as "no PR" - so a run whose PR is already open would be classed as dead
+  # 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)
+  wt=$(jq -r '.worktreePath // ""' "$state" 2>/dev/null)
+
+  # Rule 1: waiting for you is not residue.
+  if [ "$status" = "awaiting_input" ] || [ -n "$pr" ] || [ "$phase" = "6" ] || [ "$phase" = "7" ]; then
+    skipped_waiting=$((skipped_waiting + 1))
+    continue
+  fi
+
+  mtime=$(_mtime "$state")
+  age_days=$(((NOW - mtime) / 86400))
+  if [ "$phase" = "0" ]; then
+    limit="$PHASE0_DAYS"; kind="left at a Phase 0 question"
+  else
+    limit="$DAYS"; kind="stopped at Phase $phase"
+  fi
+  [ "$age_days" -gt "$limit" ] || continue
+
+  # Rule 2: the path must be strictly inside a .worktrees/ directory. A repo
+  # root recorded in worktreePath is the shape that would delete a checkout.
+  safe_wt=""
+  if [ -n "$wt" ] && [ -d "$wt" ] && [ ! -L "$wt" ]; then
+    real=$(cd "$wt" 2>/dev/null && pwd -P)
+    case "$real" in
+      */.worktrees/*) safe_wt="$real" ;;
+      *) skipped_unsafe=$((skipped_unsafe + 1)) ;;
+    esac
+  fi
+
+  size_kb=0
+  [ -n "$safe_wt" ] && size_kb=$(du -sk "$safe_wt" 2>/dev/null | cut -f1)
+
+  # Rule 3: uncommitted work is stashed, and the directory stays.
+  dirty=0
+  if [ -n "$safe_wt" ] && [ -n "$(git -C "$safe_wt" status --porcelain 2>/dev/null)" ]; then
+    dirty=1
+  fi
+
+  listed=$((listed + 1))
+  [ -n "$safe_wt" ] && HANDLED="$HANDLED
+$safe_wt"
+  human=$(printf '%s' "${size_kb:-0}" | awk '{printf "%.1fG", $1/1048576}')
+  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"
+    elif [ -n "$safe_wt" ]; then
+      printf '  would remove: %s - %s, idle %sd, %s\n' "$task" "$kind" "$age_days" "$human"
+    else
+      printf '  would mark abandoned (no reapable worktree): %s - %s, idle %sd\n' "$task" "$kind" "$age_days"
+    fi
+    continue
+  fi
+
+  run_dir=$(dirname "$state")
+  mkdir -p "$run_dir/artifacts" 2>/dev/null
+  cp "$state" "$run_dir/artifacts/agent-state.json" 2>/dev/null
+  tmp="$state.tmp.$$"
+  if jq --arg r "abandoned by gc-abandoned after ${age_days}d idle" \
+    '.status = "failed" | .haltReason = $r' "$state" > "$tmp" 2>/dev/null; then
+    mv "$tmp" "$state"
+  else
+    rm -f "$tmp"
+  fi
+
+  if [ "$dirty" -eq 1 ]; then
+    br="autopilot/abandoned/$task"
+    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"
+    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"
+    git -C "$repo" worktree prune >/dev/null 2>&1
+    printf '→ removed: %s (%s, idle %sd)\n' "$task" "$human" "$age_days"
+    freed_kb=$((freed_kb + ${size_kb:-0}))
+  else
+    printf '→ marked abandoned, no reapable worktree: %s\n' "$task"
+  fi
+  removed=$((removed + 1))
+done <<EOF
+$(find "$LOGS" -name agent-state.json -type f -maxdepth 4 -not -path '*/artifacts/*' 2>/dev/null)
+EOF
+
+# ---- pass 2: the worktrees themselves ---------------------------------------
+#
+# Driven from disk rather than from state, because 19 of the 28 worktrees
+# measured have no state file to drive from. For each one the question is what
+# its run is doing, answered by looking the state up by path and by task id.
+stale_wt=0
+unattributed=0
+unattributed_kb=0
+if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
+  # Every state file once, so the per-worktree lookup below is a grep and not a
+  # re-walk of the log tree for each of 28 directories.
+  index=$(find "$LOGS" -name agent-state.json -type f -maxdepth 4 -not -path '*/artifacts/*' 2>/dev/null |
+    while IFS= read -r f; do
+      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
+    done)
+
+  for wtroot in "$REPOS"/*/.worktrees; do
+    [ -d "$wtroot" ] || continue
+    [ -L "$wtroot" ] && continue
+    repo=$(dirname "$wtroot")
+    for d in "$wtroot"/*; do
+      [ -d "$d" ] || continue
+      [ -L "$d" ] && continue
+      real=$(cd "$d" 2>/dev/null && pwd -P) || continue
+      # The namespace guard again, unconditionally: nothing outside a
+      # `.worktrees/` directory is a candidate, whatever any record claims.
+      case "$real" in */.worktrees/*) ;; *) continue ;; esac
+      printf '%s\n' "$HANDLED" | grep -qxF "$real" && continue
+      id=$(basename "$real")
+
+      row=$(printf '%s\n' "$index" | awk -F'\t' -v p="$real" -v i="$id" '$1==p || $2==i {print; exit}')
+      st=$(printf '%s' "$row" | cut -f3)
+      pr=$(printf '%s' "$row" | cut -f4)
+      ph=$(printf '%s' "$row" | cut -f5)
+
+      # Rule 1 again: landed work is not residue, whichever pass finds it. Order
+      # matters here - the phase-6/7 test is a proxy for "still waiting", and a
+      # run whose status already says it FINISHED is not waiting for anyone. A
+      # complete run sitting at phase 7 was read as waiting and never reaped,
+      # which is how three finished worktrees held 5.1 GB indefinitely.
+      case "$st" in
+        complete | completed | failed) ;;
+        awaiting_input)
+          skipped_waiting=$((skipped_waiting + 1)); continue ;;
+        in_progress | paused)
+          continue ;; # pass 1 owns these; do not report them twice
+        *)
+          if [ -n "$pr" ] || [ "$ph" = "6" ] || [ "$ph" = "7" ]; then
+            skipped_waiting=$((skipped_waiting + 1)); continue
+          fi ;;
+      esac
+
+      attributed=1
+      case "$st" in
+        complete | completed | failed)
+          why="run finished, worktree outlived it" ;;
+        *)
+          why="no run state on record - yours to judge, never removed here"
+          attributed=0 ;;
+      esac
+
+      # Age from the newest file in the tree, not from the directory stamp: a
+      # directory mtime only tracks its immediate entries, so an actively edited
+      # worktree can look untouched for weeks.
+      newest=$(find "$real" -type f -not -path '*/.git/*' -print0 2>/dev/null |
+        xargs -0 ls -t 2>/dev/null | head -1)
+      mt=$(_mtime "${newest:-$real}")
+      age_days=$(((NOW - mt) / 86400))
+      [ "$age_days" -gt "$DAYS" ] || continue
+
+      size_kb=$(du -sk "$real" 2>/dev/null | cut -f1)
+      human=$(printf '%s' "${size_kb:-0}" | awk '{printf "%.1fG", $1/1048576}')
+      dirty=0
+      [ -n "$(git -C "$real" status --porcelain 2>/dev/null)" ] && dirty=1
+
+      if [ "$attributed" -eq 0 ]; then
+        unattributed=$((unattributed + 1))
+        unattributed_kb=$((unattributed_kb + ${size_kb:-0}))
+        printf '  %s %s - %s, idle %sd, %s\n' \
+          "$([ "$DELETE" -eq 0 ] && echo "unattributed:" || echo "left alone:")" \
+          "$id" "$why" "$age_days" "$human"
+        continue
+      fi
+
+      stale_wt=$((stale_wt + 1))
+      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"
+        else
+          printf '  would remove worktree: %s - %s, idle %sd, %s\n' "$id" "$why" "$age_days" "$human"
+        fi
+        continue
+      fi
+
+      if [ "$dirty" -eq 1 ]; 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"
+        kept_dirty=$((kept_dirty + 1))
+        continue
+      fi
+      git -C "$repo" worktree remove --force "$real" >/dev/null 2>&1 || rm -rf "$real"
+      git -C "$repo" worktree prune >/dev/null 2>&1
+      printf '→ removed worktree: %s (%s, %s, idle %sd)\n' "$id" "$why" "$human" "$age_days"
+      freed_kb=$((freed_kb + ${size_kb:-0}))
+      removed=$((removed + 1))
+    done
+  done
+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)"
+[ "$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}')
+  note="$note, $unattributed worktree(s) holding $uh with no run state (listed, untouched)"
+fi
+
+if [ "$DELETE" -eq 0 ]; then
+  if [ "$listed" -eq 0 ]; then
+    printf 'gc-abandoned: nothing to do%s\n' "${note:+ (}${note#, }${note:+)}"
+  else
+    printf '══ gc-abandoned (dry-run): %d run(s) would be reaped%s ══\n' "$listed" "$note"
+  fi
+  exit 0
+fi
+
+freed_h=$(printf '%s' "$freed_kb" | awk '{printf "%.1fG", $1/1048576}')
+printf '══ gc-abandoned: reaped %d run(s), freed ~%s%s ══\n' "$removed" "$freed_h" "$note"
+exit 0

package/pipeline/scripts/keychain.py

@@ -189,7 +189,7 @@ def _macos_find(args: list[str]) -> Optional[str]:
 
 def get(label: str, account: Optional[str] = None) -> Optional[str]:
     """Lookup by label first, then by service name. Two coexisting conventions:
-    - User's manually-added tokens (e.g. mmerterden_Vercel_Access_Token) use -l (label).
+    - User's manually-added tokens (e.g. ${USER}_Vercel_Access_Token) use -l (label).
     - credential-store.sh-managed items use -s (service).
     The helper finds either."""
     pf = _ensure_backend()

package/pipeline/scripts/usage-report.mjs

@@ -177,12 +177,12 @@ function invokedCalls(state) {
   return Array.from(names).slice(0, 30);
 }
 
+// The package declares `os: ["darwin"]` and every entry point refuses a
+// non-darwin host, so the branches this used to carry were unreachable. The
+// function and the field stay: the panel groups by `os` and a row with the key
+// missing reads as "unknown host" rather than "macOS".
 function detectOs() {
-  const p = platform();
-  if (p === "darwin") return "macos";
-  if (p === "win32") return "windows";
-  if (p === "linux") return "linux";
-  return p;
+  return platform() === "darwin" ? "macos" : platform();
 }
 
 function detectCli() {

package/pipeline/scripts/gate-linux.sh

@@ -1,62 +0,0 @@
-#!/usr/bin/env bash
-# gate-linux.sh  -  run the ci-lite job on a real Ubuntu image, locally.
-#
-# The pre-push gate (pre-push-check.sh) is the primary one, but it runs on the
-# maintainer's macOS workstation against an installed node_modules that has
-# accumulated over months. Two things it cannot answer: does this tree work on
-# Linux, and does `npm ci` from the lockfile into an empty tree still resolve.
-# ci-lite.yml answers both, and has not executed since 2026-07-25.
-#
-# `act` runs that workflow against the same image GitHub would use, so the
-# answer comes from the workflow definition rather than from a second script
-# that would drift away from it.
-#
-# NOT part of `npm run gate` on purpose: act and Docker are not installed
-# everywhere, and a required gate that cannot run is the failure ADR-0011
-# exists to avoid. Run it before a release, or after touching install/,
-# lib/credential-store.sh, or anything path-shaped.
-#
-# Needs network inside the container: the scorecard's dependency metrics ask
-# the registry (advisories and signatures) and report an unreachable registry
-# as a failure rather than a skip, on the grounds that a supply-chain check
-# which goes green without reaching the registry is worse than no check.
-#
-# Exit codes: 0 = the job passed, 1 = the job failed, 2 = tooling missing
-
-set -uo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-cd "$REPO_ROOT" || { echo "FAIL: can't cd to repo root" >&2; exit 2; }
-
-if ! command -v act >/dev/null 2>&1; then
-  cat >&2 <<'MSG'
-✗ act is not installed - this gate needs it to run the Ubuntu job locally.
-
-    brew install act        # macOS
-    # and a running Docker daemon (Docker Desktop, colima, orbstack)
-
-Why this is not bundled: it pulls a multi-gigabyte runner image. The rest of
-the gate chain (npm run gate) has no such dependency and stays the default.
-MSG
-  exit 2
-fi
-
-if ! docker info >/dev/null 2>&1; then
-  echo "✗ act is installed but no Docker daemon is reachable. Start Docker and retry." >&2
-  exit 2
-fi
-
-echo "→ Running ci-lite on ubuntu-22.04 via act (this pulls an image on first run)"
-echo ""
-
-if act workflow_dispatch \
-  -W .github/workflows/ci-lite.yml \
-  -P ubuntu-latest=catthehacker/ubuntu:act-22.04; then
-  echo ""
-  echo "✓ ci-lite passed on Linux"
-  exit 0
-fi
-
-echo "" >&2
-echo "✗ ci-lite failed on Linux. A pass on macOS does not cover this." >&2
-exit 1