@seanyao/roll 2026.514.5 → 2026.516.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v2026.515.1
+
+- **New**: `roll brief` / `roll dream` 生成文档后自动提交推送 — 每次晨报和夜检不再需要手动 commit `[loop]`
+- **New**: 双语 FAQ 指南 — 10 个自治交付常见场景（loop 卡住、PR 冲突、agent 切换、权限问题等），每条含原因和原理，EN + ZH 对照 `[docs]`
+- **Fixed**: loop 孤儿状态自愈 — cycle 启动时检测 state.yaml 残留 running，若无活跃进程则自动重置为 idle，防止 loop 因中断永久卡死 `[loop]`
+- **New**: 可选的事件驱动 PR 评审模板 — `cp templates/workflows/pr-review-event.yml .github/workflows/`，PR 开即触发 AI 评审，不装也行（loop 每轮兜底） `[pr]`
+- **New**: loop PR inbox 从"分类但空转"升级到"分类+执行" — eligible PR 自动调 AI 评审，stale PR 自动 rebase，fork 和冲突写 ALERT；bot 已评审的 PR 自动让步 `[loop]`
+- **New**: `roll review-pr <number>` — agent-agnostic AI 代码评审，任意 agent（Claude/Kimi/DeepSeek 等）均可评审任意 git 平台的 PR；PR body 加 `[skip-ai-review]` 可跳过 `[pr]`
+- **Fixed**: `roll peer` 终态后 tmux session 不再残留 — AGREE/ESCALATE/UNKNOWN/round≥3 自动 kill，round<3 保留复用 `[peer]`
+- **New**: `loop/cycle-*` 远程僵尸分支兜底 GC — 每轮 cycle 结尾扫描已合入 main 的 `loop/cycle-*` 分支并删除，弥补 PR auto-merge 失败时的清理盲区 `[loop]`
+
 ## v2026.514.5
 
 - **Fixed**: 上版 `claude/*` 临时分支清理意外失效 — 现已恢复 `[loop]`

package/README.md

@@ -11,6 +11,7 @@
 
 **[中文版 README](README_CN.md)**
 
+[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2FRoll-blue)](https://seanyao.github.io/Roll/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
 [![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)
@@ -64,6 +65,7 @@ roll loop on        # optional: let the agent work unattended
 | Peer (cross-agent review) | [guide/en/peer.md](docs/guide/en/peer.md) | [guide/zh/peer.md](docs/guide/zh/peer.md) |
 | Configuration (env vars) | [guide/en/configuration.md](docs/guide/en/configuration.md) | [guide/zh/configuration.md](docs/guide/zh/configuration.md) |
 | Skill selection guide | [guide/en/skills.md](docs/guide/en/skills.md) | [guide/zh/skills.md](docs/guide/zh/skills.md) |
+| FAQ (troubleshooting) | [guide/en/faq.md](docs/guide/en/faq.md) | [guide/zh/faq.md](docs/guide/zh/faq.md) |
 | Domain model (DDD) | [domain/context-map.md](docs/domain/context-map.md) | — |
 | Engineering common sense | [practices/engineering-common-sense.md](docs/practices/engineering-common-sense.md) | — |
 

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="2026.514.5"
+VERSION="2026.516.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -614,6 +614,7 @@ cmd_setup() {
 
   echo ""
   _print_pr_pipeline_hint
+  _print_pr_event_hint
 }
 
 # ─── PR pipeline hint ────────────────────────────────────────────────────────
@@ -643,6 +644,24 @@ _print_pr_pipeline_hint() {
 HINT
 }
 
+_print_pr_event_hint() {
+  cat <<'HINT'
+
+  Optional — enable event-driven PR review (seconds-fast, GitHub only).
+  可选 —— 启用事件驱动 PR 评审（秒级响应，仅限 GitHub）。
+
+  Without this, Roll reviews PRs each loop cycle (~1h). With it,
+  contributors get AI feedback on PR open/update immediately.
+  不安装也行 — loop 每轮会兜底评审。安装后 PR 一开即触发 AI 评审。
+
+      cp templates/workflows/pr-review-event.yml .github/workflows/
+
+  Then set the API key secret for your configured agent in GitHub repo settings.
+  然后在 GitHub 仓库设置中添加你配置的 agent 对应的 API key secret。
+
+HINT
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: update
 # Thin wrapper: upgrade the npm-installed package, then re-sync via setup.
@@ -1112,60 +1131,6 @@ _ensure_features_dir() {
   _ROLL_MERGE_SUMMARY+=("created|docs/features/")
 }
 
-# ─── Helper: write starter .gitignore (no-op if exists) ──────────────────────
-_write_gitignore() {
-  [[ -f "$1" ]] && return
-  cat > "$1" << 'EOF'
-node_modules/
-dist/
-build/
-.env
-*.local
-.DS_Store
-*.log
-EOF
-}
-
-# ─── Helper: write starter .env.example (no-op if exists) ────────────────────
-_write_env_example() {
-  [[ -f "$1" ]] && return
-  cat > "$1" << 'EOF'
-# Environment Variables — copy to .env and fill in values
-
-# Application
-# NODE_ENV=development
-# PORT=3000
-
-# Database
-# DATABASE_URL=postgresql://user:pass@localhost:5432/db
-
-# Auth
-# JWT_SECRET=your-secret-key
-EOF
-}
-
-# ─── Helper: detect project type from existing AGENTS.md ─────────────────────
-detect_project_type() {
-  local agents_file="$1/AGENTS.md"
-  [[ -f "$agents_file" ]] || { echo "unknown"; return; }
-
-  local content
-  content="$(cat "$agents_file")"
-
-  if echo "$content" | grep -qi "Fullstack Web"; then
-    echo "fullstack"
-  elif echo "$content" | grep -qi "Backend Service"; then
-    echo "backend-service"
-  elif echo "$content" | grep -qi "Frontend Only"; then
-    echo "frontend-only"
-  elif echo "$content" | grep -qi "CLI Tool"; then
-    echo "cli"
-  else
-    # AGENTS.md exists but has no type marker — fall back to file-based scan
-    scan_project_type_from_files "$1"
-  fi
-}
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: status
 # Show current state of conventions
@@ -1459,7 +1424,7 @@ _peer_auto_attach() {
   [ "$(uname)" = "Darwin" ] || return 0
   [ -f "$_LOOP_MUTE_FILE" ] && return 0
   local terminal_pref
-  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  terminal_pref=$(config_get "loop_attach_terminal" "")
   if [[ -z "$terminal_pref" ]]; then
     case "${TERM_PROGRAM:-}" in
       ghostty)   terminal_pref="ghostty" ;;
@@ -1777,6 +1742,16 @@ cmd_peer() {
   echo ""
   info "Log: $log_file"
 
+  local _should_kill=true
+  case "$resolution" in
+    REFINE|OBJECT) [[ "$round" -lt 3 ]] && _should_kill=false ;;
+  esac
+  if [[ "$_should_kill" == "true" ]] && [[ -n "$peer_session" ]] \
+     && command -v tmux >/dev/null 2>&1 \
+     && tmux has-session -t "$peer_session" 2>/dev/null; then
+    tmux kill-session -t "$peer_session" 2>/dev/null || true
+  fi
+
   case "$resolution" in
     AGREE) exit 0 ;;
     REFINE|OBJECT) exit 2 ;;
@@ -1898,6 +1873,17 @@ _skill_content() {
   awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' "$1"
 }
 
+_parse_review_verdict() {
+  local output="$1"
+  local line
+  line=$(echo "$output" | grep -o '<!--VERDICT:[^>]*-->' | tail -1)
+  [ -n "$line" ] || return 0
+  local type reason
+  type=$(echo "$line" | sed -E 's/<!--VERDICT:([A-Z_]+)(:.*)?-->/\1/')
+  reason=$(echo "$line" | sed -E 's/<!--VERDICT:[A-Z_]+:?//; s/-->//' | sed 's/^ *//')
+  echo "${type}${reason:+:${reason}}"
+}
+
 _agent_run_skill() {
   local skill="$1"
   local agent; agent=$(_project_agent)
@@ -1915,6 +1901,102 @@ _agent_run_skill() {
   esac
 }
 
+cmd_review_pr() {
+  local pr_number="${1:-}"
+  [ -n "$pr_number" ] || { err "Usage: roll review-pr <number>"; return 1; }
+
+  local slug; slug=$(_gh_repo_slug) || { err "Not a GitHub repo — review-pr requires GitHub remote"; return 1; }
+
+  local pr_json
+  pr_json=$(gh -R "$slug" pr view "$pr_number" --json title,body,diff 2>&1) \
+    || { err "gh pr view failed: ${pr_json}"; return 1; }
+
+  local title body diff
+  title=$(echo "$pr_json" | jq -r '.title // ""')
+  body=$(echo "$pr_json" | jq -r '.body // ""')
+  diff=$(echo "$pr_json" | jq -r '.diff // ""')
+
+  if echo "$body" | grep -qF '[skip-ai-review]'; then
+    gh -R "$slug" pr review "$pr_number" --approve -b "Auto-approved: [skip-ai-review] detected" 2>/dev/null || true
+    info "PR #${pr_number}: [skip-ai-review] — auto-approved"
+    return 0
+  fi
+
+  local template="${ROLL_PKG_DIR}/skills/roll-review-pr/SKILL.md"
+  [ -f "$template" ] || { err "Skill template not found: ${template}"; return 1; }
+
+  local content; content=$(_skill_content "$template")
+
+  local tmp; tmp=$(mktemp)
+  # shellcheck disable=SC2064
+  trap "rm -f '$tmp'" EXIT
+
+  echo "$content" > "$tmp"
+  sed -i '' "s|{{PR_TITLE}}|${title}|g" "$tmp" 2>/dev/null \
+    || sed -i "s|{{PR_TITLE}}|${title}|g" "$tmp"
+
+  local body_escaped; body_escaped=$(printf '%s' "$body" | sed 's/[&/\]/\\&/g; s/$/\\/' | sed '$ s/\\$//')
+  sed -i '' "s|{{PR_BODY}}|${body_escaped}|g" "$tmp" 2>/dev/null \
+    || sed -i "s|{{PR_BODY}}|${body_escaped}|g" "$tmp"
+
+  local diff_truncated
+  diff_truncated=$(echo "$diff" | head -500)
+  local diff_file; diff_file=$(mktemp)
+  echo "$diff_truncated" > "$diff_file"
+  awk -v f="$diff_file" '{
+    if (index($0, "{{PR_DIFF}}")) {
+      while ((getline line < f) > 0) print line
+      close(f)
+    } else print
+  }' "$tmp" > "${tmp}.out" && mv "${tmp}.out" "$tmp"
+  rm -f "$diff_file"
+
+  local prompt; prompt=$(cat "$tmp")
+  rm -f "$tmp"
+  trap - EXIT
+
+  local agent; agent=$(_project_agent)
+  local output
+  info "Reviewing PR #${pr_number} with ${agent}..."
+  case "$agent" in
+    claude)   output=$(claude -p --output-format text "$prompt" 2>/dev/null) ;;
+    kimi)     output=$(kimi --quiet -p "$prompt" 2>/dev/null) ;;
+    deepseek) output=$(deepseek "$prompt" 2>/dev/null) ;;
+    pi)       output=$(pi -p "$prompt" 2>/dev/null) ;;
+    codex)    output=$(codex exec "$prompt" 2>/dev/null) ;;
+    opencode) output=$(opencode run "$prompt" 2>/dev/null) ;;
+    *)        err "Unknown agent '${agent}'"; return 1 ;;
+  esac
+
+  echo "$output"
+
+  local verdict; verdict=$(_parse_review_verdict "$output")
+  local vtype; vtype="${verdict%%:*}"
+  local vreason; vreason="${verdict#*:}"
+  [ "$vreason" = "$vtype" ] && vreason=""
+
+  case "$vtype" in
+    APPROVE)
+      gh -R "$slug" pr review "$pr_number" --approve -b "AI review: approved" 2>/dev/null || true
+      info "PR #${pr_number}: APPROVED"
+      ;;
+    REQUEST_CHANGES)
+      gh -R "$slug" pr review "$pr_number" --request-changes -b "${vreason:-AI review requested changes}" 2>/dev/null || true
+      info "PR #${pr_number}: REQUEST_CHANGES — ${vreason}"
+      ;;
+    UNCERTAIN)
+      warn "PR #${pr_number}: UNCERTAIN — ${vreason}"
+      local alert_file="${ROLL_LOOP_DIR:-${HOME}/.shared/roll/loop}/ALERT.md"
+      mkdir -p "$(dirname "$alert_file")"
+      printf '[%s] PR #%s: AI review UNCERTAIN — %s\n' \
+        "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pr_number" "$vreason" >> "$alert_file"
+      ;;
+    *)
+      warn "PR #${pr_number}: no verdict parsed from agent output"
+      ;;
+  esac
+}
+
 cmd_agent() {
   local subcmd="${1:-}"; shift || true
   case "$subcmd" in
@@ -1929,8 +2011,12 @@ cmd_agent() {
       fi
       ok "Agent set to ${name} for this project  当前项目 agent 已设为 ${name}"
       local project_path; project_path=$(pwd -P)
-      crontab -l 2>/dev/null | grep -q "roll-loop:${project_path}" && \
-        info "Takes effect on next scheduled run — or: roll loop now"
+      local slug; slug=$(_project_slug "$project_path")
+      local runner="${_SHARED_ROOT}/loop/run-${slug}.sh"
+      if [[ -f "$runner" ]]; then
+        _install_launchd_plists "$project_path" >/dev/null
+        ok "Loop runner scripts regenerated for new agent  已为新 agent 重新生成 loop 脚本"
+      fi
       ;;
     list)
       echo ""; echo "  Available agents  可用 agent:"; echo ""
@@ -1971,6 +2057,14 @@ _LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
 # hash of the full path, ensuring uniqueness across sibling dirs with same name.
 _project_slug() {
   local path="$1"
+  # FIX-034: when inside a git worktree, git-common-dir returns the main tree's
+  # absolute .git path; resolve to the main tree so worktree and main-tree runs
+  # produce the same slug.
+  local _common
+  _common=$(git -C "$path" rev-parse --git-common-dir 2>/dev/null)
+  if [[ -n "$_common" && "$_common" == *"/.git" ]]; then
+    path="${_common%/.git}"
+  fi
   local base; base=$(basename "$path")
   local hash
   if command -v md5 &>/dev/null; then
@@ -1985,17 +2079,10 @@ _project_slug() {
 _config_read_int() {
   local key="$1" default="$2"
   local val
-  val=$(grep "^${key}:" "$ROLL_CONFIG" 2>/dev/null | awk '{print $2}' | tr -d '"' | head -1)
+  val=$(config_get "$key" "")
   if [[ "$val" =~ ^[0-9]+$ ]]; then echo "$val"; else echo "$default"; fi
 }
 
-_config_read_string() {
-  local key="$1" default="$2"
-  local val
-  val=$(grep "^${key}:" "$ROLL_CONFIG" 2>/dev/null | awk '{print $2}' | tr -d '"' | head -1)
-  if [[ -n "$val" ]]; then echo "$val"; else echo "$default"; fi
-}
-
 # Derive a minute in [1,55] from project path hash + offset so different projects
 # and different services within a project don't fire at the same time.
 # Offsets used: loop=0, dream=2, brief=4 → always three distinct values (2<55).
@@ -2108,7 +2195,15 @@ if [ -f "\$INNER_LOCK" ]; then
   rm -f "\$INNER_LOCK"
 fi
 printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
-trap 'rm -f "\$INNER_LOCK"' EXIT
+# FIX-038: background heartbeat writer — outer script uses this as primary liveness signal
+# to detect stale execution without relying on PID reuse heuristics.
+HEARTBEAT_FILE="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+_heartbeat_writer() {
+  while true; do echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"; sleep 60; done
+}
+_heartbeat_writer &
+_HEARTBEAT_PID=\$!
+trap 'kill "\${_HEARTBEAT_PID}" 2>/dev/null; rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"' EXIT
 
 # US-AUTO-037: pull in worktree helpers (US-AUTO-036). Sourcing bin/roll is
 # safe — its main() only runs when invoked directly (BASH_SOURCE == \$0).
@@ -2166,37 +2261,50 @@ _claude_cleanup_stale_worktrees "${project_path}" || true
 # When \`gh\` is unavailable, fall back to the legacy ff-merge path.
 if [ "\$_USE_WORKTREE" = "1" ]; then
   if [ "\$_exit" -eq 0 ]; then
-    if ( cd "\$WT" && _loop_is_doc_only_change ); 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
-    _publish_status=\$?
-    if [ "\$_publish_status" -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)
+    if [ "\$_cycle_commits" -eq 0 ]; then
       _worktree_cleanup "\$WT" "\$BRANCH"
-      echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
-    elif [ "\$_publish_status" -eq 2 ]; then
-      if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+      echo "[loop] cycle \${CYCLE_ID}: idle (no new commits); worktree cleaned"
+    else
+      if ( cd "\$WT" && _loop_is_doc_only_change ); 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
+      _publish_status=\$?
+      if [ "\$_publish_status" -eq 0 ]; then
         _worktree_cleanup "\$WT" "\$BRANCH"
-        echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
+        echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
+      elif [ "\$_publish_status" -eq 2 ]; then
+        if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+          _worktree_cleanup "\$WT" "\$BRANCH"
+          echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
+        else
+          _worktree_alert "cycle \${CYCLE_ID}: gh unavailable AND merge_back failed; worktree preserved at \$WT"
+          echo "[loop] cycle \${CYCLE_ID}: gh+merge_back both failed; worktree preserved at \$WT"
+        fi
       else
-        _worktree_alert "cycle \${CYCLE_ID}: gh unavailable AND merge_back failed; worktree preserved at \$WT"
-        echo "[loop] cycle \${CYCLE_ID}: gh+merge_back both failed; worktree preserved at \$WT"
+        _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
-      _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
     _worktree_alert "cycle \${CYCLE_ID}: claude exited \$_exit; worktree preserved at \$WT (branch \$BRANCH)"
     echo "[loop] cycle \${CYCLE_ID}: claude failed (exit \$_exit); worktree preserved at \$WT"
   fi
 fi
+
+# US-AUTO-040: fallback GC — delete remote loop/cycle-* branches already merged to main.
+_loop_cleanup_stale_cycle_branches "${project_path}" || true
 INNER
   chmod +x "$inner_path"
 
   cat > "$script_path" << SCRIPT
 #!/bin/bash -l
+# caffeinate: prevent idle sleep from killing claude during cycles
+caffeinate -i -w \$\$ &
 # Active-window check — skipped when ROLL_LOOP_FORCE is set (manual 'roll loop now')
 if [ -z "\$ROLL_LOOP_FORCE" ]; then
   h=\$(printf '%d' "\$(date +%H)")
@@ -2205,6 +2313,50 @@ fi
 # Pause check — 'roll loop pause' creates this marker to suspend scheduling
 PAUSE="\$HOME/.shared/roll/loop/PAUSE-${slug}"
 if [ -z "\$ROLL_LOOP_FORCE" ] && [ -f "\$PAUSE" ]; then exit 0; fi
+# FIX-037: orphan state detection & self-heal — if state.yaml says running
+# but no LOCK process or tmux session exists, the previous cycle was killed
+# (e.g. SIGKILL / sleep / terminal close). Heal state to idle so the next
+# cycle can proceed normally; write ALERT for transparency.
+# FIX-038: heartbeat is the primary liveness signal (avoids PID reuse race);
+# LOCK pid check is secondary fallback for backward compatibility.
+HEARTBEAT_TIMEOUT="\${ROLL_HEARTBEAT_TIMEOUT:-1800}"
+STATE_FILE="${HOME}/.shared/roll/loop/state.yaml"
+if [ -f "\$STATE_FILE" ]; then
+  _state=\$(grep '^status:' "\$STATE_FILE" | awk '{print \$2}' 2>/dev/null || echo "")
+  if [ "\$_state" = "running" ]; then
+    _still_active=false
+    # FIX-038: heartbeat is primary signal
+    _heartbeat_file="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+    if [ -f "\$_heartbeat_file" ]; then
+      _hb_ts=\$(cat "\$_heartbeat_file" 2>/dev/null || echo "0")
+      _now=\$(date -u +%s)
+      _hb_age=\$(( _now - _hb_ts ))
+      if [ "\$_hb_age" -lt "\$HEARTBEAT_TIMEOUT" ]; then
+        _still_active=true
+      fi
+    fi
+    # Fallback: LOCK pid check (for cycles without heartbeat, e.g. pre-FIX-038)
+    if [ "\$_still_active" = false ]; then
+      _lock_file="\$(dirname "\$0")/.LOCK-\$(basename "\$0" .sh | sed 's/^run-//')"
+      if [ -f "\$_lock_file" ]; then
+        _lock_pid=\$(head -1 "\$_lock_file" 2>/dev/null || echo "")
+        [ -n "\$_lock_pid" ] && kill -0 "\$_lock_pid" 2>/dev/null && _still_active=true
+      fi
+    fi
+    # Final: tmux session check
+    if [ "\$_still_active" = false ]; then
+      command -v tmux >/dev/null 2>&1 && tmux has-session -t "roll-loop-\$(basename "\$0" .sh | sed 's/^run-//')" 2>/dev/null && _still_active=true
+    fi
+    if [ "\$_still_active" = false ]; then
+      echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-037: orphan state detected (status=running, heartbeat stale or missing) — healing to idle" >> "\$LOG"
+      echo "status: idle" > "\${STATE_FILE}.tmp" && mv "\${STATE_FILE}.tmp" "\$STATE_FILE"
+      rm -f "\$_lock_file" 2>/dev/null || true
+      _alert_file="\$(dirname "\$0")/ALERT.md"
+      echo "\$(date '+%Y-%m-%dT%H:%M:%S%z') | FIX-037 auto-heal | Orphan state detected and cleared (status=running → idle)" >> "\$_alert_file" 2>/dev/null || true
+      echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-037: healed to idle, ALERT written" >> "\$LOG"
+    fi
+  fi
+fi
 LOCK="\$(dirname "\$0")/.LOCK-\$(basename "\$0" .sh | sed 's/^run-//')"
 SESSION="roll-loop-\$(basename "\$0" .sh | sed 's/^run-//')"
 INNER_SCRIPT="${inner_path}"
@@ -2227,7 +2379,9 @@ fi
 echo "\$\$" > "\$LOCK"
 trap 'rm -f "\$LOCK"' EXIT
 if command -v tmux >/dev/null 2>&1; then
-  tmux kill-session -t "\$SESSION" 2>/dev/null || true
+  tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^roll-loop-" | while read _s; do
+    tmux kill-session -t "\$_s" 2>/dev/null || true
+  done
   tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
   tmux pipe-pane -t "\$SESSION" "cat >> \"\$LOG\""
   # Auto-attach popup: when not muted, spawn a Terminal window attached to the
@@ -2304,7 +2458,7 @@ _install_launchd_plists() {
 
   # Terminal preference: config wins, then TERM_PROGRAM env, then "Terminal"
   local terminal_pref
-  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  terminal_pref=$(config_get "loop_attach_terminal" "")
   if [[ -z "$terminal_pref" ]]; then
     case "${TERM_PROGRAM:-}" in
       ghostty)    terminal_pref="ghostty" ;;
@@ -2534,7 +2688,7 @@ _loop_test() {
 
   # Detect terminal pref same way _install_launchd_plists does
   local terminal_pref
-  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  terminal_pref=$(config_get "loop_attach_terminal" "")
   if [[ -z "$terminal_pref" ]]; then
     case "${TERM_PROGRAM:-}" in
       ghostty)    terminal_pref="ghostty" ;;
@@ -3319,6 +3473,55 @@ _loop_pr_state_write() {
   ' "$state" > "$tmp" && mv "$tmp" "$state"
 }
 
+# _loop_pr_review_external <pr_number>
+#   Calls cmd_review_pr (US-PR-001) to run AI review on an eligible external PR.
+#   Lenient: errors are logged but do not fail the loop.
+_loop_pr_review_external() {
+  local pr="$1"
+  [ -n "$pr" ] || return 0
+  cmd_review_pr "$pr" 2>&1 || {
+    warn "review-pr failed for PR #${pr} (non-fatal)"
+    return 0
+  }
+}
+
+# _loop_pr_rebase_stale <pr_number> <head_ref>
+#   Attempts to rebase a stale PR onto origin/main and push.
+#   Fork PRs are skipped (no write access). Conflicts write ALERT.
+_loop_pr_rebase_stale() {
+  local pr="$1" head_ref="$2"
+  [ -n "$pr" ] && [ -n "$head_ref" ] || return 0
+
+  local slug; slug=$(_gh_repo_slug 2>/dev/null) || return 0
+
+  local pr_json
+  pr_json=$(gh -R "$slug" pr view "$pr" --json headRepository,headRepositoryOwner,isCrossRepository 2>/dev/null) || return 0
+  local is_fork
+  is_fork=$(echo "$pr_json" | jq -r '.isCrossRepository // false' 2>/dev/null)
+  if [ "$is_fork" = "true" ]; then
+    local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+    mkdir -p "$(dirname "$alert")" 2>/dev/null || true
+    printf '[%s] PR #%s: fork PR — cannot rebase (no write access)\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pr" >> "$alert"
+    return 0
+  fi
+
+  git fetch origin "$head_ref" 2>/dev/null || return 0
+  if git checkout "$head_ref" 2>/dev/null \
+     && git rebase origin/main 2>/dev/null \
+     && git push origin "$head_ref" 2>/dev/null; then
+    info "PR #${pr}: rebased ${head_ref} onto origin/main"
+  else
+    git rebase --abort 2>/dev/null || true
+    git checkout - 2>/dev/null || true
+    local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+    mkdir -p "$(dirname "$alert")" 2>/dev/null || true
+    printf '[%s] PR #%s: rebase conflict on %s — please rebase manually\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pr" "$head_ref" >> "$alert"
+  fi
+  return 0
+}
+
 # _loop_pr_inbox
 #   Walks open PRs and routes each by classification.
 #   Lenient on gh unavailability — returns 0 so the loop continues to BACKLOG.
@@ -3348,10 +3551,13 @@ _loop_pr_inbox() {
       --json reviews,mergeStateStatus,statusCheckRollup \
       2>/dev/null) || { i=$((i + 1)); continue; }
 
-    local human_review ci_state mergeable
+    local human_review ci_state mergeable bot_review
     human_review=$(echo "$view_json" | jq -r '
       [.reviews[]? | select(.authorAssociation != "BOT" and .authorAssociation != "APP")]
       | last // {} | .state // ""' 2>/dev/null)
+    bot_review=$(echo "$view_json" | jq -r '
+      [.reviews[]? | select(.authorAssociation == "BOT" or .authorAssociation == "APP")]
+      | last // {} | .state // ""' 2>/dev/null)
     mergeable=$(echo "$view_json" | jq -r '.mergeStateStatus // ""' 2>/dev/null)
     ci_state=$(echo "$view_json" | jq -r '
       if (.statusCheckRollup | length) == 0 then ""
@@ -3359,6 +3565,17 @@ _loop_pr_inbox() {
       elif all(.statusCheckRollup[]?; .conclusion == "SUCCESS" or .conclusion == "SKIPPED") then "success"
       else "pending" end' 2>/dev/null)
 
+    # Bot review gate: if a GHA workflow already handled this PR, defer to it.
+    if [ "$bot_review" = "APPROVED" ]; then
+      i=$((i + 1)); continue
+    elif [ "$bot_review" = "CHANGES_REQUESTED" ]; then
+      local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+      mkdir -p "$(dirname "$alert")" 2>/dev/null || true
+      printf '[%s] PR #%s: bot review CHANGES_REQUESTED — loop PR rejected by GHA reviewer\n' \
+        "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$num" >> "$alert"
+      i=$((i + 1)); continue
+    fi
+
     local verdict
     verdict=$(_loop_pr_classify "$head_ref" "$human_review" "$ci_state" "$mergeable")
 
@@ -3368,15 +3585,10 @@ _loop_pr_inbox() {
         ;;
       stale)
         _loop_pr_rebase_circuit "$num" || true
-        # Actual rebase work delegated to _loop_pr_rebase_stale when present
-        # (kept out of this cycle to avoid touching git remote in tests).
-        command -v _loop_pr_rebase_stale >/dev/null 2>&1 \
-          && _loop_pr_rebase_stale "$num" "$head_ref" || true
+        _loop_pr_rebase_stale "$num" "$head_ref" || true
         ;;
       eligible)
-        # Hand off to review (US-AUTO-035 supplies the actual decision).
-        command -v _loop_pr_review_external >/dev/null 2>&1 \
-          && _loop_pr_review_external "$num" || true
+        _loop_pr_review_external "$num" || true
         ;;
     esac
 
@@ -3715,6 +3927,28 @@ _claude_cleanup_stale_worktrees() {
   return 0
 }
 
+_loop_cleanup_stale_cycle_branches() {
+  local project_path="${1:-.}"
+  local url; url=$(git -C "$project_path" remote get-url origin 2>/dev/null) || return 0
+  [[ "$url" == *github.com* ]] || return 0
+
+  local branches
+  branches=$(git -C "$project_path" ls-remote --heads origin 'refs/heads/loop/cycle-*' 2>/dev/null \
+    | awk '{print $2}' | sed 's|^refs/heads/||')
+  [ -z "$branches" ] && return 0
+
+  while IFS= read -r branch; do
+    [ -z "$branch" ] && continue
+    if ! git -C "$project_path" merge-base --is-ancestor "$branch" origin/main 2>/dev/null; then
+      continue
+    fi
+    if git -C "$project_path" push origin --delete "$branch" 2>/dev/null; then
+      echo "[loop] deleted stale cycle branch: $branch"
+    fi
+  done <<< "$branches"
+  return 0
+}
+
 # US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
 #
 # _loop_publish_pr <branch> [title]
@@ -4719,6 +4953,7 @@ usage() {
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
   echo "  ci [--wait]            [CI] Show or wait for current commit's CI status       查看/等待 CI 状态"
+  echo "  review-pr <number>     [PR Review] AI-powered code review for a PR           AI 代码评审"
   echo ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
@@ -4750,6 +4985,7 @@ main() {
     agent)         cmd_agent "$@" ;;
     release)       cmd_release "$@" ;;
     ci)            cmd_ci "$@" ;;
+    review-pr)     cmd_review_pr "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;
     "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.514.5",
+  "version": "2026.516.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"
@@ -27,7 +27,6 @@
     "conventions/",
     "lib/",
     "skills/",
-    "tools/",
     "template/",
     "README.md",
     "CHANGELOG.md"

package/skills/roll-.dream/SKILL.md

@@ -275,6 +275,7 @@ git add BACKLOG.md docs/dream/YYYY-MM-DD.md
 git commit -m "chore: dream scan YYYY-MM-DD — {N} REFACTOR entries"
 # 无发现时：
 git commit -m "chore: dream scan YYYY-MM-DD — no findings"
+git push origin main
 ```
 
 - BACKLOG.md 和 dream 日志必须在**同一个 commit** 里入库，避免出现"REFACTOR 已加但日志找不到"或反过来的撕裂状态