@mmerterden/multi-agent-pipeline 11.5.0 → 12.1.0

package/pipeline/scripts/gc-tmp.sh

@@ -6,8 +6,15 @@
 # never cleaned up automatically (review.md traps its own, the rest linger), so
 # a long-lived machine accumulates them. This sweeps the known prefixes.
 #
-# SAFE BY DEFAULT: dry-run. It lists what WOULD be removed and the space it
-# would free, and deletes nothing until you pass --yes.
+# SAFE BY DEFAULT:
+#   - dry-run: lists what WOULD be removed and the space it would free, and
+#     deletes nothing until you pass --yes.
+#   - root guard: the scratch root must be an existing directory and is
+#     refused when it resolves to /, $HOME, or a git work tree, so a stray
+#     GC_TMP_ROOT can never sweep a home dir or a repo checkout.
+#   - fresh-scratch grace: items touched in the last GC_TMP_GRACE_MIN minutes
+#     (default 10) are spared, so a sweep during an in-flight run cannot pull
+#     scratch out from under it. GC_TMP_GRACE_MIN=0 disables the grace.
 #
 # Usage:
 #   gc-tmp.sh                      # dry-run: list matches + total size
@@ -16,13 +23,16 @@
 #   gc-tmp.sh --older-than=60 --yes
 #
 # Env:
-#   GC_TMP_ROOT   override the scratch root (default /tmp; tests set this)
+#   GC_TMP_ROOT       override the scratch root (default /tmp; tests set this)
+#   GC_TMP_GRACE_MIN  fresh-scratch grace window in minutes (default 10, 0 = off)
 #
-# Exit: 0 on success, 2 on usage error. Always exits 0 when nothing matches.
+# Exit: 0 on success, 2 on usage error or refused scratch root. Always exits 0
+# when nothing matches.
 
 set -uo pipefail
 
 ROOT="${GC_TMP_ROOT:-/tmp}"
+GRACE_MIN="${GC_TMP_GRACE_MIN:-10}"
 DELETE=0
 OLDER_MIN=0
 
@@ -51,9 +61,35 @@ for arg in "$@"; do
   esac
 done
 
+if ! printf '%s' "$GRACE_MIN" | grep -qE '^[0-9]+$'; then
+  echo "gc-tmp: GC_TMP_GRACE_MIN needs a whole number of minutes, got: $GRACE_MIN" >&2
+  exit 2
+fi
+
+if [ ! -d "$ROOT" ]; then
+  echo "gc-tmp: no scratch root at $ROOT  -  nothing to do"
+  exit 0
+fi
+
+# Root guard: resolve symlinks (macOS /tmp -> /private/tmp), then refuse
+# roots that can never be a scratch root. Sweeping $HOME by mistake would
+# match real dirs like ~/multi-agent-pipeline via the name prefixes below.
+ROOT="$(cd "$ROOT" 2>/dev/null && pwd -P)"
+if [ -z "$ROOT" ]; then
+  echo "gc-tmp: cannot resolve scratch root" >&2
+  exit 2
+fi
+HOME_REAL="$(cd "$HOME" 2>/dev/null && pwd -P || printf '%s' "$HOME")"
+if [ "$ROOT" = "/" ] || [ "$ROOT" = "$HOME_REAL" ] || [ -e "$ROOT/.git" ]; then
+  echo "gc-tmp: refusing scratch root $ROOT (/, \$HOME, or a git work tree is never a scratch root)" >&2
+  exit 2
+fi
+
 # Scratch prefixes the pipeline writes under $ROOT (see jira.md, review.md,
 # update-issue-progress.sh, channels/*.md, external-context-injection.md,
-# analysis.md). maxdepth 1 so we never descend into unrelated trees.
+# analysis.md). mindepth 1 so the root itself is never a candidate even when
+# its own name matches a prefix; maxdepth 1 so we never descend into
+# unrelated trees.
 NAME_ARGS=(
   -name 'multi-agent-*'
   -o -name 'issue-progress-*'
@@ -69,12 +105,24 @@ if [ "$OLDER_MIN" -gt 0 ]; then
 fi
 
 matches=()
+skipped_active=0
 while IFS= read -r -d '' p; do
+  # Fresh-scratch grace: spare items an in-flight run touched recently
+  # (checks the item and, for dirs, anything inside it).
+  if [ "$GRACE_MIN" -gt 0 ] &&
+    find "$p" -mmin "-$GRACE_MIN" -print 2>/dev/null | head -1 | grep -q .; then
+    skipped_active=$((skipped_active + 1))
+    continue
+  fi
   matches+=("$p")
-done < <(find "$ROOT" -maxdepth 1 \( "${NAME_ARGS[@]}" \) ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
+done < <(find "$ROOT" -mindepth 1 -maxdepth 1 \( "${NAME_ARGS[@]}" \) ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
 
 if [ "${#matches[@]}" -eq 0 ]; then
-  echo "gc-tmp: no leftover scratch under $ROOT  -  nothing to do"
+  if [ "$skipped_active" -gt 0 ]; then
+    echo "gc-tmp: only fresh scratch matched (touched in the last ${GRACE_MIN}m)  -  spared, nothing to do"
+  else
+    echo "gc-tmp: no leftover scratch under $ROOT  -  nothing to do"
+  fi
   exit 0
 fi
 
@@ -90,13 +138,24 @@ human="${total_kb} KB"
 if [ "$DELETE" -eq 0 ]; then
   echo "DRY-RUN  -  would remove ${#matches[@]} item(s) under $ROOT (frees ~${human}):"
   for p in "${matches[@]}"; do echo "  $p"; done
+  [ "$skipped_active" -gt 0 ] && echo "Spared $skipped_active fresh item(s) touched in the last ${GRACE_MIN}m."
   echo "Re-run with --yes to delete."
   exit 0
 fi
 
 removed=0
 for p in "${matches[@]}"; do
+  # Containment guard: only ever delete direct children of the resolved root.
+  case "$p" in
+    "$ROOT"/*) ;;
+    *)
+      echo "gc-tmp: skipping path outside scratch root: $p" >&2
+      continue
+      ;;
+  esac
   rm -rf "$p" 2>/dev/null && removed=$((removed + 1))
 done
-echo "══ garbage-collect: removed ${removed}/${#matches[@]} item(s), freed ~${human} ══"
+spared_note=""
+[ "$skipped_active" -gt 0 ] && spared_note=", spared $skipped_active fresh"
+echo "══ garbage-collect: removed ${removed}/${#matches[@]} item(s)${spared_note}, freed ~${human} ══"
 exit 0

package/pipeline/scripts/gc-worktrees.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# gc-worktrees.sh  -  sweep worktree residue in the current project repo.
+#
+# Complements gc-tmp.sh (which only touches /tmp scratch). This handles the
+# leftovers a worktree lifecycle can strand inside the repo itself:
+#
+#   1. stale worktree admin entries   -> git worktree prune
+#   2. orphan .worktrees/* dirs       -> dirs no longer registered as
+#      worktrees (killed mid-run, manual deletes). Listed in dry-run,
+#      removed only with --yes.
+#   3. gitlink residue in the index   -> .worktrees/{id} recorded as a
+#      "Subproject commit" entry by a blanket `git add -A` before the
+#      residue guard existed. --yes runs `git rm --cached` (the commit
+#      itself stays yours to make).
+#   4. missing residue guard          -> ensures `.worktrees/` is in
+#      .git/info/exclude so the gitlink class cannot re-occur.
+#
+# Registered, healthy worktrees are NEVER touched - finishing or killing a
+# task is /multi-agent:finish / /multi-agent:kill territory.
+#
+# SAFE BY DEFAULT: dry-run. Deletes nothing until you pass --yes.
+#
+# Usage:
+#   gc-worktrees.sh                     # dry-run in the current repo
+#   gc-worktrees.sh --yes               # apply
+#   gc-worktrees.sh --repo <path>       # operate on another repo
+#   gc-worktrees.sh --older-than=60     # only orphan dirs idle > 60 min
+#
+# Exit: 0 on success (including "nothing to do"), 2 on usage error.
+
+set -uo pipefail
+
+REPO="$PWD"
+DELETE=0
+OLDER_MIN=0
+
+usage() {
+  grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes | --force) DELETE=1; shift ;;
+    --repo)
+      REPO="${2:-}"
+      [ -z "$REPO" ] && { echo "gc-worktrees: --repo needs a path" >&2; exit 2; }
+      shift 2
+      ;;
+    --older-than=*)
+      OLDER_MIN="${1#*=}"
+      if ! printf '%s' "$OLDER_MIN" | grep -qE '^[0-9]+$'; then
+        echo "gc-worktrees: --older-than needs a whole number of minutes, got: $OLDER_MIN" >&2
+        exit 2
+      fi
+      shift
+      ;;
+    -h | --help) usage; exit 0 ;;
+    *) echo "gc-worktrees: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "gc-worktrees: $REPO is not a git work tree  -  nothing to do"
+  exit 0
+fi
+REPO="$(cd "$REPO" && pwd -P)"
+WT_ROOT="$REPO/.worktrees"
+
+changed=0
+
+# 1. Stale admin entries (safe on a clean repo, no confirmation needed:
+#    prune only drops bookkeeping for dirs that are already gone).
+pruned=$(git -C "$REPO" worktree prune -v 2>&1 | grep -c . || true)
+[ "$pruned" -gt 0 ] && echo "→ pruned $pruned stale worktree admin entr$( [ "$pruned" -eq 1 ] && echo y || echo ies)"
+
+# 2. Orphan dirs: present under .worktrees/ but not registered as worktrees.
+orphans=()
+if [ -d "$WT_ROOT" ]; then
+  registered=$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+  for d in "$WT_ROOT"/*/; do
+    [ -d "$d" ] || continue
+    dir="$(cd "$d" && pwd -P)"
+    # Path guard: only ever consider dirs strictly inside <repo>/.worktrees/.
+    case "$dir" in "$WT_ROOT"/*) ;; *) continue ;; esac
+    if printf '%s\n' "$registered" | grep -qxF "$dir"; then
+      continue  # healthy registered worktree - kill/finish territory
+    fi
+    if [ "$OLDER_MIN" -gt 0 ] && find "$dir" -type f -mmin "-$OLDER_MIN" 2>/dev/null | head -1 | grep -q .; then
+      continue  # recently touched - spare it
+    fi
+    orphans+=("$dir")
+  done
+fi
+for dir in ${orphans+"${orphans[@]}"}; do
+  size=$(du -sh "$dir" 2>/dev/null | cut -f1)
+  if [ "$DELETE" -eq 1 ]; then
+    rm -rf "$dir" && { echo "→ removed orphan worktree dir: ${dir#"$REPO"/} (${size:-?})"; changed=$((changed + 1)); }
+  else
+    echo "would remove orphan worktree dir: ${dir#"$REPO"/} (${size:-?})"
+  fi
+done
+
+# 3. Gitlink residue in the index ("Subproject commit" entries under
+#    .worktrees/ from a pre-guard `git add -A`).
+gitlinks=$(git -C "$REPO" ls-files -s -- .worktrees 2>/dev/null | awk '$1 == "160000" { print $4 }')
+if [ -n "$gitlinks" ]; then
+  while IFS= read -r path; do
+    [ -z "$path" ] && continue
+    if [ "$DELETE" -eq 1 ]; then
+      git -C "$REPO" rm --cached --ignore-unmatch -q -- "$path" \
+        && { echo "→ unstaged gitlink residue: $path (commit the removal yourself)"; changed=$((changed + 1)); }
+    else
+      echo "would unstage gitlink residue from the index: $path"
+    fi
+  done <<EOF
+$gitlinks
+EOF
+fi
+
+# 4. Residue guard: keep .worktrees/ out of the index from now on.
+ex="$(git -C "$REPO" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/info/exclude"
+if [ -n "${ex%/info/exclude}" ] && ! grep -qxF '.worktrees/' "$ex" 2>/dev/null; then
+  if [ "$DELETE" -eq 1 ]; then
+    mkdir -p "$(dirname "$ex")" \
+      && printf '.worktrees/\n' >> "$ex" \
+      && { echo "→ added .worktrees/ to .git/info/exclude (residue guard)"; changed=$((changed + 1)); }
+  else
+    echo "would add .worktrees/ to .git/info/exclude (residue guard)"
+  fi
+fi
+
+total=$(( ${#orphans[@]} + $(printf '%s' "$gitlinks" | grep -c . || true) ))
+if [ "$DELETE" -eq 1 ]; then
+  echo "══ gc-worktrees: applied $changed change(s) in $REPO ══"
+elif [ "$total" -eq 0 ] && [ "$pruned" -eq 0 ] && { [ -z "${ex%/info/exclude}" ] || grep -qxF '.worktrees/' "$ex" 2>/dev/null; }; then
+  echo "gc-worktrees: no worktree residue in $REPO  -  nothing to do"
+else
+  echo "══ gc-worktrees: dry-run  -  re-run with --yes to apply ══"
+fi
+exit 0

package/pipeline/scripts/localize-commands.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * localize-commands.mjs - swap slash-command picker descriptions between
+ * English and the outputLanguage variant in an INSTALLED command tree.
+ *
+ * The repo (and the npm package) always keeps English `description:` values;
+ * files that ship a `description-tr:` frontmatter line can be localized in
+ * place after install. The original English text is preserved in a
+ * `description-en:` sidecar line so the swap is fully reversible.
+ *
+ *   apply    description-en <- description, description <- description-tr
+ *   restore  description <- description-en, sidecar line removed
+ *
+ * Both modes are idempotent and only touch the three description* lines of
+ * the YAML frontmatter; every other byte is preserved. Files without a
+ * description-tr line are left untouched.
+ *
+ * Usage:
+ *   node localize-commands.mjs apply   [--dir <commandsDir>]
+ *   node localize-commands.mjs restore [--dir <commandsDir>]
+ *
+ * Default dir: $HOME/.claude/commands/multi-agent
+ * Exit: 0 on success (including missing dir), 2 on usage error.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join } from "path";
+
+const DESC = /^description:[ \t]*(.*)$/;
+const DESC_TR = /^description-tr:[ \t]*(.*)$/;
+const DESC_EN = /^description-en:[ \t]*(.*)$/;
+
+/**
+ * Swap the description of one SKILL.md. Returns true when the file changed.
+ *
+ * @param {string} file
+ * @param {"apply"|"restore"} mode
+ */
+export function localizeFile(file, mode) {
+  const original = readFileSync(file, "utf-8");
+  const lines = original.split("\n");
+  // Only operate inside the first frontmatter block.
+  if (lines[0] !== "---") return false;
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return false;
+
+  let descIdx = -1;
+  let trIdx = -1;
+  let enIdx = -1;
+  for (let i = 1; i < end; i++) {
+    if (descIdx < 0 && DESC.test(lines[i])) descIdx = i;
+    else if (trIdx < 0 && DESC_TR.test(lines[i])) trIdx = i;
+    else if (enIdx < 0 && DESC_EN.test(lines[i])) enIdx = i;
+  }
+  if (descIdx < 0) return false;
+
+  if (mode === "apply") {
+    if (trIdx < 0) return false;
+    const trValue = lines[trIdx].match(DESC_TR)[1];
+    const current = lines[descIdx].match(DESC)[1];
+    if (current === trValue) return false; // already applied
+    if (enIdx < 0) {
+      // Preserve the English original right after the description line.
+      lines.splice(descIdx + 1, 0, `description-en: ${current}`);
+    }
+    lines[descIdx] = `description: ${trValue}`;
+  } else {
+    if (enIdx < 0) return false;
+    const enValue = lines[enIdx].match(DESC_EN)[1];
+    lines[descIdx] = `description: ${enValue}`;
+    lines.splice(enIdx, 1);
+  }
+  const next = lines.join("\n");
+  if (next === original) return false;
+  writeFileSync(file, next);
+  return true;
+}
+
+/**
+ * Localize every SKILL.md directly in `dir` and one level below it.
+ *
+ * @param {string} dir
+ * @param {"apply"|"restore"} mode
+ * @returns {number} count of changed files
+ */
+export function localizeCommands(dir, mode) {
+  if (!existsSync(dir)) return 0;
+  const files = [];
+  const rootSkill = join(dir, "SKILL.md");
+  if (existsSync(rootSkill)) files.push(rootSkill);
+  for (const entry of readdirSync(dir)) {
+    const sub = join(dir, entry, "SKILL.md");
+    try {
+      if (statSync(join(dir, entry)).isDirectory() && existsSync(sub)) files.push(sub);
+    } catch {
+      // unreadable entry - skip
+    }
+  }
+  let changed = 0;
+  for (const f of files) {
+    try {
+      if (localizeFile(f, mode)) changed++;
+    } catch {
+      // never fail the whole run over one file
+    }
+  }
+  return changed;
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const mode = args[0];
+  if (mode !== "apply" && mode !== "restore") {
+    console.error("usage: localize-commands.mjs <apply|restore> [--dir <commandsDir>]");
+    process.exit(2);
+  }
+  let dir = join(process.env.HOME || process.env.USERPROFILE || "", ".claude", "commands", "multi-agent");
+  const dirFlag = args.indexOf("--dir");
+  if (dirFlag >= 0) {
+    if (!args[dirFlag + 1]) {
+      console.error("localize-commands: --dir needs a path");
+      process.exit(2);
+    }
+    dir = args[dirFlag + 1];
+  }
+  const changed = localizeCommands(dir, mode);
+  console.log(`localize-commands: ${mode} -> ${changed} file(s) changed in ${dir}`);
+}

package/pipeline/scripts/phase-tracker.sh

@@ -245,12 +245,14 @@ format_elapsed() {
 }
 
 # Cost table ships next to this script in every install tree (repo,
-# ~/.claude/scripts, ~/.copilot/scripts). Pricing math matches
-# render-agent-log-cost.sh exactly: tokens_in is FRESH input (cache-exclusive,
+# ~/.claude/scripts, ~/.copilot/scripts). Pricing math comes from cost-lib.sh
+# (shared with the other renderers): tokens_in is FRESH input (cache-exclusive,
 # per the disjoint token-count contract), tokens_cached is priced at the
 # discounted cacheReadPerMtok rate, floored to cents. A missing/unparseable
 # table never fails a caller - USD simply renders empty / "-".
 COST_TABLE="$(cd "$(dirname "$0")" && pwd)/cost-table.json"
+COST_LIB="$(cd "$(dirname "$0")" && pwd)/cost-lib.sh"
+if [ -f "$COST_LIB" ]; then . "$COST_LIB"; else COST_JQ_DEFS=""; fi
 
 # Print est. USD ("0.21") for one phase index or, with "total", the sum across
 # priceable phases. Prints "-" when nothing is priceable. Never non-zero exit.
@@ -258,19 +260,13 @@ phase_usd() {
   local selector="$1"  # integer phase index into .phases[], or "total"
   [ -f "$COST_TABLE" ] || { echo "-"; return 0; }
   local state; state="$(load_state)"
-  echo "$state" | jq -r --slurpfile prices "$COST_TABLE" --arg sel "$selector" '
-    def usd_of(p): ($prices[0].prices[p.model // ""] // null) as $rate |
-      if $rate == null then null
-      else ( ((p.tokens_in // 0) / 1000000) * $rate.inPerMtok
-           + ((p.tokens_cached // 0) / 1000000) * ($rate.cacheReadPerMtok // $rate.inPerMtok)
-           + ((p.tokens_out // 0) / 1000000) * $rate.outPerMtok )
-      end;
-    def floor_cents(u): if u == null then null else ((u * 100) | floor) / 100 end;
+  echo "$state" | jq -r --slurpfile prices "$COST_TABLE" --arg sel "$selector" "$COST_JQ_DEFS"'
+    def usd_of(p): cost_usd_of($prices[0].prices[p.model // ""] // null; (p.tokens_in // 0); (p.tokens_out // 0); (p.tokens_cached // 0));
     if $sel == "total" then
-      ([.phases[] | usd_of(.) | select(. != null)] | if length == 0 then "-" else (add | floor_cents(.) | tostring) end)
+      ([.phases[] | usd_of(.) | select(. != null)] | if length == 0 then "-" else (add | cost_floor_cents(.) | tostring) end)
     else
       (.phases[($sel | tonumber)] // null) as $p |
-      if $p == null then "-" else (usd_of($p) | floor_cents(.) | if . == null then "-" else tostring end) end
+      if $p == null then "-" else (usd_of($p) | cost_floor_cents(.) | if . == null then "-" else tostring end) end
     end
   ' 2>/dev/null || echo "-"
 }
@@ -372,13 +368,8 @@ render() {
     echo "$prices_json" | jq empty 2>/dev/null || prices_json='{"prices":{}}'
   fi
   local phase_data
-  phase_data=$(echo "$state" | jq -r --argjson prices "$prices_json" '
-    def usd_of(p): ($prices.prices[p.model // ""] // null) as $rate |
-      if $rate == null then null
-      else ( ((p.tokens_in // 0) / 1000000) * $rate.inPerMtok
-           + ((p.tokens_cached // 0) / 1000000) * ($rate.cacheReadPerMtok // $rate.inPerMtok)
-           + ((p.tokens_out // 0) / 1000000) * $rate.outPerMtok )
-      end;
+  phase_data=$(echo "$state" | jq -r --argjson prices "$prices_json" "$COST_JQ_DEFS"'
+    def usd_of(p): cost_usd_of($prices.prices[p.model // ""] // null; (p.tokens_in // 0); (p.tokens_out // 0); (p.tokens_cached // 0));
     .phases // []
     | sort_by(.id | (tonumber? // 9999))
     | .[] | [

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