@mmerterden/multi-agent-pipeline 16.18.0 → 16.20.0

package/pipeline/lib/fetch-crashlytics.sh

@@ -67,13 +67,15 @@ ISSUE_ID=""
 SESSION_ID=""
 TIMEOUT="${FIREBASE_TIMEOUT_SECONDS:-20}"
 
+need_value() { [ $# -ge 2 ] || { echo "ERR: $1 needs a value" >&2; exit 4; }; }
+
 while [ $# -gt 0 ]; do
   case "$1" in
-    --project)    PROJECT_ID="$2"; shift 2 ;;
-    --platform)   PLATFORM="$2";   shift 2 ;;
-    --bundle)     BUNDLE="$2";     shift 2 ;;
-    --issue-id)   ISSUE_ID="$2";   shift 2 ;;
-    --session-id) SESSION_ID="$2"; shift 2 ;;
+    --project)    need_value "$@"; PROJECT_ID="$2"; shift 2 ;;
+    --platform)   need_value "$@"; PLATFORM="$2";   shift 2 ;;
+    --bundle)     need_value "$@"; BUNDLE="$2";     shift 2 ;;
+    --issue-id)   need_value "$@"; ISSUE_ID="$2";   shift 2 ;;
+    --session-id) need_value "$@"; SESSION_ID="$2"; shift 2 ;;
     -h|--help)
       echo "usage: $0 <issue-url> | $0 --project ... --platform ... --bundle ... --issue-id ... [--session-id ...]" >&2
       exit 4 ;;
@@ -234,6 +236,7 @@ fi
 #   1. Build header + claim, base64url
 #   2. Sign with the SA private key
 #   3. POST to oauth2.googleapis.com/token
+TOKEN_RC=0
 ACCESS_TOKEN=$(SA_JSON_IN="$SA_JSON" python3 - <<'PY'
 import base64, json, os, sys, time, urllib.parse, urllib.request
 
@@ -302,10 +305,10 @@ except Exception as e:
     print("", file=sys.stderr)
     sys.exit(2)
 PY
-)
+) || TOKEN_RC=$?
 
-if [ -z "$ACCESS_TOKEN" ]; then
-  echo "ERR: Firebase token exchange failed" >&2
+if [ "$TOKEN_RC" -ne 0 ] || [ -z "$ACCESS_TOKEN" ]; then
+  echo "ERR: Firebase token exchange failed (exchange rc=$TOKEN_RC)" >&2
   exit 3
 fi
 

package/pipeline/lib/fetch-document.sh

@@ -31,7 +31,7 @@
 #   }
 #
 # Exit codes:
-#   0  success (may be degraded-empty for a pdf with no converter)
+#   0  success
 #   3  download or read failure
 #   4  bad usage / unsupported extension
 #   6  converter not available (pdf only; the orchestrator treats this as

package/pipeline/lib/fetch-figma-annotations.sh

@@ -89,13 +89,15 @@ BATCH=4
 log() { printf '%s\n' "$*" >&2; }
 die() { local code="$1"; shift; log "fetch-figma-annotations: $*"; exit "$code"; }
 
+need_value() { [ $# -ge 2 ] || die 1 "$1 requires a value"; }
+
 while [ $# -gt 0 ]; do
   case "$1" in
-    --file-key) FILE_KEY="${2:-}"; shift 2 ;;
-    --node-id) NODE_IDS="${2:-}"; shift 2 ;;
-    --url) URL="${2:-}"; shift 2 ;;
-    --lang-prefixes) LANG_PREFIXES="${2:-TR,EN}"; shift 2 ;;
-    --batch) BATCH="${2:-4}"; shift 2 ;;
+    --file-key) need_value "$@"; FILE_KEY="$2"; shift 2 ;;
+    --node-id) need_value "$@"; NODE_IDS="$2"; shift 2 ;;
+    --url) need_value "$@"; URL="$2"; shift 2 ;;
+    --lang-prefixes) need_value "$@"; LANG_PREFIXES="${2:-TR,EN}"; shift 2 ;;
+    --batch) need_value "$@"; BATCH="${2:-4}"; shift 2 ;;
     -h|--help) grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'; exit 0 ;;
     *) die 1 "unknown argument: $1" ;;
   esac

package/pipeline/lib/fetch-fortify.sh

@@ -62,11 +62,13 @@ ISSUE_ID=""
 TIMEOUT="${FORTIFY_TIMEOUT_SECONDS:-25}"
 AUTH_SCHEME="${FORTIFY_AUTH_SCHEME:-auto}"
 
+need_value() { [ $# -ge 2 ] || { echo "ERR: $1 needs a value" >&2; exit 4; }; }
+
 while [ $# -gt 0 ]; do
   case "$1" in
-    --version-id) VERSION_ID="$2"; shift 2 ;;
-    --issue)      ISSUE_ID="$2";   shift 2 ;;
-    --instance-id) ISSUE_ID="$2";  shift 2 ;;
+    --version-id) need_value "$@"; VERSION_ID="$2"; shift 2 ;;
+    --issue)      need_value "$@"; ISSUE_ID="$2";   shift 2 ;;
+    --instance-id) need_value "$@"; ISSUE_ID="$2";  shift 2 ;;
     -h|--help)
       echo "usage: $0 <ssc-url> | $0 --version-id <id> [--issue <id>] | $0 --instance-id <id>" >&2
       exit 4 ;;

package/pipeline/lib/fetch-graylog.sh

@@ -73,11 +73,13 @@ TIMEOUT="${GRAYLOG_TIMEOUT_SECONDS:-25}"
 RANGE="${GRAYLOG_RANGE_SECONDS:-86400}"
 LIMIT="${GRAYLOG_LIMIT:-200}"
 
+need_value() { [ $# -ge 2 ] || { echo "ERR: $1 needs a value" >&2; exit 4; }; }
+
 while [ $# -gt 0 ]; do
   case "$1" in
-    --trx)  TRX_ID="$2";  shift 2 ;;
-    --conv) CONV_ID="$2"; shift 2 ;;
-    --env)  ENVIRONMENT="$2"; shift 2 ;;
+    --trx)  need_value "$@"; TRX_ID="$2";  shift 2 ;;
+    --conv) need_value "$@"; CONV_ID="$2"; shift 2 ;;
+    --env)  need_value "$@"; ENVIRONMENT="$2"; shift 2 ;;
     -h|--help)
       echo "usage: $0 --trx <transaction-id> | --conv <conversation-id> [--env auto|prod|test]" >&2
       exit 4 ;;

package/pipeline/lib/figma-mcp-refresh.sh

@@ -85,7 +85,7 @@ refresh_grant_cfg() {
 
 RESPONSE=$(curl -s --max-time 20 -X POST "$TOKEN_ENDPOINT" \
   -H "Content-Type: application/x-www-form-urlencoded" \
-  -K <(refresh_grant_cfg))
+  -K <(refresh_grant_cfg)) || RESPONSE=""
 
 NEW_ACCESS=$(printf '%s' "$RESPONSE" | jq -r '.access_token // empty' 2>/dev/null || true)
 NEW_REFRESH=$(printf '%s' "$RESPONSE" | jq -r '.refresh_token // empty' 2>/dev/null || true)

package/pipeline/lib/figma-screenshot.sh

@@ -81,6 +81,8 @@ if ! command -v resolve_figma_token >/dev/null 2>&1; then
 fi
 
 FIGMA_API="https://api.figma.com/v1"
+WORK_DIR=$(mktemp -d "${TMPDIR:-/tmp}/figma-screenshot.XXXXXX")
+trap 'rm -rf "$WORK_DIR"' EXIT INT TERM
 PARALLEL_DL=4
 HTTP_TIMEOUT=60
 MAX_IDS_PER_CALL=50
@@ -126,7 +128,8 @@ Options:
                    hold the other channel's design" before a run may write that a
                    channel has none. Emits JSON, downloads nothing.
   --feature-slug   Feature name to match against, for --discover-sections.
-  --output-dir     Output directory. Default: /tmp/figma-screenshots-<ts>.
+  --output-dir     Output directory. Default: a fresh mktemp dir
+                   ($TMPDIR/figma-screenshots.XXXXXX).
   --scale          Render scale (1-4). Default: 2.
   --format         Image format. Default: png.
   --help           Show this help text and exit.
@@ -256,7 +259,7 @@ fetch_nodes_metadata() {
 fetch_image_urls() {
   local ids="$1"
   local tmp
-  tmp=$(mktemp)
+  tmp=$(mktemp "$WORK_DIR/images.XXXXXX")
   local url="$FIGMA_API/images/$FILE_KEY?ids=$ids&format=$FORMAT&scale=$SCALE"
   local code
   code=$(curl_figma "$tmp" "$url")
@@ -281,7 +284,7 @@ render_and_download() {
 
   # Emit a job list (nodeId<TAB>url<TAB>outPath) for parallel download.
   local jobs
-  jobs=$(mktemp)
+  jobs=$(mktemp "$WORK_DIR/jobs.XXXXXX")
   local key_prefix="${FILE_KEY:0:4}"
   printf '%s' "$urls_json" | jq -r 'to_entries[] | "\(.key)\t\(.value)"' \
     | while IFS=$'\t' read -r nid url; do
@@ -292,7 +295,7 @@ render_and_download() {
 
   # Parallel download. xargs -P keeps the channel count bounded.
   local results
-  results=$(mktemp)
+  results=$(mktemp "$WORK_DIR/results.XXXXXX")
   # shellcheck disable=SC2016
   awk -F'\t' '{printf "%s\037%s\037%s\n", $1,$2,$3}' "$jobs" \
     | xargs -P "$PARALLEL_DL" -I{} bash -c '
@@ -389,17 +392,19 @@ if [ "$#" -eq 0 ]; then
   exit 1
 fi
 
+need_value() { [ "$#" -ge 2 ] || die 1 "$1 requires a value"; }
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --help|-h) print_help; exit 0 ;;
-    --file-key) FILE_KEY="${2:-}"; shift 2 ;;
-    --node-id)  NODE_ID="${2:-}"; shift 2 ;;
-    --section)  SECTION_URL="${2:-}"; shift 2 ;;
+    --file-key) need_value "$@"; FILE_KEY="$2"; shift 2 ;;
+    --node-id)  need_value "$@"; NODE_ID="$2"; shift 2 ;;
+    --section)  need_value "$@"; SECTION_URL="$2"; shift 2 ;;
     --discover-sections) DISCOVER=1; shift ;;
-    --feature-slug) FEATURE_SLUG="${2:-}"; shift 2 ;;
-    --output-dir) OUTPUT_DIR="${2:-}"; shift 2 ;;
-    --scale)    SCALE="${2:-2}"; shift 2 ;;
-    --format)   FORMAT="${2:-png}"; shift 2 ;;
+    --feature-slug) need_value "$@"; FEATURE_SLUG="$2"; shift 2 ;;
+    --output-dir) need_value "$@"; OUTPUT_DIR="$2"; shift 2 ;;
+    --scale)    need_value "$@"; SCALE="${2:-2}"; shift 2 ;;
+    --format)   need_value "$@"; FORMAT="${2:-png}"; shift 2 ;;
     *) die 1 "unknown argument: $1" ;;
   esac
 done
@@ -431,7 +436,7 @@ if [ -z "${FIGMA_TOKEN:-}" ]; then
 fi
 
 if [ -z "$OUTPUT_DIR" ]; then
-  OUTPUT_DIR="/tmp/figma-screenshots-$(date +%Y%m%d-%H%M%S)"
+  OUTPUT_DIR=$(mktemp -d "${TMPDIR:-/tmp}/figma-screenshots.XXXXXX")
 fi
 mkdir -p "$OUTPUT_DIR"
 
@@ -444,14 +449,12 @@ mkdir -p "$OUTPUT_DIR"
 # "Elite Kart" on one section and "Elit Kart" on its sibling.
 
 run_discover_mode() {
-  local body
-  # Same as fetch_with_retry: the token goes through a curl config on a process
-  # substitution, never argv, because argv is readable from ps.
-  body=$(curl -sS --max-time "$HTTP_TIMEOUT" --connect-timeout 5 \
-    -K <(printf 'header = "X-Figma-Token: %s"\n' "$FIGMA_TOKEN") \
-    "https://api.figma.com/v1/files/${FILE_KEY}?depth=3") || die 3 "file tree fetch failed"
-
-  printf '%s' "$body" | FEATURE_SLUG="$FEATURE_SLUG" FILE_KEY="$FILE_KEY" python3 -c '
+  local tree code
+  tree=$(mktemp "$WORK_DIR/tree.XXXXXX")
+  code=$(curl_figma "$tree" "$FIGMA_API/files/${FILE_KEY}?depth=3")
+  handle_http_code "$code" "file tree for $FILE_KEY"
+
+  FEATURE_SLUG="$FEATURE_SLUG" FILE_KEY="$FILE_KEY" python3 -c '
 import json, os, re, sys, unicodedata
 
 def fold(t):
@@ -475,11 +478,11 @@ def channel_of(name):
                 return label
     return None
 
-raw = sys.stdin.read()
+raw = open(sys.argv[1]).read()
 try:
     doc = json.loads(raw).get("document", {})
 except Exception:
-    print(json.dumps({"error": "unparseable file response"})); sys.exit(3)
+    print(json.dumps({"error": "unparseable file response"})); sys.exit(6)
 
 slug_words = [w for w in fold(os.environ["FEATURE_SLUG"]).split() if len(w) > 2]
 out, weak, pages = [], [], 0
@@ -516,7 +519,7 @@ print(json.dumps({
     "candidates": sorted(out, key=lambda c: (c["channelGuess"] or "zz", c["id"])),
     "weakMatches": sorted(weak, key=lambda c: c["id"]),
 }, ensure_ascii=False, indent=2))
-'
+' "$tree"
 }
 
 # --- Section mode -----------------------------------------------------------
@@ -570,7 +573,7 @@ PY
 
   # Collect ids and chunk to MAX_IDS_PER_CALL.
   local ids_file
-  ids_file=$(mktemp)
+  ids_file=$(mktemp "$WORK_DIR/ids.XXXXXX")
   awk -F'\t' '{print $1}' "$lookup" > "$ids_file"
 
   local rows

package/pipeline/lib/figma-token.sh

@@ -31,8 +31,9 @@
 # An unset or non-executable CRED_STORE is tolerated: resolution falls through to
 # the env fallback so a keychain-less CI box still works.
 
-# The canonical key first, the legacy key second. Space-separated so the loop
-# below stays POSIX-ish and works under bash 3.2 (stock macOS).
+# The canonical key first, the legacy key second. Space-separated; the loop
+# below splits explicitly because zsh (the pipeline's Bash tool) does not
+# word-split an unquoted parameter, so `for key in $KEYS` saw one key there.
 FIGMA_TOKEN_LOGICAL_KEYS="${FIGMA_TOKEN_LOGICAL_KEYS:-figma figma_pat}"
 
 # resolve_figma_token
@@ -40,13 +41,16 @@ FIGMA_TOKEN_LOGICAL_KEYS="${FIGMA_TOKEN_LOGICAL_KEYS:-figma figma_pat}"
 resolve_figma_token() {
   local key tok
   if [ -n "${CRED_STORE:-}" ] && [ -x "${CRED_STORE:-}" ]; then
-    for key in $FIGMA_TOKEN_LOGICAL_KEYS; do
+    while IFS= read -r key; do
+      [ -n "$key" ] || continue
       tok=$("$CRED_STORE" get "$key" 2>/dev/null || true)
       if [ -n "$tok" ]; then
         printf '%s' "$tok"
         return 0
       fi
-    done
+    done <<EOF_KEYS
+$(printf '%s\n' "$FIGMA_TOKEN_LOGICAL_KEYS" | tr ' ' '\n')
+EOF_KEYS
   fi
   if [ -n "${FIGMA_PAT:-}" ]; then
     printf '%s' "$FIGMA_PAT"

package/pipeline/lib/issue-fetcher.sh

@@ -43,7 +43,6 @@
 # Required env:
 #   ACCOUNT_JIRA_TOKEN_KEY    keychain service name (optional)
 #   ACCOUNT_JIRA_HOST         e.g. jira.example.com    (optional)
-#   ACCOUNT_GH_TOKEN_KEY      keychain service name (optional)
 #   ACCOUNT_DEFAULT_OWNER     fallback GitHub owner (optional)
 #   ACCOUNT_DEFAULT_REPO      fallback GitHub repo  (optional)
 #   PROMPT_LANG               tr|en  -  controls maturity.summary language (default: tr)

package/pipeline/lib/jira-publish.sh

@@ -54,13 +54,15 @@ BACKUP_DIR="${JIRA_BACKUP_DIR:-$HOME/.claude/logs/multi-agent/jira-backups}"
 
 die() { echo "$1" >&2; exit "${2:-64}"; }
 
+need_value() { [ "$#" -ge 2 ] || die "$1 requires a value"; }
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
-    --issue) ISSUE="${2:-}"; shift 2 ;;
-    --body-file) BODY_FILE="${2:-}"; shift 2 ;;
-    --target) TARGET="${2:-}"; shift 2 ;;
-    --mode) MODE="${2:-}"; shift 2 ;;
-    --backup-dir) BACKUP_DIR="${2:-}"; shift 2 ;;
+    --issue) need_value "$@"; ISSUE="$2"; shift 2 ;;
+    --body-file) need_value "$@"; BODY_FILE="$2"; shift 2 ;;
+    --target) need_value "$@"; TARGET="$2"; shift 2 ;;
+    --mode) need_value "$@"; MODE="$2"; shift 2 ;;
+    --backup-dir) need_value "$@"; BACKUP_DIR="$2"; shift 2 ;;
     --confirm-overwrite) CONFIRM=1; shift ;;
     --dry-run) DRY_RUN=1; shift ;;
     -h|--help) sed -n '2,40p' "$0"; exit 0 ;;

package/pipeline/lib/md2confluence-v3.py

@@ -69,6 +69,11 @@ PUNCT_MAP_DEFAULT_TR = {
 PUNCT_MAP_EN = dict(PUNCT_MAP_DEFAULT_TR)
 PUNCT_MAP_EN["\u00A7"] = "section"
 
+# Typographic dashes (U+2010 to U+2015), quotes (U+2018 to U+201F), the
+# ellipsis and the section sign, including the variants the maps above do
+# not rewrite, so a residual can actually be reported.
+FORBIDDEN_PUNCT_RE = re.compile("[\u2010-\u2015\u2018-\u201F\u2026\u00A7]")
+
 
 def detect_language(markdown: str, front_matter_lang: str | None) -> str:
     if front_matter_lang:
@@ -76,12 +81,11 @@ def detect_language(markdown: str, front_matter_lang: str | None) -> str:
         if lang.startswith("en"):
             return "en"
         return "tr"
-    # Heuristic: presence of TR-only characters in headings
-    for line in markdown.splitlines():
-        if line.startswith("#"):
-            if re.search(r"[ğışçöü]", line):
-                return "tr"
-    return "tr"
+    # Heuristic: a Turkish document carries Turkish-only letters somewhere in
+    # its body; a text without a single one is English.
+    if re.search(r"[ğışçöüĞİŞÇÖÜ]", markdown):
+        return "tr"
+    return "en"
 
 
 def apply_punctuation_gate(text: str, language: str) -> tuple[str, list[str]]:
@@ -91,7 +95,9 @@ def apply_punctuation_gate(text: str, language: str) -> tuple[str, list[str]]:
         out = out.replace(src, dst)
 
     warnings: list[str] = []
-    leftover = [ch for ch in mapping.keys() if ch in out]
+    # The residual check must look wider than the mapping: every mapped
+    # character was just replaced, so testing those again can never fire.
+    leftover = sorted(set(FORBIDDEN_PUNCT_RE.findall(out)))
     if leftover:
         warnings.append(
             "punctuation gate: residual forbidden characters: "

package/pipeline/lib/multi-repo-pipeline.sh

@@ -33,7 +33,7 @@ set -euo pipefail
 CMD="${1:-}"
 STATE="${2:-}"
 [ -z "$CMD" ] || [ -z "$STATE" ] && {
-  echo "usage: $0 <prepare|commit|push|pr|teardown> <state.json>" >&2
+  echo "usage: $0 <prepare|bridge|commit|push|pr|teardown> <state.json>" >&2
   exit 1
 }
 [ ! -f "$STATE" ] && { echo "ERR: state file not found: $STATE" >&2; exit 2; }
@@ -54,6 +54,8 @@ TASK_ID=$(python3 -c "import json; d=json.load(open('$STATE')); print(d['taskId'
 COMMIT_TYPE=$(python3 -c "import json; d=json.load(open('$STATE')); print(d.get('commitType','feat'))")
 ISSUE_KEY=$(python3 -c "import json; d=json.load(open('$STATE')); print(d['issueRef'].get('key') or '')")
 ISSUE_TITLE=$(python3 -c "import json; d=json.load(open('$STATE')); print(d['issueRef'].get('title') or '')")
+IDENTITY_NAME=$(python3 -c "import json; d=json.load(open('$STATE')); print((d.get('identity') or {}).get('name') or '')")
+IDENTITY_EMAIL=$(python3 -c "import json; d=json.load(open('$STATE')); print((d.get('identity') or {}).get('email') or '')")
 
 cmd_prepare() {
   mkdir -p "$WORKTREE_ROOT"
@@ -90,24 +92,32 @@ cmd_commit() {
   # loop  -  a piped `while` runs in a subshell and the summary exit would
   # always be 0 regardless of per-repo failures.
   local failed=0
+  # state.identity is the commit author/committer, as documented in the schema
+  # above. Git's own config is the fallback when the picker recorded none.
+  local identity_args=()
+  if [ -n "$IDENTITY_NAME" ] && [ -n "$IDENTITY_EMAIL" ]; then
+    identity_args=(-c "user.name=$IDENTITY_NAME" -c "user.email=$IDENTITY_EMAIL")
+  fi
   while IFS=$'\t' read -r name url provider; do
     local target="$WORKTREE_ROOT/$name"
     [ ! -d "$target" ] && continue
     cd "$target"
-    # Use status --porcelain so untracked files count as "changes" too  -
-    # dev sessions usually add brand-new files alongside edits, and `git diff`
-    # alone misses them.
-    if [ -z "$(git status --porcelain 2>/dev/null)" ]; then
-      echo "[$name] no changes, skipping commit"
+    # Only what the dev session staged is committed. A blanket `git add -A`
+    # here swept build output and nested-worktree gitlinks into the commit.
+    if git diff --cached --quiet 2>/dev/null; then
+      if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+        echo "[$name] nothing staged (unstaged or untracked changes present)  -  stage what belongs in the commit, skipping"
+      else
+        echo "[$name] no changes, skipping commit"
+      fi
       cd - >/dev/null
       continue
     fi
-    git add -A
     local subject="$COMMIT_TYPE($name): $ISSUE_TITLE"
     [ -n "$ISSUE_KEY" ] && subject="$subject [$ISSUE_KEY]"
     # Trim subject to 72 chars
     subject=$(printf '%s' "$subject" | cut -c1-72)
-    if git commit --quiet -m "$subject"; then
+    if git ${identity_args[@]+"${identity_args[@]}"} commit --quiet -m "$subject"; then
       echo "[$name] committed: $subject"
     else
       echo "ERR: [$name] commit failed" >&2

package/pipeline/lib/plan-todos.sh

@@ -155,10 +155,19 @@ do_start() {
   write_state "$state_path" "$new"
 }
 
+require_todo() {
+  # $1 state path, $2 todo_id  -  exits 1 when the id is not in the plan.
+  if ! jq -e --arg id "$2" '(.plan.todos // []) | map(select(.id == $id)) | length > 0' "$1" >/dev/null 2>&1; then
+    echo "plan-todos: todo '$2' not found" >&2
+    exit 1
+  fi
+}
+
 do_complete() {
   local task_id="${1:-}"; local todo_id="${2:-}"; local notes="${3:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: complete <task-id> <todo-id> [notes]" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" --arg n "$notes" '
@@ -176,6 +185,7 @@ do_fail() {
   local task_id="${1:-}"; local todo_id="${2:-}"; local reason="${3:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] || [ -z "$reason" ] && { echo "usage: fail <task-id> <todo-id> <reason>" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" --arg r "$reason" '
@@ -190,6 +200,7 @@ do_skip() {
   local task_id="${1:-}"; local todo_id="${2:-}"; local reason="${3:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] || [ -z "$reason" ] && { echo "usage: skip <task-id> <todo-id> <reason>" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" --arg r "$reason" '

package/pipeline/lib/post-pr-review.sh

@@ -408,9 +408,16 @@ post_bitbucket_server() {
     needs_work) status_payload='{"status":"NEEDS_WORK"}' ;;
   esac
 
-  curl -sS -m 30 -K <(bb_auth_cfg "$auth_user" "$auth_token") -X PUT \
+  local http
+  http=$(curl -sS -m 30 -K <(bb_auth_cfg "$auth_user" "$auth_token") -X PUT \
     -H "Content-Type: application/json" "$base/participants/$user_slug" \
-    -d "$status_payload" >/dev/null
+    -d "$status_payload" -o /dev/null -w '%{http_code}' || echo 000)
+  case "$http" in
+    200|201) ;;
+    *)
+      echo "post-pr-review: bitbucket verdict PUT failed (HTTP $http) for PR #$PR_NUM  -  $DECISION was NOT recorded" >&2
+      return 4 ;;
+  esac
 }
 
 # --- Main switch ------------------------------------------------------------

package/pipeline/lib/repo-cache.sh

@@ -18,12 +18,13 @@
 #   ./repo-cache.sh bitbucket <workspace> [--refresh]
 #
 # Required env per-provider:
-#   github    -> GH_TOKEN_KEY (keychain service)
+#   github    -> (none)  -  uses the gh CLI's own auth; GH_USER selects the account
 #   bitbucket -> BB_TOKEN_KEY, BB_USER_KEY, BB_HOST (e.g. bitbucket.example.com)
 #   local     -> (none)  -  scopes are treated as filesystem roots; "scope=$HOME"
 #                walks $HOME with maxdepth, scope=<path> walks just that path.
-#                LOCAL_SCAN_ROOTS env can override the default root list.
-#                LOCAL_SCAN_MAXDEPTH env (default 4) bounds traversal cost.
+#                LOCAL_SCAN_ROOTS env (colon-separated, like PATH) overrides the
+#                default root list. LOCAL_SCAN_MAXDEPTH env (default 4) bounds
+#                traversal cost.
 
 set -euo pipefail
 
@@ -211,16 +212,23 @@ print(json.dumps(out))
   local)
     # Scan filesystem roots for git repos. Default roots cover the common
     # places personal/work checkouts live; override via LOCAL_SCAN_ROOTS.
-    DEFAULT_ROOTS="$HOME $HOME/Documents $HOME/Developer $HOME/projects $HOME/code $HOME/work"
-    ROOTS="${LOCAL_SCAN_ROOTS:-$DEFAULT_ROOTS}"
-    MAXDEPTH="${LOCAL_SCAN_MAXDEPTH:-4}"
-    # When SCOPE is an absolute path use it directly; otherwise treat SCOPE
-    # as a label and walk the configured roots.
+    # Roots are held in an array, never a whitespace-split string: a HOME with
+    # a space in it split into two nonexistent roots and the scan found nothing.
+    ROOTS=()
     if [ -d "$SCOPE" ]; then
-      ROOTS="$SCOPE"
+      ROOTS=("$SCOPE")
+    elif [ -n "${LOCAL_SCAN_ROOTS:-}" ]; then
+      while IFS= read -r root; do
+        [ -n "$root" ] && ROOTS+=("$root")
+      done <<EOF_ROOTS
+$(printf '%s\n' "$LOCAL_SCAN_ROOTS" | tr ':' '\n')
+EOF_ROOTS
+    else
+      ROOTS=("$HOME" "$HOME/Documents" "$HOME/Developer" "$HOME/projects" "$HOME/code" "$HOME/work")
     fi
+    MAXDEPTH="${LOCAL_SCAN_MAXDEPTH:-4}"
     : > "$CACHE_TMP.list"
-    for root in $ROOTS; do
+    for root in ${ROOTS[@]+"${ROOTS[@]}"}; do
       [ -d "$root" ] || continue
       # -prune avoids descending into already-found .git trees (nested submodules
       # show up via submodule-detector, not the top-level picker).

package/pipeline/lib/review-watch.sh

@@ -10,11 +10,16 @@
 #   - Reads watched repos from prefs.global.reviewWatch.repos[] (or --repos).
 #   - For each repo, lists open PRs since the last seen cursor (state in
 #     ~/.claude/state/review-watch/<owner-repo>.json).
-#   - For each PR not yet reviewed (or updated since last review), invokes
-#     `bash $HOME/.claude/lib/post-pr-review.sh <task-id>` after writing the
-#     PR input to agent-state.json. The reviewer dispatch itself is the
-#     responsibility of /multi-agent:review's LLM loop; review-watch is just
-#     the trigger.
+#   - For each PR not yet reviewed (or updated since last review), writes the
+#     PR input to a per-PR agent-state.json (see Storage) and prints the
+#     dispatch line. The review itself is /multi-agent:review's LLM loop,
+#     which fills `.review.findings` for that task id; review-watch never
+#     spends tokens.
+#   - On a later scan, a PR whose agent-state carries findings for the
+#     current head SHA is posted through post-pr-review.sh, and only a
+#     successful post stamps reviewed_prs[<n>] = <sha>. A PR is never marked
+#     reviewed without a review having been posted.
+#     REVIEW_WATCH_DRY_RUN=1 reports what would be posted and stamps nothing.
 #   - Honors labelFilter (only review PRs carrying the label, default: all).
 #   - Skips PRs the user authored (we don't review our own PRs through this
 #     surface  -  that's what the in-pipeline Phase 4 / standalone /review is
@@ -36,13 +41,26 @@
 #   ~/.claude/state/review-watch/<owner__repo>.json
 #     { last_seen_iso: "2026-05-11T12:34:56Z",
 #       reviewed_prs: { "1234": "head-sha-abc" } }
+#   ~/.claude/logs/multi-agent/review-watch/<owner__repo>-pr<n>/agent-state.json
+#     { taskId, review: { input: {...}, headCommitSha, findings? } }
+#     (task id <owner__repo>-pr<n>; post-pr-review.sh reads it by that id)
 
 set -euo pipefail
 
 PREFS="$HOME/.claude/multi-agent-preferences.json"
 STATE_DIR="$HOME/.claude/state/review-watch"
+REVIEW_LOGS="$HOME/.claude/logs/multi-agent/review-watch"
 mkdir -p "$STATE_DIR"
 
+POSTER=""
+for _cand in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/post-pr-review.sh" \
+             "$HOME/.claude/lib/post-pr-review.sh" \
+             "$HOME/.copilot/lib/post-pr-review.sh" \
+             "$HOME/.codex/lib/post-pr-review.sh"; do
+  [ -f "$_cand" ] && { POSTER="$_cand"; break; }
+done
+unset _cand
+
 CMD="${1:-}"
 shift || true
 
@@ -192,16 +210,44 @@ review_one_repo() {
       continue
     fi
 
+    local task_id state_file
+    task_id="${repo//\//__}-pr${pr_num}"
+    state_file="$REVIEW_LOGS/$task_id/agent-state.json"
+
+    # Findings already written for THIS head by /multi-agent:review: post them.
+    # The stamp below is the only place reviewed_prs is written, and it is
+    # written only after post-pr-review.sh returned 0.
+    if [ -f "$state_file" ] \
+       && [ "$(jq -r '.review.headCommitSha // ""' "$state_file" 2>/dev/null)" = "$head_sha" ] \
+       && jq -e '.review.findings | type == "array"' "$state_file" >/dev/null 2>&1; then
+      if [ "${REVIEW_WATCH_DRY_RUN:-0}" = "1" ]; then
+        printf '  dry-run: would post the review for PR #%s (task %s) via post-pr-review.sh\n' "$pr_num" "$task_id"
+      elif [ -z "$POSTER" ]; then
+        err "post-pr-review.sh not found  -  PR #$pr_num stays pending"
+      elif bash "$POSTER" "$task_id"; then
+        printf '  posted review for PR #%s at %s\n' "$pr_num" "$head_sha"
+        state=$(jq --arg n "$pr_num" --arg s "$head_sha" \
+          '.reviewed_prs[$n] = $s' <<<"$state")
+      else
+        err "post-pr-review.sh failed for $repo PR #$pr_num  -  stays pending, not stamped"
+      fi
+      continue
+    fi
+
+    # No review for this head yet: write the input /multi-agent:review reads
+    # and hand off. review-watch does not run the LLM itself, because token
+    # cost decisions stay with the user; the PR stays un-stamped until a
+    # review is actually posted.
     printf '  dispatch review: %s PR #%s  -  %s\n' "$repo" "$pr_num" "$title"
-    printf '    url=%s head=%s\n' "$url" "$head_sha"
-
-    # Record that we reviewed this head SHA. The actual dispatch happens
-    # via /multi-agent:review on the surface that invoked review-watch
-    # (Claude Code session or future webhook handler). review-watch only
-    # produces the dispatch list  -  it does not run the LLM itself, because
-    # token cost decisions stay with the user.
-    state=$(jq --arg n "$pr_num" --arg s "$head_sha" \
-      '.reviewed_prs[$n] = $s' <<<"$state")
+    printf '    url=%s head=%s task=%s\n' "$url" "$head_sha" "$task_id"
+    mkdir -p "$(dirname "$state_file")"
+    jq -n --arg repo "$repo" --arg n "$pr_num" --arg sha "$head_sha" \
+          --arg url "$url" --arg title "$title" --arg t "$task_id" '
+      { schemaVersion: "2.1.0", taskId: $t,
+        review: { input: { kind: "pr", provider: "github", host: "github.com",
+                           orgRepo: $repo, prNumber: ($n | tonumber),
+                           url: $url, title: $title },
+                  headCommitSha: $sha, iterationNumber: 1 } }' > "$state_file"
   done < <(jq -c '.[]' <<<"$prs_json")
 
   # Persist the NEWEST updatedAt seen this scan  -  the previous per-PR