@seanyao/roll 2.602.4 → 2.603.1

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2.602.4"
+VERSION="2.603.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -5519,26 +5519,20 @@ import prices_fetcher as pf
 
 snapshot_dir = os.path.join(lib_dir, "prices")
 
-# FIX-116: vendor-specific default URLs.
-VENDOR_URLS = {
-    "anthropic": "https://platform.claude.com/docs/en/about-claude/pricing",
-    "deepseek":  "https://api-docs.deepseek.com/quick_start/pricing",
-    "kimi":      "https://platform.kimi.com/docs/pricing/chat",
-}
-
 if vendor:
-    default_url = VENDOR_URLS.get(vendor)
-    if not default_url:
+    if vendor not in pf.VENDOR_REGISTRY:
         print(f"$(msg prices_refresh.roll_unknown_vendor_vendor)", file=sys.stderr)
         print(f"$(msg prices_refresh.roll_known_vendors_join_sorted_vendor)", file=sys.stderr)
         sys.exit(1)
-    url = override_url or default_url
-    pf.DEFAULT_SOURCE_URL = url
 else:
-    url = override_url or pf.DEFAULT_SOURCE_URL
+    vendor = "anthropic"
 
 try:
-    action, changes = pf.refresh(snapshot_dir=snapshot_dir, url=url)
+    action, changes = pf.refresh(
+        snapshot_dir=snapshot_dir,
+        vendor=vendor,
+        url=override_url or None,
+    )
 except pf.FetchError as exc:
     print(f"[roll] fetch failed: {exc}", file=sys.stderr)
     print("[roll] keeping existing snapshot, no changes written  保留旧快照，未写入新文件",
@@ -5577,42 +5571,127 @@ cmd_prices() {
   esac
 }
 
+# FIX-178: AI-style a deterministic changelog draft into the project voice via
+# the configured agent (roll agent use). Content-preserving polish only — same
+# items + (ID)s, bold-lead style anchored on the last 3 released versions. Echoes
+# the styled draft on success; empty output on any failure so the caller falls
+# back to the deterministic raw draft. Bounded by a 150s watchdog (macOS lacks
+# timeout(1)). Uses the same agent path as peer review (_agent_argv).
+_changelog_ai_style() {
+  local raw="$1"
+  [ -n "$raw" ] || return 1
+  local agent; agent=$(_project_agent)
+  local anchors; anchors=$(_changelog_style_anchors CHANGELOG.md 2>/dev/null || true)
+  local prompt
+  prompt="你是 roll 的 changelog 编辑。把【原始草稿】改写成发布说明,严格遵守:
+1) 不增删条目、不改事实;每条保留它的(ID)。只润色措辞。
+2) 每条格式:\`- **简短标题(ID)** — 补充说明\`;若原条目结尾有 \`[loop]\` 则保留。
+3) 保留每个 ### 分类标题与分组。只输出 markdown,从 '## Unreleased' 开始,前后不要任何解释。
+
+【风格锚点·最近版本】
+${anchors}
+
+【原始草稿】
+${raw}"
+  _agent_argv "$agent" text "$prompt" 2>/dev/null || return 1
+  _agent_bypass_claude_perms
+  local out; out=$(mktemp)
+  "${_AGENT_ARGV[@]}" >"$out" 2>/dev/null &
+  local pid=$!
+  local waited=0
+  while kill -0 "$pid" 2>/dev/null; do
+    sleep 1; waited=$((waited + 1))
+    if [ "$waited" -ge 150 ]; then
+      kill "$pid" 2>/dev/null; sleep 1; kill -9 "$pid" 2>/dev/null; break
+    fi
+  done
+  wait "$pid" 2>/dev/null
+  # Normalize agent chrome before extracting: some agents (e.g. kimi) prefix the
+  # rendered answer with a "• " marker and indent the body. Changelog markdown is
+  # flat (##, ###, -, blank), so stripping a leading "• " and any leading
+  # whitespace is safe and is a no-op for plain agents (e.g. claude -p). Then
+  # keep from the first '## Unreleased' line onward (drops any preamble).
+  sed -E 's/^[[:space:]]*•[[:space:]]?//; s/^[[:space:]]+//' "$out" \
+    | awk '/^## Unreleased/{f=1} f{print}'
+  rm -f "$out"
+}
+
+# FIX-178: replace (or insert) the ## Unreleased section of CHANGELOG.md with
+# the given draft (which itself begins with '## Unreleased'). getline-from-file
+# keeps the multi-line draft intact.
+_changelog_write_unreleased() {
+  local draft="$1" cl="${2:-CHANGELOG.md}"
+  local dfile; dfile=$(mktemp); printf '%s\n' "$draft" > "$dfile"
+  local tmp; tmp=$(mktemp)
+  if [ -f "$cl" ] && grep -q '^## Unreleased' "$cl"; then
+    awk -v df="$dfile" '
+      /^## Unreleased/ && !done { while ((getline line < df) > 0) print line; print ""; skip=1; done=1; next }
+      skip && /^## / { skip=0 }
+      skip { next }
+      { print }
+    ' "$cl" > "$tmp"
+  else
+    { [ -f "$cl" ] && head -1 "$cl" || echo "# Changelog"; echo; cat "$dfile"; echo;
+      [ -f "$cl" ] && tail -n +2 "$cl"; } > "$tmp"
+  fi
+  mv "$tmp" "$cl"; rm -f "$dfile"
+}
+
 # FIX-113: changelog audit — list PRs merged to main since latest release
 # tag that don't appear in CHANGELOG.md's ## Unreleased section.
 # US-CL-006: changelog generate — deterministic draft from backlog Done stories.
+# FIX-178: generate now AI-styles the deterministic draft via the configured
+# agent by default (content-preserving); --no-ai / --json stay deterministic.
 cmd_changelog() {
-  local subcmd="${1:-audit}"
+  local subcmd="${1:-generate}"
   shift || true
   case "$subcmd" in
-    audit)
-      python3 "${ROLL_PKG_DIR}/lib/changelog_audit.py" "$@"
-      ;;
     generate)
-      python3 "${ROLL_PKG_DIR}/lib/changelog_generate.py" "$@"
+      local want_ai=1 to_write=0 is_json=0 pyargs=()
+      local a
+      for a in "$@"; do
+        case "$a" in
+          --no-ai) want_ai=0 ;;
+          --write) to_write=1 ;;
+          --json)  is_json=1; want_ai=0; pyargs+=("$a") ;;
+          *)       pyargs+=("$a") ;;
+        esac
+      done
+      local raw
+      raw=$(python3 "${ROLL_PKG_DIR}/lib/changelog_generate.py" "${pyargs[@]}") || return 1
+      if [ "$is_json" = 1 ]; then printf '%s\n' "$raw"; return 0; fi
+      local final="$raw"
+      if [ "$want_ai" = 1 ]; then
+        local styled; styled=$(_changelog_ai_style "$raw" 2>/dev/null || true)
+        if [ -n "$styled" ] && printf '%s' "$styled" | grep -q '^- '; then
+          final="$styled"
+        else
+          warn "changelog: AI 润色不可用/失败,输出确定性草稿(可加 --no-ai 跳过)"
+        fi
+      fi
+      if [ "$to_write" = 1 ]; then
+        _changelog_write_unreleased "$final"
+        info "Updated CHANGELOG.md"
+      else
+        printf '%s\n' "$final"
+      fi
       ;;
     --help|-h|help)
       cat <<EOF
-Usage: roll changelog <subcommand>
-
-  audit [--since <tag>] [--json]        发版前体检
-    Scan PRs merged to main since latest v* tag; flag ones that look user-visible
-    (carry US-/FIX-/REFACTOR- id) but are missing from CHANGELOG.md '## Unreleased'.
-
-  generate [--write] [--json]           从 backlog 生成草稿
-    Extract ✅ Done stories from .roll/backlog.md, filter internal entries,
-    apply lint, and produce a draft ## Unreleased section.
-
-  roll changelog audit                  # check against latest v* tag
-  roll changelog audit --since v2026.520.1
-  roll changelog audit --json           # machine-readable
-  roll changelog generate               # preview draft to stdout
-  roll changelog generate --write       # append draft to CHANGELOG.md
-  roll changelog generate --json        # machine-readable
+Usage: roll changelog generate [options]
+
+  从 backlog ✅ Done 故事 + 上次发布以来的提交,生成 ## Unreleased 发布说明。
+  默认用配置的 agent(roll agent use)按项目风格润色;失败自动回退确定性草稿。
+
+  roll changelog generate               # 预览(AI 润色)
+  roll changelog generate --write       # 写入 CHANGELOG.md(AI 润色)
+  roll changelog generate --no-ai       # 仅确定性草稿,不调 AI
+  roll changelog generate --json        # 机器可读(确定性)
 EOF
       ;;
     *)
       err "$(msg changelog.unknown_subcommand ${subcmd})"
-      err "Try: roll changelog audit | roll changelog generate"
+      err "Try: roll changelog generate"
       return 1
       ;;
   esac
@@ -8273,6 +8352,7 @@ _write_alert_loop_runner_script() {
   local script_path="$1" project_path="$2" roll_bin="$3" log_path="$4"
   mkdir -p "$(dirname "$script_path")"
   local lock="${project_path}/.roll/loop/.alert-loop.lock"
+  local slug; slug=$(_project_slug "${project_path}")
   cat > "$script_path" << ALERTRUNNER
 #!/bin/bash -l
 set -o pipefail
@@ -8297,6 +8377,15 @@ fi
 printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$LOCK"
 trap 'rm -f "\$LOCK"' EXIT
 cd "${project_path}" || exit 0
+# FIX-171: bake the project-local runtime dir directly; do not rely on
+# _loop_runtime_dir which may fail to resolve in fresh shells. Set
+# _LOOP_ALERT so the dispatched roll reads the project-local ALERT file,
+# but do not override an externally-supplied value (test sandboxes).
+_LOOP_RT_DIR="${project_path}/.roll/loop"
+if [ -d "\$_LOOP_RT_DIR" ]; then
+  : "\${_LOOP_ALERT:=\${_LOOP_RT_DIR}/ALERT-${slug}.md}"
+  export _LOOP_ALERT
+fi
 bash "${roll_bin}" _alert_dispatch >> "${log_path}" 2>&1 || true
 ALERTRUNNER
   chmod +x "$script_path"
@@ -8559,6 +8648,11 @@ _runs_append() {
   if [ -n "\$_story_field" ]; then
     _stype_field="\${_story_field%%-*}"
   fi
+  # US-LOOP-068: target field — roll-meta for roll-meta stories, empty otherwise
+  local _target_field=""
+  if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+    _target_field="roll-meta"
+  fi
   # US-EVAL-002: compute the objective result_eval block from this cycle's
   # facts via the US-EVAL-001 pure-function rubric. Best-effort — when python3
   # or the scorer script is unavailable the row is written WITHOUT result_eval
@@ -8608,6 +8702,7 @@ _runs_append() {
     --arg tier "\$_tier_field" \\
     --arg fallback_from "\$_fallback_from_field" \\
     --arg story_type "\$_stype_field" \\
+    --arg target "\$_target_field" \\
     --argjson built "\$_built" \\
     --argjson skipped '[]' \\
     --argjson alerts '[]' \\
@@ -8618,6 +8713,7 @@ _runs_append() {
       cycle_id:\$cycle_id, agent:\$agent, tier:\$tier, fallback_from:\$fallback_from,
       story_type:\$story_type, built:\$built, skipped:\$skipped, alerts:\$alerts,
       tcr_count:\$tcr_count, duration_sec:\$duration_sec, phases:\$phases}
+     + (if \$target == "" then {} else {target:\$target} end)
      + (if \$result_eval == null then {} else {result_eval:\$result_eval} end)' \\
     > "\$_tmp" 2>/dev/null || { rm -f "\$_tmp"; return 0; }
   # FIX-157: ensure target exists before append; missing file silently drops
@@ -8849,6 +8945,10 @@ for _orphan_wt in "\${_SHARED_ROOT}/worktrees/${slug}-cycle-"*; do
       ( cd "\$_orphan_wt" && _loop_publish_pr "\$_orphan_branch" "recover orphan \${_orphan_branch}" ) && _orphan_ok=1
     fi
     if [ "\$_orphan_ok" -eq 1 ]; then
+      # US-LOOP-068: if orphan contains a roll-meta worktree, clean it first
+      if [ -d "\${_orphan_wt}/.roll/.git" ]; then
+        _loop_roll_meta_worktree_cleanup "\$_orphan_wt" "\$_orphan_branch" "${project_path}" 2>/dev/null || true
+      fi
       _worktree_cleanup "\$_orphan_wt" "\$_orphan_branch"
       echo "[loop] FIX-040: orphan recovered and cleaned: \$_orphan_branch"
     else
@@ -8856,6 +8956,10 @@ for _orphan_wt in "\${_SHARED_ROOT}/worktrees/${slug}-cycle-"*; do
     fi
   else
     echo "[loop] FIX-040: orphan worktree \$_orphan_wt has no commits; cleaning up"
+    # US-LOOP-068: if orphan contains a roll-meta worktree, clean it first
+    if [ -d "\${_orphan_wt}/.roll/.git" ]; then
+      _loop_roll_meta_worktree_cleanup "\$_orphan_wt" "\$_orphan_branch" "${project_path}" 2>/dev/null || true
+    fi
     _worktree_cleanup "\$_orphan_wt" "\$_orphan_branch"
   fi
 done
@@ -8873,6 +8977,16 @@ if _worktree_fetch_origin main \\
   # because .roll/ is gitignored and the clean clone has no backlog
   # for Claude to read or skill entry points to dispatch to.
   _worktree_sync_meta "\$WT" 2>/dev/null || true
+  # US-LOOP-068: for roll-meta stories, replace the synced .roll/ with a
+  # real roll-meta git worktree so commits land in roll-meta remote.
+  if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+    if _loop_roll_meta_worktree_setup "\$WT" "\$BRANCH" "${project_path}" 2>/dev/null; then
+      echo "[loop] cycle \${CYCLE_ID}: roll-meta worktree \${WT}/.roll on \$BRANCH"
+    else
+      echo "[loop] cycle \${CYCLE_ID}: roll-meta worktree setup failed — falling back to normal"
+      _ROLL_META_TARGET=0
+    fi
+  fi
   echo "[loop] cycle \${CYCLE_ID}: worktree \$WT on \$BRANCH"
   _loop_event cycle_start "\${CYCLE_ID}" "" "" || true
   # US-AGENT-006: per-story routing — pick the next Todo, route to an agent
@@ -8929,6 +9043,15 @@ if _worktree_fetch_origin main \\
   fi
   CYCLE_AGENT="\${ROLL_LOOP_ROUTED_AGENT:-\$(_project_agent)}"
   _loop_event agent_used "\${CYCLE_ID}" "\${CYCLE_AGENT}" "primary" || true
+  # US-LOOP-068: detect roll-meta target after routing is complete
+  _ROLL_META_TARGET=0
+  if [ -n "\$ROLL_LOOP_ROUTED_STORY" ]; then
+    if _loop_is_roll_meta_story "\$ROLL_LOOP_ROUTED_STORY" "\${ROLL_MAIN_PROJECT}/.roll/backlog.md" 2>/dev/null; then
+      _ROLL_META_TARGET=1
+      echo "[loop] story \${ROLL_LOOP_ROUTED_STORY} is roll-meta target"
+    fi
+  fi
+  export ROLL_LOOP_ROLL_META_TARGET="\${_ROLL_META_TARGET}"
   _phase_end worktree_setup ok
 else
   # P3 fix: skip the cycle entirely when worktree isolation fails.
@@ -9071,12 +9194,25 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
   if [ "\$_exit" -ne 0 ]; then
     _cycle_status="failed"
   else
-    _cycle_commits_pre=\$(cd "\$WT" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    # US-LOOP-068: for roll-meta stories, count commits in the roll-meta worktree
+    if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+      _cycle_commits_pre=\$(cd "\$WT/.roll" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    else
+      _cycle_commits_pre=\$(cd "\$WT" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    fi
     if [ "\$_cycle_commits_pre" -gt 0 ]; then
       _cycle_status="built"
-      _cycle_tcr=\$(cd "\$WT" && git log --oneline origin/main..HEAD -- 2>/dev/null | grep -c ' tcr:' || echo 0)
+      if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+        _cycle_tcr=\$(cd "\$WT/.roll" && git log --oneline origin/main..HEAD -- 2>/dev/null | grep -c ' tcr:' || echo 0)
+      else
+        _cycle_tcr=\$(cd "\$WT" && git log --oneline origin/main..HEAD -- 2>/dev/null | grep -c ' tcr:' || echo 0)
+      fi
       if command -v jq >/dev/null 2>&1; then
-        _cycle_built=\$(cd "\$WT" && git diff origin/main -- .roll/backlog.md 2>/dev/null | grep '✅ Done' | grep -oE '\[[A-Z]+-[0-9]+\]' | sed 's/^.//;s/.\$//' | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
+        if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+          _cycle_built=\$(cd "\$WT/.roll" && git diff origin/main -- backlog.md 2>/dev/null | grep '✅ Done' | grep -oE '\[[A-Z]+-[0-9]+\]' | sed 's/^.//;s/.\$//' | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
+        else
+          _cycle_built=\$(cd "\$WT" && git diff origin/main -- .roll/backlog.md 2>/dev/null | grep '✅ Done' | grep -oE '\[[A-Z]+-[0-9]+\]' | sed 's/^.//;s/.\$//' | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
+        fi
       fi
     fi
   fi
@@ -9097,8 +9233,17 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
   if [ "\$_exit" -eq 0 ]; then
     # Idle cycle — no commits ahead of origin/main means nothing was built;
     # skip publish and reclaim the worktree immediately.
-    _cycle_commits=\$(cd "\$WT" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    # US-LOOP-068: for roll-meta stories, count commits in roll-meta worktree
+    if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+      _cycle_commits=\$(cd "\$WT/.roll" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    else
+      _cycle_commits=\$(cd "\$WT" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    fi
     if [ "\$_cycle_commits" -eq 0 ]; then
+      # US-LOOP-068: clean up roll-meta worktree before product worktree
+      if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+        _loop_roll_meta_worktree_cleanup "\$WT" "\$BRANCH" "${project_path}" 2>/dev/null || true
+      fi
       _worktree_cleanup "\$WT" "\$BRANCH"
       _loop_event idle "\${CYCLE_ID}" "" "" || true
       # FIX-F (2026-05-25): explicitly write the terminal "idle" cycle_end +
@@ -9115,12 +9260,42 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
       echo "[loop] cycle \${CYCLE_ID}: idle (no new commits); worktree cleaned"
     else
       _is_doc_only=0
-      ( cd "\$WT" && _loop_is_doc_only_change ) && _is_doc_only=1
+      # US-LOOP-068: for roll-meta stories, doc-only check runs in roll-meta worktree
+      if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+        ( cd "\$WT/.roll" && _loop_is_doc_only_change ) && _is_doc_only=1
+      else
+        ( cd "\$WT" && _loop_is_doc_only_change ) && _is_doc_only=1
+      fi
+      # US-LOOP-069: roll-meta boundary guard — abort if a roll-meta story touched product files
+      if ! _loop_guard_roll_meta_boundary "\$WT" "\$ROLL_LOOP_ROUTED_STORY"; then
+        _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
+        _phases_guard=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_guard" ] && _phases_guard='{}'
+        _runs_append "failed" 0 "[]" "\$_phases_guard" 2>/dev/null || true
+        echo "[loop] cycle \${CYCLE_ID}: US-LOOP-069 blocked — roll-meta story touched product files; worktree preserved at \$WT"
+        trap '_inner_cleanup' EXIT
+        exit 0
+      fi
+      # US-LOOP-068: roll-meta test gate — run roll-meta tests when ops/ changed
+      if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+        if ! _loop_roll_meta_test_gate "\$WT"; then
+          _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
+          _phases_test=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_test" ] && _phases_test='{}'
+          _runs_append "failed" 0 "[]" "\$_phases_test" 2>/dev/null || true
+          echo "[loop] cycle \${CYCLE_ID}: roll-meta test gate failed; worktree preserved at \$WT"
+          trap '_inner_cleanup' EXIT
+          exit 0
+        fi
+      fi
       _phase_begin publish_push
-      if [ "\$_is_doc_only" -eq 1 ]; then
-        ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
+      # US-LOOP-068: roll-meta stories publish to roll-meta remote
+      if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+        _loop_roll_meta_publish "\$WT" "\$BRANCH" "loop cycle \${CYCLE_ID}"
       else
-        ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" )
+        if [ "\$_is_doc_only" -eq 1 ]; then
+          ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
+        else
+          ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" )
+        fi
       fi
       _publish_status=\$?
       if [ "\$_publish_status" -eq 0 ]; then
@@ -9140,6 +9315,10 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
         # so dashboard renders #NN ✓/↩/… correctly. Must run while branch ref
         # is still resolvable on remote — gh pr view <branch> needs the head ref.
         _loop_emit_pr_final "\$BRANCH" 2>/dev/null || true
+        # US-LOOP-068: clean up roll-meta worktree before product worktree
+        if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+          _loop_roll_meta_worktree_cleanup "\$WT" "\$BRANCH" "${project_path}" 2>/dev/null || true
+        fi
         _worktree_cleanup "\$WT" "\$BRANCH"
         _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
         # US-OBS-014: normal-completion path — push a fresh status snapshot.
@@ -9147,15 +9326,42 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
         _phase_end cleanup ok
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
       elif [ "\$_publish_status" -eq 2 ]; then
-        if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+        # US-LOOP-068: for roll-meta, merge_back doesn't apply — skip straight to
+        # the orphan-push safety net (roll-meta commits live on a different remote).
+        _merged_back=0
+        if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+          :
+        elif ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
           _worktree_cleanup "\$WT" "\$BRANCH"
           # US-LOOP-005 T3: gh unavailable + ff merge_back OK → cycle_end done
           _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
           echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
+          _merged_back=1
+        fi
+        # FIX-039: gh unavailable + merge_back failed — push orphan branch+tag to origin
+        # as final safety net so code is never local-only before worktree cleanup.
+        # Skip entirely when merge_back already finalized the cycle (the worktree is
+        # gone, so re-pushing from \$WT would spuriously fail and raise a false alert).
+        # US-LOOP-068: for roll-meta, push from roll-meta worktree
+        if [ "\$_merged_back" -ne 1 ]; then
+        _orphan_tag="loop-orphan-\${CYCLE_ID}"
+        if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+          if ( cd "\$WT/.roll" && git push origin "\$BRANCH" 2>/dev/null \
+               && git tag "\$_orphan_tag" 2>/dev/null \
+               && git push origin "\$_orphan_tag" 2>/dev/null ); then
+            _loop_roll_meta_worktree_cleanup "\$WT" "\$BRANCH" "${project_path}" 2>/dev/null || true
+            _worktree_cleanup "\$WT" "\$BRANCH"
+            # US-LOOP-005 T4: gh unavailable + orphan push OK → cycle_end orphan
+            _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
+            _worktree_alert "cycle \${CYCLE_ID}: gh+merge_back failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
+            echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
+          else
+            # US-LOOP-005 T5: gh unavailable + all failed → cycle_end failed
+            _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
+            _worktree_alert "cycle \${CYCLE_ID}: gh+merge_back+push all failed; worktree preserved at \$WT"
+            echo "[loop] cycle \${CYCLE_ID}: all publish paths failed; worktree preserved at \$WT"
+          fi
         else
-          # FIX-039: gh unavailable + merge_back failed — push orphan branch+tag to origin
-          # as final safety net so code is never local-only before worktree cleanup.
-          _orphan_tag="loop-orphan-\${CYCLE_ID}"
           if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \
                && git tag "\$_orphan_tag" 2>/dev/null \
                && git push origin "\$_orphan_tag" 2>/dev/null ); then
@@ -9171,23 +9377,43 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
             echo "[loop] cycle \${CYCLE_ID}: all publish paths failed; worktree preserved at \$WT"
           fi
         fi
+        fi
       else
         # FIX-039: PR publish failed — push orphan branch+tag to origin as safety net.
         # (_loop_publish_pr may have already pushed the branch; git push is idempotent.)
+        # US-LOOP-068: for roll-meta, push from roll-meta worktree
         _orphan_tag="loop-orphan-\${CYCLE_ID}"
-        if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \
-             && git tag "\$_orphan_tag" 2>/dev/null \
-             && git push origin "\$_orphan_tag" 2>/dev/null ); then
-          _worktree_cleanup "\$WT" "\$BRANCH"
-          # US-LOOP-005 T6: PR publish failed + orphan push OK → cycle_end orphan
-          _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
-          _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
-          echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
+        if [ "\${_ROLL_META_TARGET:-0}" = "1" ]; then
+          if ( cd "\$WT/.roll" && git push origin "\$BRANCH" 2>/dev/null \
+               && git tag "\$_orphan_tag" 2>/dev/null \
+               && git push origin "\$_orphan_tag" 2>/dev/null ); then
+            _loop_roll_meta_worktree_cleanup "\$WT" "\$BRANCH" "${project_path}" 2>/dev/null || true
+            _worktree_cleanup "\$WT" "\$BRANCH"
+            # US-LOOP-005 T6: PR publish failed + orphan push OK → cycle_end orphan
+            _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
+            _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
+            echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
+          else
+            # US-LOOP-005 T7: PR publish failed + orphan push failed → cycle_end failed
+            _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
+            _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
+            echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
+          fi
         else
-          # US-LOOP-005 T7: PR publish failed + orphan push failed → cycle_end failed
-          _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
-          _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
-          echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
+          if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \
+               && git tag "\$_orphan_tag" 2>/dev/null \
+               && git push origin "\$_orphan_tag" 2>/dev/null ); then
+            _worktree_cleanup "\$WT" "\$BRANCH"
+            # US-LOOP-005 T6: PR publish failed + orphan push OK → cycle_end orphan
+            _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
+            _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
+            echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
+          else
+            # US-LOOP-005 T7: PR publish failed + orphan push failed → cycle_end failed
+            _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
+            _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
+            echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
+          fi
         fi
       fi
     fi
@@ -11434,7 +11660,10 @@ _loop_pr_do_heal() {
 _loop_pr_merge_approved() {
   local num="$1" ci_state="$2" mergeable="$3" slug="$4"
   [ -n "$num" ] && [ -n "$slug" ] || return 0
-  [ "$ci_state" = "success" ] && [ "$mergeable" = "MERGEABLE" ] || return 0
+  [ "$ci_state" = "success" ] || return 0
+  # MERGEABLE (GraphQL mergeable) or CLEAN (mergeStateStatus) — see
+  # _loop_pr_merge_self_eager for why both spellings must be accepted.
+  case "$mergeable" in MERGEABLE|CLEAN) ;; *) return 0 ;; esac
   if gh -R "$slug" pr merge "$num" --squash --delete-branch >/dev/null 2>&1; then
     info "PR #${num}: human-approved + CI green — merged"
   else
@@ -11490,7 +11719,7 @@ EOF
 # can enforce them at Step 2 (story pickup). Pure functions, no side effects.
 #
 # BACKLOG row format (relevant fragments):
-#   | [US-AUTO-033](...) | desc `depends-on:US-AUTO-037` `manual-only:true` | 📋 Todo |
+#   | [US-AUTO-033](...) | desc `depends-on:US-AUTO-037` | 📋 Todo |
 #   | FIX-100 | desc `depends-on:US-A,US-B` | 📋 Todo |
 #
 # Row matching is anchored on `^| [?<id>\b` so a story-id appearing in some
@@ -11539,15 +11768,14 @@ _loop_check_depends_on() {
   return 0
 }
 
-# _loop_is_manual_only <story-id> [backlog-path]
-#   Exit 0: story's own row carries any manual-only:<value> tag.
-#   Exit 1: tag absent, story-id not found, or backlog missing.
-#
-# FIX-109: loop used to accept only the literal `manual-only:true` value;
-# anything else (e.g. `manual-only:roll-meta`, `manual-only:sean-yao`) was
-# ignored and the story got picked. Now any non-empty `manual-only:<value>`
-# qualifies — lets users tag rows reserved for a specific human or scope.
-_loop_is_manual_only() {
+# FIX-172: detect whether a story routes its output to roll-meta — path-based,
+# never tag-based. A story is a roll-meta target iff its declared deliverable
+# **Files:** include a path under .roll/ that is NOT a status-management file
+# (.roll/backlog.md, .roll/features/). Every cycle flips its own backlog/feature
+# status under .roll/, so "touches .roll/" must NOT flag a product story; only a
+# genuine roll-meta deliverable (e.g. .roll/ops/watch.sh) counts.
+# Returns 0 when the story delivers to roll-meta.
+_loop_is_roll_meta_story() {
   local id="$1"
   local backlog="${2:-.roll/backlog.md}"
   [ -n "$id" ] || return 1
@@ -11557,7 +11785,30 @@ _loop_is_manual_only() {
   row=$(grep -E "^\| \[?${id}[]| ]" "$backlog" | head -1)
   [ -n "$row" ] || return 1
 
-  echo "$row" | grep -qE 'manual-only:[A-Za-z0-9_.-]+'
+  # Resolve the feature file from the row's markdown link: [id](path.md#anchor).
+  # Links appear in two relative forms — ".roll/features/x.md" (rel. to product
+  # root) or "features/x.md" (rel. to .roll). Normalise from "features/" onward
+  # and resolve against the backlog's own directory (the roll-meta root).
+  local link featrel metadir feat
+  link=$(printf '%s\n' "$row" | grep -oE '\([^)]+\.md' | head -1 | sed -E 's/^\(//')
+  [ -n "$link" ] || return 1
+  featrel=$(printf '%s\n' "$link" | sed -E 's#^.*(features/.*)#\1#')
+  metadir=$(dirname "$backlog")
+  feat="${metadir}/${featrel}"
+  [ -f "$feat" ] || return 1
+
+  # Extract this story's **Files:** block, then test for a roll-meta deliverable
+  # path (under .roll/ but not the universal status-management files).
+  awk -v id="$id" '
+    $0 ~ ("^## " id "( |$)") {insec=1; next}
+    insec && /^## / {exit}
+    insec && /^\*\*Files:\*\*/ {infiles=1; next}
+    insec && infiles && /^\*\*/ {exit}
+    insec && infiles {print}
+  ' "$feat" \
+    | grep -oE '\.roll/[A-Za-z0-9_./-]+' \
+    | grep -vE '^\.roll/backlog\.md$|^\.roll/features/' \
+    | grep -q .
 }
 
 # US-AUTO-034: PR-first inbox — loop processes open PRs before scanning BACKLOG.
@@ -11598,6 +11849,17 @@ _loop_pr_classify() {
       fi
       echo "loop_self"; return 0
       ;;
+    claude/*)
+      # Claude-agent-authored PRs are loop-owned for autonomous merge/rebase
+      # once green — same treatment as loop/* — so they close within a
+      # PR-loop tick instead of waiting on a human or a GHA bot review.
+      # CI-red claude/* PRs are deliberately NOT routed to background heal
+      # (no agent re-spawn); they fall through to the stale/eligible paths
+      # below so a human decides what to do with a failing run.
+      if [[ "$ci_state" != "failure" ]]; then
+        echo "loop_self"; return 0
+      fi
+      ;;
   esac
 
   case "$human_review" in
@@ -11605,7 +11867,10 @@ _loop_pr_classify() {
     APPROVED)          echo "blocked_human_approved";         return 0 ;;
   esac
 
-  if [ "$ci_state" = "failure" ] || [ "$mergeable" = "CONFLICTING" ] || [ "$mergeable" = "BEHIND" ]; then
+  # CONFLICTING is the GraphQL `mergeable` enum; DIRTY/BEHIND are
+  # `mergeStateStatus` values (_loop_pr_inbox feeds the latter). Accept both
+  # spellings so a conflicting/out-of-date PR is reliably routed to rebase.
+  if [ "$ci_state" = "failure" ] || [ "$mergeable" = "CONFLICTING" ] || [ "$mergeable" = "DIRTY" ] || [ "$mergeable" = "BEHIND" ]; then
     echo "stale"
     return 0
   fi
@@ -11795,7 +12060,12 @@ _loop_pr_rebase_stale() {
 #   spec name. Both coexist until Phase 2 collapses the inbox path.
 _loop_pr_merge_self_eager() {
   local num="$1" ci_state="$2" mergeable="$3" slug="$4"
-  [ "$ci_state" = "success" ] && [ "$mergeable" = "MERGEABLE" ] || return 0
+  [ "$ci_state" = "success" ] || return 0
+  # Accept both the GraphQL `mergeable` enum (MERGEABLE) and the
+  # `mergeStateStatus` enum (CLEAN). _loop_pr_inbox feeds mergeStateStatus, so
+  # a ready-to-merge PR arrives as CLEAN in production — without it the eager
+  # merge never fired and self-PRs silently waited on repo-level auto-merge.
+  case "$mergeable" in MERGEABLE|CLEAN) ;; *) return 0 ;; esac
   gh -R "$slug" pr merge "$num" --squash --delete-branch >/dev/null 2>&1 \
     && info "PR #${num}: loop_self CI green — merged" \
     || warn "PR #${num}: loop_self merge failed — left open"
@@ -11847,7 +12117,7 @@ _loop_pr_inbox() {
       # All gates cleared (bot-approved + CI green + no conflicts) → merge directly.
       # Relying on repo-level auto-merge being configured is not reliable; loop
       # owns the decision here since it already ran the review.
-      if [ "$ci_state" = "success" ] && [ "$mergeable" = "MERGEABLE" ]; then
+      if [ "$ci_state" = "success" ] && { [ "$mergeable" = "MERGEABLE" ] || [ "$mergeable" = "CLEAN" ]; }; then
         gh -R "$slug" pr merge "$num" --squash --delete-branch >/dev/null 2>&1 \
           && info "PR #${num}: bot-approved + CI green — merged" \
           || warn "PR #${num}: merge failed (bot-approved + CI green) — left open"
@@ -11866,7 +12136,21 @@ _loop_pr_inbox() {
 
     case "$verdict" in
       loop_self)
-        _loop_pr_merge_self_eager "$num" "$ci_state" "$mergeable" "$slug"
+        # Green self-PR: merge when clean, else rebase onto main first. A
+        # loop/* or claude/* PR that fell BEHIND or now CONFLICTS with main can
+        # never auto-merge until rebased — eager-merge alone would leave it
+        # stuck open forever. Rebase is circuit-gated (≥3 attempts/24h → ALERT)
+        # and merges on a later tick once the rebased head is green + clean.
+        case "$mergeable" in
+          BEHIND|DIRTY|CONFLICTING)
+            if _loop_pr_rebase_circuit "$num"; then
+              _loop_pr_rebase_stale "$num" "$head_ref" || true
+            fi
+            ;;
+          *)
+            _loop_pr_merge_self_eager "$num" "$ci_state" "$mergeable" "$slug"
+            ;;
+        esac
         ;;
       loop_self_ci_red)
         # US-LOOP-062a: a red loop/* PR (classified by US-LOOP-049) is now
@@ -11902,7 +12186,7 @@ _loop_pr_inbox() {
 #
 # Loop-safe building blocks for the future PR Loop (com.roll.pr.<slug>.plist,
 # 5-min cadence). Phase 1 ships the helpers + tests only; Phase 2 (runner /
-# plist / main-loop wiring) is manual-only and out of scope here.
+# plist / main-loop wiring) is wired by hand and out of scope here.
 #
 # All helpers are lenient on a missing `gh` binary or any gh failure: they
 # return 0 so a loop iteration never aborts on a single bad PR. State writes
@@ -12091,7 +12375,7 @@ _loop_pr_route() {
 # These six helpers collect CI timing data, classify failures, auto-rerun
 # transient flakes, and surface flaky / degradation signals as backlog
 # entries. They are NOT yet wired into any runner or launchd plist — that is
-# Phase 2 (manual-only:true). Each is unit-tested in
+# Phase 2 (wired by hand). Each is unit-tested in
 # tests/unit/roll_loop_ci_loop.bats with gh stubbed. Do not delete or inline.
 #
 # State lives under project-local .roll/state/:
@@ -12125,9 +12409,20 @@ _ci_record_timing() {
   local dir; dir=$(_ci_state_dir)
   local file="${dir}/ci-timing.jsonl"
 
-  # Idempotency: skip if this run_id is already recorded.
+  # Idempotency: skip if this run_id is already recorded with a non-empty
+  # conclusion. If the existing record has an empty conclusion and the new
+  # data has a conclusion, update in-place so in-progress runs are completed.
   if [ -f "$file" ] && grep -q "\"run_id\":${run_id}," "$file" 2>/dev/null; then
-    return 0
+    local existing_conclusion new_conclusion
+    existing_conclusion=$(grep "\"run_id\":${run_id}," "$file" 2>/dev/null | jq -r '.conclusion // ""' 2>/dev/null)
+    new_conclusion=$(echo "$json" | jq -r '.conclusion // ""' 2>/dev/null)
+    if [ -n "$existing_conclusion" ] || [ -z "$new_conclusion" ]; then
+      return 0
+    fi
+    # Remove the stale line so the new record can be appended below.
+    local tmpfile="${file}.tmp.$$"
+    grep -v "\"run_id\":${run_id}," "$file" > "$tmpfile" 2>/dev/null || true
+    mv "$tmpfile" "$file"
   fi
 
   workflow=$(echo "$json" | jq -r '.workflowName // .name // ""' 2>/dev/null)
@@ -12446,7 +12741,7 @@ _ci_scan() {
 # that every loop appends to but nobody reads. The Alert Loop turns it into a
 # real consumer: parse → dedup (1h per category) → notify (error always) →
 # log → rotate. They are NOT yet wired into any runner or launchd plist — that
-# is Phase 2 (manual-only:true). Each is unit-tested in
+# is Phase 2 (wired by hand). Each is unit-tested in
 # tests/unit/roll_loop_alert_loop.bats with _notify stubbed. Do not delete or
 # inline.
 #
@@ -12856,7 +13151,13 @@ _skill_write_self_score() {
     *) err "_skill_write_self_score: verdict must be good / ok / regression (got '$verdict')"; return 1 ;;
   esac
 
+  # FIX-176: anchor notes to <project>/.roll/notes regardless of cwd. When
+  # invoked with cwd already inside the .roll dir (e.g. a self-score run from
+  # within .roll), the bare ".roll/notes" doubled to .roll/.roll/notes.
   local notes_dir=".roll/notes"
+  if [ "$(basename "$PWD")" = ".roll" ]; then
+    notes_dir="notes"
+  fi
   mkdir -p "$notes_dir"
   local ts; ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
   local date_part="${ts%%T*}"
@@ -13113,7 +13414,7 @@ _changelog_audit_gate() {
 # US-AUTO-036: worktree helpers (loop-safe pure additions).
 #
 # Phase 1 of worktree isolation — these helpers are NOT yet called by
-# runner.sh. US-AUTO-037 (manual-only) wires them into
+# runner.sh. US-AUTO-037 (wired by hand) wires them into
 # _write_loop_runner_script. Do not delete or inline; they are unit-tested
 # in tests/unit/roll_worktree.bats.
 
@@ -13214,6 +13515,58 @@ _worktree_sync_meta() {
   fi
 }
 
+# US-LOOP-068: set up .roll/ inside the product worktree as a roll-meta git worktree.
+# Must be called after the product worktree is created.
+# Returns 0 on success, 1 on failure.
+_loop_roll_meta_worktree_setup() {
+  local wt="$1" branch="$2" project_path="$3"
+  local meta_repo="${project_path}/.roll"
+  [ -d "$meta_repo/.git" ] || { echo "[loop] roll-meta setup: ${meta_repo} is not a git repo"; return 1; }
+  rm -rf "${wt}/.roll"
+  git -C "$meta_repo" worktree add "${wt}/.roll" -b "$branch" "origin/main"
+}
+
+# US-LOOP-068: clean up the roll-meta worktree inside the product worktree.
+_loop_roll_meta_worktree_cleanup() {
+  local wt="$1" branch="$2" project_path="$3"
+  local meta_repo="${project_path}/.roll"
+  [ -d "$meta_repo/.git" ] || return 0
+  git -C "$meta_repo" worktree remove --force "${wt}/.roll" 2>/dev/null || true
+  rm -rf "${wt}/.roll" 2>/dev/null || true
+  git -C "$meta_repo" branch -D "$branch" 2>/dev/null || true
+}
+
+# US-LOOP-068: publish a PR from the roll-meta worktree.
+_loop_roll_meta_publish() {
+  local wt="$1" branch="$2" title="$3"
+  (cd "${wt}/.roll" && _loop_publish_pr "$branch" "$title")
+}
+
+# US-LOOP-068: run roll-meta test gate when .roll/ops/ files are modified.
+# Returns 0 when no ops changes or tests pass; 1 when tests fail.
+_loop_roll_meta_test_gate() {
+  local wt="$1"
+  local _ops_changed
+  _ops_changed=$(cd "${wt}/.roll" && git diff --name-only origin/main..HEAD 2>/dev/null | grep '^ops/' || true)
+  [ -n "$_ops_changed" ] || return 0
+  if ! command -v bats >/dev/null 2>&1; then
+    echo "[loop] roll-meta ops/ changed but bats not installed — skipping test gate"
+    return 0
+  fi
+  local _test_dir="${wt}/.roll/ops/tests"
+  if [ ! -d "$_test_dir" ]; then
+    echo "[loop] roll-meta ops/ changed but no $_test_dir found — skipping test gate"
+    return 0
+  fi
+  echo "[loop] roll-meta test gate: bats ${_test_dir}"
+  if ! bats "${_test_dir}" 2>/dev/null; then
+    echo "[loop] roll-meta test gate failed"
+    return 1
+  fi
+  echo "[loop] roll-meta test gate passed"
+  return 0
+}
+
 # _worktree_merge_back <branch>
 #   Caller must be in the main worktree (cwd = main). Steps:
 #     1. git pull --ff-only origin main   (sync local main with remote)
@@ -13412,8 +13765,8 @@ refs/heads/claude/*"
 # v1 type/est/risk routing). lib/agent_routes_lint.py is no longer invoked.
 
 # FIX-146: per-story eligibility gate, reusable for pick and re-validation.
-# Exit 0 when the story id is eligible to be worked (📋 Todo, not manual-only,
-# deps satisfied, no open PR). Exit 1 otherwise.
+# Exit 0 when the story id is eligible to be worked (📋 Todo, deps satisfied,
+# no open PR). Exit 1 otherwise.
 # Args: <story-id> [backlog-path] [open-pr-titles]
 _loop_story_is_eligible() {
   local id="$1"
@@ -13431,13 +13784,10 @@ _loop_story_is_eligible() {
   _status=$(printf '%s\n' "$row" | awk -F'|' '{for(i=NF;i>=1;i--) if($i ~ /[^ \t]/) {gsub(/^[ \t]+|[ \t]+$/, "", $i); print $i; exit}}')
   [ "$_status" = "📋 Todo" ] || return 1
 
-  # Gate 1: manual-only
-  _loop_is_manual_only "$id" "$backlog" 2>/dev/null && return 1
-
-  # Gate 2: depends-on
+  # Gate 1: depends-on
   _loop_check_depends_on "$id" "$backlog" >/dev/null 2>&1 || return 1
 
-  # Gate 3 (FIX-141): skip if an open PR already references this story id.
+  # Gate 2 (FIX-141): skip if an open PR already references this story id.
   if [ -n "$open_pr_titles" ] && printf '%s\n' "$open_pr_titles" | grep -qE "${id}([^0-9A-Za-z]|$)"; then
     return 1
   fi
@@ -13448,9 +13798,8 @@ _loop_story_is_eligible() {
 # US-AGENT-006: pick the next eligible 📋 Todo story from .roll/backlog.md
 # applying the same gates as the roll-loop SKILL Step 2:
 #   1. Status = 📋 Todo
-#   2. NOT manual-only:* tagged
-#   3. depends-on:* (if any) all ✅ Done
-#   4. Priority order: FIX > US > REFACTOR
+#   2. depends-on:* (if any) all ✅ Done
+#   3. Priority order: FIX > US > REFACTOR
 #
 # stdout: chosen story id (single line)
 # exit 0 when picked, 1 when nothing eligible.
@@ -13947,6 +14296,38 @@ _loop_is_doc_only_change() {
   return 0
 }
 
+# _loop_guard_roll_meta_boundary <worktree> <story_id>
+# US-LOOP-069: for roll-meta-target stories (deliverable under .roll/), verify
+# that no product-repo tracked files were modified in the worktree. Returns 0 if
+# safe (or not a roll-meta story), returns 1 if product files were touched and
+# writes ALERT. FIX-172: roll-meta-ness is path-based, not tag-based.
+_loop_guard_roll_meta_boundary() {
+  local wt="$1" story_id="$2"
+  [ -n "$story_id" ] || return 0
+  [ -d "$wt" ] || return 0
+
+  local _backlog="${ROLL_MAIN_PROJECT:-.}/.roll/backlog.md"
+  [ -f "$_backlog" ] || return 0
+
+  _loop_is_roll_meta_story "$story_id" "$_backlog" || return 0
+
+  local _changed _violations
+  _changed=$(cd "$wt" && git diff --name-only origin/main..HEAD 2>/dev/null || true)
+  [ -n "$_changed" ] || return 0
+
+  _violations=$(printf '%s\n' "$_changed" | grep -v '^\.roll/' || true)
+  if [ -n "$_violations" ]; then
+    local _alert
+    _alert="US-LOOP-069 guard blocked roll-meta story ${story_id}"
+    _alert="${_alert}"$'\n'"Touched product files (only .roll/ is allowed):"
+    _alert="${_alert}"$'\n'"${_violations}"
+    _worktree_alert "$_alert"
+    return 1
+  fi
+
+  return 0
+}
+
 # _loop_publish_doc_pr <branch> [title]
 #   Like _loop_publish_pr but merges immediately with --admin (no CI wait).
 #   For doc-only changes where CI is not meaningful.
@@ -15576,19 +15957,30 @@ _invalidate_update_cache() {
   rm -f "${ROLL_HOME}/.update-check"
 }
 
+# FIX-170: the cache file is `<ts> <latest> <writer-version>` — the 3rd field
+# binds it to the binary version that wrote it. FIX-166's explicit invalidation
+# only covers `roll update` run by a NEW binary; an upgrade executed by an old
+# binary (the 2.602.2→2.602.4 transition) or out-of-band (npm -g / brew / git)
+# left a stale cache that reverse-nagged for up to 24h. A writer-version
+# mismatch now means "stale" regardless of TTL: refetch, and stay silent until
+# the refetch lands. Legacy 2-field caches have no writer → auto-invalidated.
 _check_update_async() {
   local cache="${ROLL_HOME}/.update-check"
   local now; now=$(date +%s)
-  local last=0
-  [[ -f "$cache" ]] && last=$(awk '{print $1}' "$cache" 2>/dev/null || echo 0)
-  (( now - last < 86400 )) && return
+  local last=0 writer=""
+  if [[ -f "$cache" ]]; then
+    last=$(awk '{print $1}' "$cache" 2>/dev/null || echo 0)
+    writer=$(awk '{print $3}' "$cache" 2>/dev/null || true)
+  fi
+  [[ "$writer" == "$VERSION" ]] && (( now - ${last:-0} < 86400 )) && return
 
   {
     local latest
     latest=$(curl -sf --max-time 5 \
       "https://api.github.com/repos/seanyao/roll/releases/latest" \
       | grep '"tag_name"' | sed 's/.*"v\([^"]*\)".*/\1/' 2>/dev/null || true)
-    echo "$now ${latest:-}" > "$cache"
+    # `-` placeholder keeps the field positions stable when the fetch fails.
+    echo "$now ${latest:--} $VERSION" > "$cache"
   } &
   disown
 }
@@ -15596,8 +15988,13 @@ _check_update_async() {
 _notify_update() {
   local cache="${ROLL_HOME}/.update-check"
   [[ -f "$cache" ]] || return 0
-  local latest; latest=$(awk '{print $2}' "$cache" 2>/dev/null || true)
-  [[ -z "$latest" || "$latest" == "$VERSION" ]] && return
+  local latest writer
+  latest=$(awk '{print $2}' "$cache" 2>/dev/null || true)
+  writer=$(awk '{print $3}' "$cache" 2>/dev/null || true)
+  # FIX-170: cache written by a different binary version is stale — stay
+  # silent; _check_update_async has already kicked off the refetch.
+  [[ "$writer" != "$VERSION" ]] && return
+  [[ -z "$latest" || "$latest" == "-" || "$latest" == "$VERSION" ]] && return
   # FIX-163: the cached `latest` is GitHub's releases/latest — the newest
   # release by created_at, NOT by semver. Under the MAJOR.MMDD scheme a plain
   # `sort -V` mis-ranks versions across the year-based→MAJOR.MMDD transition