@mmerterden/multi-agent-pipeline 11.5.0 → 12.1.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

package/pipeline/scripts/render-agent-log-cost.sh

@@ -32,6 +32,8 @@ done
 
 ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 COST_TABLE="$ROOT/pipeline/scripts/cost-table.json"
+COST_LIB="$ROOT/pipeline/scripts/cost-lib.sh"
+if [ -f "$COST_LIB" ]; then . "$COST_LIB"; else COST_JQ_DEFS=""; fi
 
 command -v jq >/dev/null 2>&1 || { echo "render-agent-log-cost: jq required" >&2; exit 2; }
 
@@ -94,27 +96,19 @@ if [ "$rows_json" = "[]" ] && [ -n "$SPANS_FILE" ] && [ -f "$SPANS_FILE" ]; then
   ' "$SPANS_FILE")
 fi
 
-joined=$(jq -n --argjson rows "$rows_json" --slurpfile prices "$COST_TABLE" '
+joined=$(jq -n --argjson rows "$rows_json" --slurpfile prices "$COST_TABLE" "$COST_JQ_DEFS"'
   $rows | map(
     . as $r |
     ($prices[0].prices[$r.model] // null) as $p |
     # tokens_in is freshly-billed input (cache-exclusive, matching the host
     # input_tokens field); tokens_cached is the separate prompt-cache-read
-    # count, billed at the discounted cacheReadPerMtok rate (default to
-    # inPerMtok when the field is absent so an old price table still prices it).
-    # The two counts are disjoint - never subtract one from the other - so this
-    # renderer and aggregate-metrics.mjs agree on what "total input" means.
-    $r.tokens_in as $fresh |
+    # count, billed at the discounted cacheReadPerMtok rate. The two counts are
+    # disjoint - never subtract one from the other - so this renderer and
+    # aggregate-metrics.mjs agree on what "total input" means.
     ($r.tokens_cached // 0) as $cached |
     . + {
       tokens_cached: $cached,
-      usd: (
-        if $p == null then null
-        else ( ($fresh / 1000000) * $p.inPerMtok
-             + ($cached / 1000000) * ($p.cacheReadPerMtok // $p.inPerMtok)
-             + ($r.tokens_out / 1000000) * $p.outPerMtok )
-        end
-      )
+      usd: cost_usd_of($p; $r.tokens_in; $r.tokens_out; $cached)
     }
   )
 ')

package/pipeline/scripts/render-cost-summary.sh

@@ -26,6 +26,8 @@ done
 
 ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 COST_TABLE="$ROOT/pipeline/scripts/cost-table.json"
+COST_LIB="$ROOT/pipeline/scripts/cost-lib.sh"
+if [ -f "$COST_LIB" ]; then . "$COST_LIB"; else COST_JQ_DEFS=""; fi
 
 command -v jq >/dev/null 2>&1 || { echo "render-cost-summary: jq required" >&2; exit 2; }
 
@@ -78,17 +80,12 @@ if [ "$rows_json" = "[]" ] && [ -n "$SPANS_FILE" ] && [ -f "$SPANS_FILE" ]; then
 fi
 
 # Compute USD per row using cost-table
-joined=$(jq -n --argjson rows "$rows_json" --slurpfile prices "$COST_TABLE" '
+joined=$(jq -n --argjson rows "$rows_json" --slurpfile prices "$COST_TABLE" "$COST_JQ_DEFS"'
   $rows | map(
     . as $r |
     ($prices[0].prices[$r.model] // null) as $p |
     . + {
-      usd: (
-        if $p == null then null
-        else ( ($r.tokens_in / 1000000) * $p.inPerMtok
-             + ($r.tokens_out / 1000000) * $p.outPerMtok )
-        end
-      )
+      usd: cost_usd_of($p; $r.tokens_in; $r.tokens_out; 0)
     }
   )
 ')

package/pipeline/scripts/run-aggregator.mjs

@@ -37,6 +37,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { costUsd } from "./_cost.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -135,9 +136,7 @@ function computeCost(modelKey, tokensIn, tokensOut, costTable) {
   if (!price || (typeof price.inPerMtok !== "number" && typeof price.outPerMtok !== "number")) {
     return { cost_usd: 0, cost_unknown_model: true };
   }
-  const usd =
-    ((tokensIn || 0) / 1_000_000) * (price.inPerMtok || 0) +
-    ((tokensOut || 0) / 1_000_000) * (price.outPerMtok || 0);
+  const usd = costUsd(price, tokensIn, tokensOut);
   return { cost_usd: Number(usd.toFixed(6)) };
 }
 

package/pipeline/scripts/smoke-description-tr.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# smoke-description-tr.sh  -  localized picker-description contract.
+#
+# Verifies: every shipped command SKILL.md carries a description-tr line
+# (coverage), repo description: lines stay English with no description-en
+# sidecars committed (hygiene), and localize-commands.mjs apply/restore is
+# an idempotent, byte-identical round trip (mechanics).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CMD_DIR="$REPO_ROOT/pipeline/commands/multi-agent"
+LOCALIZER="$REPO_ROOT/pipeline/scripts/localize-commands.mjs"
+
+PASS=0
+FAIL=0
+record_pass() { PASS=$((PASS + 1)); printf '  \342\234\223 %s\n' "$1"; }
+record_fail() { FAIL=$((FAIL + 1)); printf '  \342\234\227 %s\n' "$1"; }
+
+printf '\342\206\222 smoke-description-tr: localized picker-description contract\n'
+
+# 1. Coverage: every command SKILL.md (incl. the dispatcher) has description-tr
+missing=""
+count=0
+for f in "$CMD_DIR/SKILL.md" "$CMD_DIR"/*/SKILL.md; do
+  [ -f "$f" ] || continue
+  count=$((count + 1))
+  grep -q '^description-tr:' "$f" || missing="$missing ${f#"$CMD_DIR/"}"
+done
+if [ -z "$missing" ]; then
+  record_pass "all $count command SKILL.md files carry description-tr"
+else
+  record_fail "missing description-tr in:$missing"
+fi
+
+# 2. Hygiene: repo descriptions stay English, no sidecars committed
+if grep -rn '^description:.*[çğıöşüÇĞİÖŞÜ]' "$CMD_DIR" >/dev/null 2>&1; then
+  record_fail "repo description: lines must stay English (Turkish characters found)"
+else
+  record_pass "repo description: lines are English"
+fi
+if grep -rln '^description-en:' "$CMD_DIR" >/dev/null 2>&1; then
+  record_fail "description-en sidecar committed to the repo (installed-tree artifact)"
+else
+  record_pass "no description-en sidecar in the repo"
+fi
+
+# 3. Translation length within the agent-skills description budget
+long=$(awk '/^description-tr:/ && length($0) > 1044 { print FILENAME }' "$CMD_DIR"/*/SKILL.md "$CMD_DIR/SKILL.md" 2>/dev/null | head -1)
+if [ -z "$long" ]; then
+  record_pass "every description-tr is within the 1024-char budget"
+else
+  record_fail "description-tr exceeds budget in $long"
+fi
+
+# 4. Round trip: apply is idempotent, restore is byte-identical
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+cp -R "$CMD_DIR" "$tmpdir/cmds"
+node "$LOCALIZER" apply --dir "$tmpdir/cmds" >/dev/null 2>&1
+if grep -q '^description:.*[çğıöşüÇĞİÖŞÜ]' "$tmpdir/cmds/dev/SKILL.md" \
+  && grep -q '^description-en:' "$tmpdir/cmds/dev/SKILL.md"; then
+  record_pass "apply swaps description and writes the description-en sidecar"
+else
+  record_fail "apply did not localize the sample file"
+fi
+second=$(node "$LOCALIZER" apply --dir "$tmpdir/cmds" 2>/dev/null)
+if printf '%s' "$second" | grep -q ' 0 file(s) changed'; then
+  record_pass "second apply is a no-op (idempotent)"
+else
+  record_fail "second apply changed files again: $second"
+fi
+node "$LOCALIZER" restore --dir "$tmpdir/cmds" >/dev/null 2>&1
+if diff -r "$CMD_DIR" "$tmpdir/cmds" >/dev/null 2>&1; then
+  record_pass "restore returns a byte-identical tree"
+else
+  record_fail "restore left differences vs the original tree"
+fi
+
+printf '\n\342\225\220\342\225\220 smoke-description-tr: %d passed, %d failed \342\225\220\342\225\220\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-gc-tmp.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # smoke-gc-tmp.sh  -  gc-tmp.sh sweeps only known scratch prefixes, is dry-run
-# by default, and never touches unrelated files.
+# by default, never touches unrelated files, refuses unsafe scratch roots,
+# never deletes the root itself, and spares fresh scratch by default.
 #
 # Exit 0 = all pass, 1 = any failure.
 
@@ -40,7 +41,7 @@ seed() {
 echo "→ 1. dry-run lists matches and deletes nothing"
 seed
 before=$(find "$SB" -mindepth 1 | wc -l | tr -d ' ')
-out=$(GC_TMP_ROOT="$SB" bash "$GC" 2>&1)
+out=$(GC_TMP_ROOT="$SB" GC_TMP_GRACE_MIN=0 bash "$GC" 2>&1)
 after=$(find "$SB" -mindepth 1 | wc -l | tr -d ' ')
 echo "$out" | grep -q "DRY-RUN" && pass "dry-run banner shown" || fail "dry-run banner missing"
 [ "$before" = "$after" ] && pass "dry-run deleted nothing ($after entries intact)" || fail "dry-run changed the tree ($before -> $after)"
@@ -49,7 +50,7 @@ echo "$out" | grep -q "unrelated-file.txt" && fail "dry-run matched an unrelated
 echo ""
 echo "→ 2. --yes removes only matched scratch"
 seed
-GC_TMP_ROOT="$SB" bash "$GC" --yes >/dev/null 2>&1
+GC_TMP_ROOT="$SB" GC_TMP_GRACE_MIN=0 bash "$GC" --yes >/dev/null 2>&1
 [ -f "$SB/unrelated-file.txt" ] && pass "unrelated file preserved" || fail "unrelated file was deleted"
 [ ! -e "$SB/multi-agent-picker-PROJ-1.json" ] && pass "multi-agent-* file removed" || fail "multi-agent-* file survived"
 [ ! -e "$SB/multi-agent-review-PROJ-1-x" ] && pass "scratch dir removed" || fail "scratch dir survived"
@@ -61,7 +62,7 @@ remaining=$(find "$SB" -mindepth 1 | wc -l | tr -d ' ')
 echo ""
 echo "→ 3. --older-than excludes fresh scratch"
 seed
-out=$(GC_TMP_ROOT="$SB" bash "$GC" --older-than=1 2>&1)
+out=$(GC_TMP_ROOT="$SB" GC_TMP_GRACE_MIN=0 bash "$GC" --older-than=1 2>&1)
 echo "$out" | grep -q "nothing to do" && pass "freshly-created scratch excluded by --older-than=1" || fail "--older-than did not exclude fresh files"
 
 echo ""
@@ -79,6 +80,51 @@ rc=$?
 rm -rf "$EMPTY"
 { [ "$rc" = "0" ] && echo "$out" | grep -q "nothing to do"; } && pass "empty root exits 0 with no-op message" || fail "empty root not a clean no-op"
 
+echo ""
+echo "→ 6. unsafe scratch roots are refused (exit 2)"
+GC_TMP_ROOT="$HOME" bash "$GC" >/dev/null 2>&1
+[ "$?" = "2" ] && pass "\$HOME as scratch root refused" || fail "\$HOME as scratch root not refused"
+GC_TMP_ROOT="/" bash "$GC" >/dev/null 2>&1
+[ "$?" = "2" ] && pass "/ as scratch root refused" || fail "/ as scratch root not refused"
+GITROOT="$(mktemp -d)"
+mkdir -p "$GITROOT/.git"
+touch "$GITROOT/multi-agent-bait.json"
+GC_TMP_ROOT="$GITROOT" bash "$GC" --yes >/dev/null 2>&1
+rc=$?
+[ "$rc" = "2" ] && pass "git work tree as scratch root refused" || fail "git work tree as scratch root not refused"
+[ -f "$GITROOT/multi-agent-bait.json" ] && pass "bait file inside refused root untouched" || fail "refused root was still swept"
+rm -rf "$GITROOT"
+
+echo ""
+echo "→ 7. a root itself named like scratch is never deleted"
+SR="$(mktemp -d)"
+mkdir -p "$SR/multi-agent-root"
+touch "$SR/multi-agent-root/multi-agent-inner.json"
+GC_TMP_ROOT="$SR/multi-agent-root" GC_TMP_GRACE_MIN=0 bash "$GC" --yes >/dev/null 2>&1
+[ -d "$SR/multi-agent-root" ] && pass "matching-named root survives --yes" || fail "root dir itself was deleted"
+[ ! -e "$SR/multi-agent-root/multi-agent-inner.json" ] && pass "inner scratch still removed" || fail "inner scratch survived"
+rm -rf "$SR"
+
+echo ""
+echo "→ 8. symlinked scratch is unlinked without following it"
+seed
+VICTIM="$(mktemp -d)"
+echo keep >"$VICTIM/keep.txt"
+ln -s "$VICTIM" "$SB/multi-agent-linked"
+GC_TMP_ROOT="$SB" GC_TMP_GRACE_MIN=0 bash "$GC" --yes >/dev/null 2>&1
+[ ! -e "$SB/multi-agent-linked" ] && pass "symlink itself removed" || fail "symlink survived"
+[ -f "$VICTIM/keep.txt" ] && pass "symlink target untouched" || fail "symlink target was deleted"
+rm -rf "$VICTIM"
+
+echo ""
+echo "→ 9. default grace spares fresh scratch"
+seed
+out=$(GC_TMP_ROOT="$SB" bash "$GC" --yes 2>&1)
+rc=$?
+[ "$rc" = "0" ] && pass "grace run exits 0" || fail "grace run exited $rc"
+[ -f "$SB/multi-agent-picker-PROJ-1.json" ] && pass "fresh scratch spared by default grace" || fail "default grace deleted fresh scratch"
+echo "$out" | grep -qi "spared" && pass "output mentions spared fresh items" || fail "no spared note in output"
+
 echo ""
 echo "══ gc-tmp smoke: $PASS passed, $FAIL failed ══"
 [ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-gc-worktrees.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# smoke-gc-worktrees.sh  -  contract of the worktree residue sweeper.
+#
+# Verifies gc-worktrees.sh: dry-run-by-default, orphan-dir removal only with
+# --yes, registered worktrees untouched, gitlink residue unstaged, exclude
+# guard added idempotently, --older-than sparing, non-repo no-op, and flag
+# validation.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT="$SCRIPT_DIR/gc-worktrees.sh"
+
+PASS=0
+FAIL=0
+record_pass() { PASS=$((PASS + 1)); printf '  \342\234\223 %s\n' "$1"; }
+record_fail() { FAIL=$((FAIL + 1)); printf '  \342\234\227 %s\n' "$1"; }
+
+printf '\342\206\222 smoke-gc-worktrees: worktree residue sweep contract\n'
+
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+
+# Fixture repo: one registered worktree, one orphan dir, one gitlink residue.
+REPO="$tmpdir/repo"
+mkdir -p "$REPO"
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.email smoke@test
+git -C "$REPO" config user.name smoke
+echo hi > "$REPO/f.txt"
+git -C "$REPO" add f.txt
+git -C "$REPO" commit -qm init
+git -C "$REPO" worktree add -q "$REPO/.worktrees/REG" -b reg-branch
+mkdir -p "$REPO/.worktrees/ORPHAN"
+echo x > "$REPO/.worktrees/ORPHAN/file"
+git -C "$REPO" update-index --add --cacheinfo "160000,$(git -C "$REPO" rev-parse HEAD),.worktrees/GONE"
+
+# 1. Script parses
+if bash -n "$SCRIPT" 2>/dev/null; then
+  record_pass "gc-worktrees.sh parses (bash -n)"
+else
+  record_fail "gc-worktrees.sh has syntax errors"
+fi
+
+# 2. Dry-run lists all three findings and deletes nothing
+out=$(bash "$SCRIPT" --repo "$REPO" 2>&1); rc=$?
+if [ "$rc" -eq 0 ] \
+  && printf '%s' "$out" | grep -q "would remove orphan worktree dir: .worktrees/ORPHAN" \
+  && printf '%s' "$out" | grep -q "would unstage gitlink residue from the index: .worktrees/GONE" \
+  && printf '%s' "$out" | grep -q "would add .worktrees/ to .git/info/exclude"; then
+  record_pass "dry-run lists orphan dir + gitlink + missing guard"
+else
+  record_fail "dry-run should list all three findings (rc=$rc): $out"
+fi
+if [ -d "$REPO/.worktrees/ORPHAN" ] && git -C "$REPO" ls-files -s -- .worktrees | grep -q 160000; then
+  record_pass "dry-run changed nothing"
+else
+  record_fail "dry-run must not delete or unstage anything"
+fi
+
+# 3. --older-than spares the freshly-touched orphan
+out=$(bash "$SCRIPT" --repo "$REPO" --older-than=60 2>&1)
+if printf '%s' "$out" | grep -q "would remove orphan"; then
+  record_fail "--older-than=60 should spare the fresh orphan dir"
+else
+  record_pass "--older-than spares recently-touched orphan dirs"
+fi
+
+# 4. --yes applies all three
+out=$(bash "$SCRIPT" --repo "$REPO" --yes 2>&1); rc=$?
+if [ "$rc" -eq 0 ] && [ ! -d "$REPO/.worktrees/ORPHAN" ]; then
+  record_pass "--yes removes the orphan dir"
+else
+  record_fail "--yes should remove the orphan dir (rc=$rc): $out"
+fi
+if git -C "$REPO" ls-files -s -- .worktrees | grep -q 160000; then
+  record_fail "--yes should unstage the gitlink residue"
+else
+  record_pass "--yes unstages the gitlink residue"
+fi
+if [ "$(grep -cxF '.worktrees/' "$REPO/.git/info/exclude" 2>/dev/null)" = "1" ]; then
+  record_pass "--yes adds the exclude guard exactly once"
+else
+  record_fail "exclude guard missing or duplicated"
+fi
+
+# 5. Registered worktree untouched
+if [ -d "$REPO/.worktrees/REG" ] && git -C "$REPO" worktree list | grep -q "REG"; then
+  record_pass "registered worktree left untouched"
+else
+  record_fail "registered worktree must never be touched"
+fi
+
+# 6. Re-run -> nothing to do, guard not duplicated
+out=$(bash "$SCRIPT" --repo "$REPO" 2>&1); rc=$?
+if [ "$rc" -eq 0 ] && printf '%s' "$out" | grep -q "nothing to do"; then
+  record_pass "clean repo -> nothing to do (exit 0)"
+else
+  record_fail "clean repo should be a no-op (rc=$rc): $out"
+fi
+bash "$SCRIPT" --repo "$REPO" --yes >/dev/null 2>&1
+if [ "$(grep -cxF '.worktrees/' "$REPO/.git/info/exclude")" = "1" ]; then
+  record_pass "exclude guard is idempotent across --yes reruns"
+else
+  record_fail "exclude guard duplicated on rerun"
+fi
+
+# 7. Non-repo -> silent no-op exit 0
+out=$(bash "$SCRIPT" --repo "$tmpdir" 2>&1); rc=$?
+if [ "$rc" -eq 0 ] && printf '%s' "$out" | grep -q "not a git work tree"; then
+  record_pass "non-repo -> exit 0 no-op"
+else
+  record_fail "non-repo should exit 0 with a no-op message (rc=$rc)"
+fi
+
+# 8. Unknown flag -> usage error exit 2
+bash "$SCRIPT" --definitely-not-a-flag >/dev/null 2>&1; rc=$?
+if [ "$rc" -eq 2 ]; then
+  record_pass "unknown flag -> exit 2"
+else
+  record_fail "unknown flag should exit 2 (got $rc)"
+fi
+
+printf '\n\342\225\220\342\225\220 smoke-gc-worktrees: %d passed, %d failed \342\225\220\342\225\220\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]