@mmerterden/multi-agent-pipeline 11.5.0 → 12.0.0

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

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 ]