@seanyao/roll 2026.524.2 → 2026.525.1

package/CHANGELOG.md

@@ -1,33 +1,43 @@
 # Changelog
 
-## v2026.524.2
+## v2026.525.1
 
 ### Added
 
-- **用 pi / deepseek / kimi 跑的 loop 也能在终端里实时看到进度** — 不再黑屏 `[loop]`
-- **`roll slides new` 可以用项目自己的模板** — 不只用内置的了 `[deck]`
-- **`roll slides list` 一眼看出 slide 状态** — 哪些能看、哪些生成失败、失败原因也能查 `[deck]`
+- loop 触发频率可以按项目单独设 — 每个项目能自定义间隔，不再全局一刀切 `[loop]`
 
 ### Fixed
 
-- **loop 不再一次吞太多故事** — 每次只做一个，时间可预期 `[loop]`
-- **dashboard 不再对非 Claude 模型显示空白** — 能看出每轮谁跑的 `[loop]`
+- `roll` 主页不再把已启用的 loop 误报成"缺失" `[loop]`
+- loop 弹窗关了也能翻回之前的输出 — 不再一关就全丢 `[loop]`
 
-## v2026.524.1
+## v2026.524.2
 
 ### Added
 
 - **`roll slides new` 不再像卡住** — 分阶段显示进度、当前步骤和耗时 `[deck]`
+- **`roll slides new` 可以用项目自己的模板** — 不只用内置的了 `[deck]`
+- **`roll slides list` 一眼看出 slide 状态** — 哪些能看、哪些生成失败、失败原因也能查 `[deck]`
+- **`roll slides templates` 列出可用模板** — 内置和项目自定义的一眼可见 `[deck]`
+- **`roll slides delete` 删除幻灯片** — 不再需要手动 rm `[deck]`
+- **用 pi / deepseek / kimi 跑的 loop 也能在终端里实时看到进度** — 不再黑屏 `[loop]`
 - **网站语言随浏览器自动切换** — 中文用户看到中文 `[i18n]`
 
 ### Fixed
 
-- **成本不再虚高** — 支持多模型真实价格 `[dashboard]`
+- **loop 不再一次吞太多故事** — 每次只做一个，时间可预期 `[loop]`
 - **loop 挂了会换备用** — 不再直接放弃 `[loop]`
 - **loop 本地工作区不再堆积** — 合并后自动清理 `[loop]`
 - **标进行中的故事不再永久卡住** — 超时恢复待办 `[loop]`
+- **成本不再虚高** — 支持多模型真实价格 `[dashboard]`
+- **dashboard 不再对非 Claude 模型显示空白** — 能看出每轮谁跑的 `[loop]`
 - **主页 agent 标签不再骗人** — 显示真名 `[dashboard]`
 
+### Docs
+
+- **新增 `guide/{en,zh}/pricing.md`** — `roll prices` 命令用法、价格快照机制、历史成本固化语义；README 索引同步 `[pricing]`
+- **FAQ 新增 A11** — 价格更新后历史 cycle 成本数字不会变 `[pricing]`
+
 ## v2026.523.2
 
 ### Added

package/README.md

@@ -69,6 +69,7 @@ roll loop on        # let AI work through the backlog (optional)
 | Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
 | Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
 | Slides (deck generator) | [guide/en/slides.md](guide/en/slides.md) | [guide/zh/slides.md](guide/zh/slides.md) |
+| Pricing (cost visibility) | [guide/en/pricing.md](guide/en/pricing.md) | [guide/zh/pricing.md](guide/zh/pricing.md) |
 | FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |
 | Adoption patterns | [guide/en/patterns/](guide/en/patterns/) | [guide/zh/patterns/](guide/zh/patterns/) |
 

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.524.2"
+VERSION="2026.525.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -2674,7 +2674,13 @@ _peer_auto_attach() {
   [ "$(uname)" = "Darwin" ] || return 0
   [ -f "$_LOOP_MUTE_FILE" ] && return 0
   local attach_cmd="${_SHARED_ROOT}/loop/attach-${session}.command"
-  printf '#!/bin/bash\nexec tmux attach -t %s\n' "$session" > "$attach_cmd" 2>/dev/null || return 0
+  # Drop `exec` so the wrapping shell survives `tmux attach` exiting; pause
+  # on `read` afterwards so the user can scroll back through the session's
+  # output before closing the Terminal window. Without this the window
+  # closes the instant the tmux session ends and the entire scrollback
+  # disappears with it.
+  printf '#!/bin/bash\ntmux attach -t %s\necho\necho "================================================================"\necho "  session ended. press enter to close this window."\necho "================================================================"\nread _\n' \
+    "$session" > "$attach_cmd" 2>/dev/null || return 0
   chmod +x "$attach_cmd" 2>/dev/null || return 0
   open -g -a Terminal "$attach_cmd" >/dev/null 2>&1 || true
 }
@@ -3084,18 +3090,6 @@ _project_agent() {
   fi
 }
 
-_fallback_agent() {
-  local pref new_pref
-  new_pref=$(_project_agent_pref_file)
-  if [[ -f "$new_pref" ]] && grep -q "^fallback_agent:" "$new_pref" 2>/dev/null; then
-    grep "^fallback_agent:" "$new_pref" | awk '{print $2}' | tr -d '"' | head -1
-  elif [[ -f ".roll.yaml" ]] && grep -q "^fallback_agent:" .roll.yaml 2>/dev/null; then
-    grep "^fallback_agent:" .roll.yaml | awk '{print $2}' | tr -d '"' | head -1
-  elif [[ -f "$ROLL_CONFIG" ]] && grep -q "fallback_agent:" "$ROLL_CONFIG" 2>/dev/null; then
-    grep "fallback_agent:" "$ROLL_CONFIG" | awk '{print $2}' | tr -d '"' | head -1
-  fi
-}
-
 _skill_content() {
   # Strip YAML frontmatter (---...---) — it's roll-internal metadata, not agent instructions
   awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' "$1"
@@ -3349,12 +3343,19 @@ USAGE  用法
                           在浏览器中打开已渲染的幻灯片
   roll slides logs <slug> Show the last build failure log for a deck
                           显示幻灯片上次构建失败日志
+  roll slides templates   List available slide templates (built-in + project)
+                          列出可用模板（内置 + 项目自定义）
+  roll slides delete <slug> [--force]
+                          Delete a deck (dir + HTML) with confirmation prompt
+                          删除幻灯片（含目录与 HTML），需确认
 
 OPTIONS  选项
   --no-open               Skip auto-opening the rendered HTML in a browser
                           渲染后不自动打开浏览器
   --no-build              Skip auto-build after agent completes (deck.md only)
                           仅生成 deck.md，不自动渲染
+  --force                 Skip confirmation prompt (delete subcommand)
+                          跳过确认提示（delete 子命令）
   --help, -h              Show this help
                           显示本帮助
 EOF
@@ -3724,6 +3725,114 @@ cmd_slides_logs() {
   return 0
 }
 
+# ─── US-DECK-014 ─────────────────────────────────────────────────────────────
+cmd_slides_delete() {
+  local slug="" force=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=1; shift ;;
+      --help|-h) _slides_help; return 0 ;;
+      --*) err "Unknown option: $1  未知选项: $1"; return 1 ;;
+      *)
+        if [[ -z "$slug" ]]; then
+          slug="$1"; shift
+        else
+          err "Unexpected argument: $1  多余参数: $1"; return 1
+        fi
+        ;;
+    esac
+  done
+
+  if [[ -z "$slug" ]]; then
+    err "Usage: roll slides delete <slug> [--force]"
+    echo "用法: roll slides delete <slug> [--force]" >&2
+    return 1
+  fi
+
+  local deck_dir=".roll/slides/${slug}"
+  local html=".roll/slides/${slug}.html"
+
+  if [[ ! -d "$deck_dir" ]] || [[ ! -f "${deck_dir}/deck.md" ]]; then
+    err "Deck not found: ${slug}  未找到幻灯片：${slug}"
+    return 1
+  fi
+
+  # Non-TTY must use --force (skip interactive confirmation)
+  if [[ $force -eq 0 ]]; then
+    if [[ ! -t 0 ]]; then
+      err "Non-interactive terminal: must use --force to delete  非交互终端：需使用 --force 参数"
+      return 1
+    fi
+    printf 'Delete deck "%s"? (y/N)  删除幻灯片 "%s"？(y/N) ' "$slug" "$slug" >&2
+    read -r answer
+    case "$answer" in
+      [yY]|[yY][eE][sS]) : ;;
+      *) info "Cancelled  已取消"; return 0 ;;
+    esac
+  fi
+
+  # Remove deck directory and HTML file
+  rm -rf "$deck_dir" 2>/dev/null || true
+  rm -f "$html" 2>/dev/null || true
+  ok "Deleted ${slug}  已删除 ${slug}"
+  return 0
+}
+
+# ─── US-DECK-014 ─────────────────────────────────────────────────────────────
+cmd_slides_templates() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --help|-h) _slides_help; return 0 ;;
+      --*) err "Unknown option: $1  未知选项: $1"; return 1 ;;
+      *) err "Unexpected argument: $1  多余参数: $1"; return 1 ;;
+    esac
+  done
+
+  local seen=""
+  local found=0
+  local name base path source
+
+  printf '%-24s  %-12s  %s\n' "name" "source" "path"
+  printf '%-24s  %-12s  %s\n' "----" "------" "----"
+
+  # Built-in templates (shipped with roll package)
+  local builtin_dir="${ROLL_PKG_DIR}/lib/slides/templates"
+  if [[ -d "$builtin_dir" ]]; then
+    shopt -s nullglob
+    for tpl in "$builtin_dir"/*.html; do
+      name="${tpl##*/}"
+      name="${name%.html}"
+      printf '%-24s  %-12s  %s\n' "$name" "builtin" "$tpl"
+      found=1
+    done
+    shopt -u nullglob
+  fi
+
+  # Project-level overrides (.roll/slides/templates/)
+  local proj_dir=".roll/slides/templates"
+  if [[ -d "$proj_dir" ]]; then
+    shopt -s nullglob
+    for tpl in "$proj_dir"/*.html; do
+      name="${tpl##*/}"
+      name="${name%.html}"
+      # Mark as project override if same name exists in builtin
+      if [[ -f "${builtin_dir}/${name}.html" ]]; then
+        source="project (override)"
+      else
+        source="project"
+      fi
+      printf '%-24s  %-12s  %s\n' "$name" "$source" "$tpl"
+      found=1
+    done
+    shopt -u nullglob
+  fi
+
+  if [[ $found -eq 0 ]]; then
+    info "No templates found  无可用模板"
+  fi
+  return 0
+}
+
 # ─── US-DECK-004 ─────────────────────────────────────────────────────────────
 # Turn a topic string into a kebab-case slug.
 # Lower-cases, replaces any run of non-alphanumerics with a single dash,
@@ -4083,6 +4192,12 @@ cmd_slides() {
     logs)
       cmd_slides_logs "$@"
       ;;
+    templates)
+      cmd_slides_templates "$@"
+      ;;
+    delete)
+      cmd_slides_delete "$@"
+      ;;
     --help|-h|help)
       _slides_help
       return 0
@@ -4290,6 +4405,47 @@ _project_slug() {
   if [[ -n "$_common" && "$_common" == *"/.git" ]]; then
     path="${_common%/.git}"
   fi
+
+  # US-OBS-010: derive slug from git remote URL for stable cross-machine
+  # identity.  Normalize: strip .git, git@HOST:PATH → https://HOST/PATH,
+  # lowercase.  Fallback chain: origin → first available remote → path-based.
+  local remote_url
+  remote_url=$(git -C "$path" remote get-url origin 2>/dev/null)
+  if [[ -z "$remote_url" ]]; then
+    local first_remote
+    first_remote=$(git -C "$path" remote 2>/dev/null | head -1)
+    if [[ -n "$first_remote" ]]; then
+      remote_url=$(git -C "$path" remote get-url "$first_remote" 2>/dev/null)
+    fi
+  fi
+
+  if [[ -n "$remote_url" ]]; then
+    remote_url="${remote_url%.git}"
+    if [[ "$remote_url" =~ ^git@([^:]+):(.+)$ ]]; then
+      remote_url="https://${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+    fi
+    remote_url=$(printf '%s' "$remote_url" | tr '[:upper:]' '[:lower:]')
+    local base; base=$(basename "$remote_url")
+    local hash
+    if command -v md5 &>/dev/null; then
+      hash=$(printf '%s' "$remote_url" | md5 | cut -c1-6)
+    else
+      hash=$(printf '%s' "$remote_url" | md5sum | cut -c1-6)
+    fi
+    base=$(printf '%s' "$base" | tr -cs '[:alnum:]' '-' | sed 's/-*$//')
+    printf '%s' "${base}-${hash}"
+    return 0
+  fi
+
+  # No remote available — fall back to path-based slug.
+  # If roll_records_remote is configured, warn the user: the slug won't be
+  # stable across machines, so cross-machine sync cannot work.
+  local records_remote
+  records_remote=$(config_get "roll_records_remote" "")
+  if [[ -n "$records_remote" ]]; then
+    printf 'roll: WARNING — roll_records_remote is configured but no git remote URL found; slug will fall back to path-based (cross-machine merge will not work)\n' >&2
+  fi
+
   local base; base=$(basename "$path")
   local hash
   if command -v md5 &>/dev/null; then
@@ -4389,6 +4545,144 @@ PYEOF
   rm -f "${loop_dir}/run-${old_slug}.sh" "${loop_dir}/run-${old_slug}-inner.sh"
 }
 
+# US-OBS-010: path-based slug (without remote URL) — used to detect the
+# pre-remote slug so migration can merge old records into the new identity.
+_project_slug_path_based() {
+  local path="${1:-$(pwd -P 2>/dev/null || pwd)}"
+  if [[ "$(uname -s 2>/dev/null)" == "Darwin" ]]; then
+    local _canon
+    _canon=$(realpath "$path" 2>/dev/null) && path="$_canon"
+  fi
+  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
+    hash=$(printf '%s' "$path" | md5 | cut -c1-6)
+  else
+    hash=$(printf '%s' "$path" | md5sum | cut -c1-6)
+  fi
+  base=$(printf '%s' "$base" | tr -cs '[:alnum:]' '-' | sed 's/-*$//')
+  printf '%s' "${base}-${hash}"
+}
+
+# US-OBS-010: migrate loop records from old path-based slug to new
+# remote-based slug.  Dedup by run_id; atomic cp→tmp→mv; keep old as .bak.
+#
+# Usage: _slug_migrate_to_remote <project_path> [<loop_dir>]
+_slug_migrate_to_remote() {
+  local project_path="$1"
+  local loop_dir="${2:-${_SHARED_ROOT}/loop}"
+
+  local new_slug; new_slug=$(_project_slug "$project_path")
+  local old_slug; old_slug=$(_project_slug_path_based "$project_path")
+
+  # Dedup guard: no migration needed
+  [[ "$old_slug" == "$new_slug" ]] && return 0
+  [[ -f "${loop_dir}/events-${old_slug}.ndjson" ]] || return 0
+
+  printf 'roll: migrating loop records %s → %s (cross-machine slug)\n' "$old_slug" "$new_slug" >&2
+
+  # Migrate events with run_id dedup + atomic write
+  local events_file="${loop_dir}/events-${new_slug}.ndjson"
+  local tmp_events; tmp_events=$(mktemp)
+
+  # Collect existing run_ids from new slug file
+  local existing_ids=""
+  if [[ -f "$events_file" ]]; then
+    existing_ids=$(python3 -c "
+import json, sys
+try:
+    with open('$events_file') as f:
+        for line in f:
+            d = json.loads(line.strip())
+            if 'label' in d:
+                print(d['label'])
+except: pass
+" 2>/dev/null)
+  fi
+
+  # Append old events to new, dedup by label (run_id / cycle_id)
+  python3 - "$old_slug" "$events_file" "$tmp_events" << 'PYEOF'
+import json, sys
+old_slug, new_file, tmp_file = sys.argv[1], sys.argv[2], sys.argv[3]
+
+# Read existing new-file ids
+seen = set()
+try:
+    with open(new_file) as f:
+        for line in f:
+            d = json.loads(line.strip())
+            if 'label' in d:
+                seen.add(d['label'])
+except FileNotFoundError:
+    pass
+
+# Append old events, deduped
+old_file = new_file.replace(new_file.split('-')[-1].split('.')[0], old_slug)
+with open(tmp_file, 'w') as out:
+    # Copy existing new file
+    try:
+        with open(new_file) as f:
+            out.write(f.read())
+    except FileNotFoundError:
+        pass
+    # Append old events not yet seen
+    old_path = '/'.join(new_file.rsplit('/', 1)[:-1] + [f'events-{old_slug}.ndjson'])
+    try:
+        with open(old_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                d = json.loads(line)
+                lid = d.get('label', '')
+                if lid not in seen:
+                    seen.add(lid)
+                    out.write(json.dumps(d) + '\n')
+    except FileNotFoundError:
+        pass
+PYEOF
+
+  # Atomic replace
+  mv "$tmp_events" "$events_file"
+
+  # Keep old events as .bak (do not delete)
+  cp "${loop_dir}/events-${old_slug}.ndjson" "${loop_dir}/events-${old_slug}.ndjson.bak"
+  rm "${loop_dir}/events-${old_slug}.ndjson"
+
+  # Migrate runs.jsonl: rewrite project field + dedup by run_id
+  local runs_file="${loop_dir}/runs.jsonl"
+  if [[ -f "$runs_file" ]]; then
+    local tmp; tmp=$(mktemp)
+    python3 - "$old_slug" "$new_slug" "$runs_file" > "$tmp" << 'PYEOF'
+import json, sys
+old, new, path = sys.argv[1], sys.argv[2], sys.argv[3]
+seen = set()
+with open(path) as f:
+    for line in f:
+        line = line.rstrip('\n')
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+            if 'project' in d and old in str(d['project']):
+                d['project'] = str(d['project']).replace(old, new)
+            rid = d.get('run_id', '')
+            if rid in seen:
+                continue
+            seen.add(rid)
+            print(json.dumps(d))
+        except Exception:
+            print(line)
+PYEOF
+    mv "$tmp" "$runs_file"
+  fi
+}
+
 _LOOP_TAG="# roll-loop"
 # FIX-065: when sourced in a test context with no explicit override, route
 # shared state into a per-process /tmp path instead of falling back to
@@ -4502,6 +4796,71 @@ _loop_derive_minute() {
   echo $(( (hash_dec + offset) % 55 + 1 ))
 }
 
+# US-LOOP-011: validate a (period, offset) pair against the allowed schedule spec.
+# Allowed periods are the divisors of 60: 60/30/20/15/12/10/6/5.
+# Offset must be within [0, period).
+_loop_schedule_valid() {
+  local period="$1" offset="$2"
+  case "$period" in
+    60|30|20|15|12|10|6|5) ;;
+    *) return 1 ;;
+  esac
+  [[ "$offset" =~ ^[0-9]+$ ]] || return 1
+  if (( offset >= period )); then return 1; fi
+  return 0
+}
+
+# US-LOOP-011: compute the loop schedule spec for a project.
+# Resolution order:
+#   1. .roll/local.yaml  loop_schedule.{period_minutes,offset_minute}
+#   2. ~/.roll/config.yaml  loop_minute  → period=60, offset=loop_minute
+#   3. default              period=60, offset=hash(project_path)%60
+# Output: "<period> <offset>" on stdout. Exit 0 on success.
+# Invalid project config → fallback to global/default + write ALERT.
+_loop_schedule_spec() {
+  local project_path="$1"
+
+  # 1. Try project-level .roll/local.yaml
+  local local_file="${project_path}/.roll/local.yaml"
+  if [[ -f "$local_file" ]]; then
+    local local_period local_offset
+    # Extract values from under loop_schedule: key (using awk for reliable block parsing)
+    local_period=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+period_minutes:/{print $2; exit}' "$local_file")
+    local_offset=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+offset_minute:/{print $2; exit}' "$local_file")
+    if [[ -n "$local_period" && -n "$local_offset" ]]; then
+      if _loop_schedule_valid "$local_period" "$local_offset"; then
+        echo "$local_period $local_offset"
+        return 0
+      fi
+      # Invalid: alert, then fall through to global/default
+      local slug; slug=$(_project_slug "$project_path")
+      local alert_file="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/ALERT-${slug}.md"
+      mkdir -p "$(dirname "$alert_file")" 2>/dev/null || true
+      {
+        printf '## ⚠️ US-LOOP-011: Invalid loop_schedule\n\n'
+        printf '**Time**: %s\n' "$(date '+%Y-%m-%d %H:%M:%S')"
+        printf '**Source**: %s\n\n' "${project_path}/.roll/local.yaml"
+        printf '**Values**: period_minutes=%s, offset_minute=%s\n\n' "$local_period" "$local_offset"
+        printf '**Action**: period must be one of 60/30/20/15/12/10/6/5; offset must be 0–(period-1). Falling back to default (period=60).\n\n'
+        printf '%s\n' '---'
+      } >> "$alert_file"
+    fi
+  fi
+
+  # 2. Try global ~/.roll/config.yaml loop_minute (backward compat)
+  local global_minute
+  global_minute=$(_config_read_int "loop_minute" "")
+  if [[ -n "$global_minute" && "$global_minute" =~ ^[0-9]+$ ]]; then
+    echo "60 $global_minute"
+    return 0
+  fi
+
+  # 3. Default: derive from project path hash (never collides across projects)
+  local offset
+  offset=$(_loop_derive_minute "$project_path" 0)
+  echo "60 $offset"
+}
+
 # US-LOOP-001: structured event emission for cycle observability.
 # Writes a tab-separated line to stdout (for tmux/attach display) and appends
 # a JSON line to the per-project NDJSON event file under _SHARED_ROOT/loop/.
@@ -4542,7 +4901,7 @@ _loop_event() {
         startup) _emoji="🚀" ;;
         preflight) _emoji="🔍" ;;
         worktree_setup) _emoji="🌳" ;;
-        claude_invoke) _emoji="🤖" ;;
+        agent_invoke) _emoji="🤖" ;;
         publish_push) _emoji="📤" ;;
         publish_wait_merge) _emoji="⏳" ;;
         cleanup) _emoji="🧹" ;;
@@ -4761,30 +5120,15 @@ _write_loop_runner_script() {
   # US-AUTO-037: strip leading `cd "<path>" && ` (callers like
   # _install_launchd_plists prepend it). The runner now manages cwd itself
   # — pointing at the worktree when isolation succeeds, project_path otherwise.
-  local claude_cmd; claude_cmd="${cmd_verbose#cd \"*\" && }"
+  local agent_cmd; agent_cmd="${cmd_verbose#cd \"*\" && }"
   # FIX-048: Claude Code resolves project root from the worktree's .git file to
   # the main repo, placing worktree absolute paths outside its sandbox. Inject
   # --add-dir "$WT" so the worktree directory is explicitly allowed. Only applies
   # to claude (the --output-format stream-json flag is exclusive to claude runs).
-  if [[ "$claude_cmd" == *"--output-format stream-json"* ]]; then
-    claude_cmd="${claude_cmd/--output-format stream-json/--output-format stream-json --add-dir \"\$WT\"}"
+  if [[ "$agent_cmd" == *"--output-format stream-json"* ]]; then
+    agent_cmd="${agent_cmd/--output-format stream-json/--output-format stream-json --add-dir \"\$WT\"}"
   fi
   local slug; slug=$(_project_slug "$project_path")
-  # FIX-115: build fallback agent command. When primary agent fails all 3
-  # attempts, the inner runner switches to this command for 3 more attempts.
-  local fallback_agent; fallback_agent=$(_fallback_agent)
-  local fallback_cmd=""
-  if [[ -n "$fallback_agent" ]]; then
-    local fallback_skill_file="${ROLL_HOME}/skills/roll-loop/SKILL.md"
-    if [[ -f "$fallback_skill_file" ]]; then
-      local fallback_prompt; fallback_prompt=$(_skill_content "$fallback_skill_file")
-      if _agent_argv "$fallback_agent" plain "$fallback_prompt" 2>/dev/null; then
-        _AGENT_ARGV[0]=$(command -v "${_AGENT_ARGV[0]}" 2>/dev/null || echo "${_AGENT_ARGV[0]}")
-        printf -v fallback_cmd '%q ' "${_AGENT_ARGV[@]}"
-        fallback_cmd="${fallback_cmd% }"
-      fi
-    fi
-  fi
   cat > "$inner_path" << INNER
 #!/bin/bash -l
 set -o pipefail
@@ -4816,7 +5160,7 @@ printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
 # to detect stale execution without relying on PID reuse heuristics.
 # US-LOOP-007: heartbeat also emits phase_tick for the current phase so tmux
 # readers see "still alive in <phase>" during long-running silences (e.g.
-# claude_invoke 5-45 min). CURRENT_PHASE is maintained by _phase_begin/_phase_end.
+# agent_invoke 5-45 min). CURRENT_PHASE is maintained by _phase_begin/_phase_end.
 HEARTBEAT_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
 CURRENT_PHASE=""
 # bash 3.2 (macOS /bin/bash) lacks associative arrays — use namespaced
@@ -5193,11 +5537,7 @@ export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
 # US-LOOP-010: tell loop-fmt.py which agent is running so it can branch
 # rendering: claude → stream-json parser, others → transparent passthrough.
 export ROLL_LOOP_AGENT="\$(_project_agent)"
-_phase_begin claude_invoke
-# FIX-115: fallback agent support — when primary fails 3 attempts, try fallback 3 more
-FALLBACK_AGENT_NAME="${fallback_agent}"
-FALLBACK_CMD="${fallback_cmd}"
-_USE_FALLBACK=0
+_phase_begin agent_invoke
 for _attempt in 1 2 3; do
   # FIX-068: defensive reset before each attempt — _CYCLE_TIMED_OUT carries
   # the SIGTERM result of the previous attempt and would otherwise force an
@@ -5220,9 +5560,9 @@ for _attempt in 1 2 3; do
     } ) &
   _WATCHDOG_PID=\$!
   if [ -f "\$FMT" ]; then
-    ( cd "\$WT" && ${claude_cmd} ) | python3 "\$FMT"
+    ( cd "\$WT" && ${agent_cmd} ) | python3 "\$FMT"
   else
-    ( cd "\$WT" && ${claude_cmd} )
+    ( cd "\$WT" && ${agent_cmd} )
   fi
   _exit=\$?
   kill "\$_WATCHDOG_PID" 2>/dev/null
@@ -5235,48 +5575,10 @@ for _attempt in 1 2 3; do
   fi
 done
 
-# FIX-115: fallback agent retry — when primary fails all 3 attempts and a
-# fallback_agent is configured, try the fallback for 3 more attempts.
-if [ "\$_CYCLE_TIMED_OUT" -eq 0 ] && [ "\$_exit" -ne 0 ] && [ -n "\$FALLBACK_AGENT_NAME" ] && [ -n "\$FALLBACK_CMD" ]; then
-  _loop_event agent_switch "\$FALLBACK_AGENT_NAME" "" "primary failed after 3 attempts" || true
-  _loop_event agent_used "\${CYCLE_ID}" "\$FALLBACK_AGENT_NAME" "fallback" || true
-  echo "[loop] primary agent failed after 3 attempts — switching to fallback: \$FALLBACK_AGENT_NAME"
-  _USE_FALLBACK=1
-  # US-LOOP-010: tell loop-fmt which fallback agent is running so it renders
-  # correctly (passthrough for non-claude, stream-json for claude).
-  export ROLL_LOOP_AGENT="\$FALLBACK_AGENT_NAME"
-  for _attempt in 1 2 3; do
-    _CYCLE_TIMED_OUT=0
-    ( sleep "\$LOOP_CYCLE_TIMEOUT_SEC" && {
-        kill -TERM \$\$ 2>/dev/null
-        pkill -TERM -P \$\$ 2>/dev/null
-        pkill -TERM -f "\$WT" 2>/dev/null
-        sleep 5
-        pkill -KILL -P \$\$ 2>/dev/null
-        pkill -KILL -f "\$WT" 2>/dev/null
-      } ) &
-    _WATCHDOG_PID=\$!
-    if [ -f "\$FMT" ]; then
-      ( cd "\$WT" && \$FALLBACK_CMD ) | python3 "\$FMT"
-    else
-      ( cd "\$WT" && \$FALLBACK_CMD )
-    fi
-    _exit=\$?
-    kill "\$_WATCHDOG_PID" 2>/dev/null
-    wait "\$_WATCHDOG_PID" 2>/dev/null
-    [ "\$_CYCLE_TIMED_OUT" -eq 1 ] && break
-    [ "\$_exit" -eq 0 ] && break
-    if [ "\$_attempt" -lt 3 ]; then
-      echo "[loop] \$FALLBACK_AGENT_NAME exited \$_exit (attempt \$_attempt/3) — retrying in 30s..."
-      sleep 30
-    fi
-  done
-fi
-
 if [ "\$_CYCLE_TIMED_OUT" -eq 1 ] || [ "\$_exit" -ne 0 ]; then
-  _phase_end claude_invoke fail
+  _phase_end agent_invoke fail
 else
-  _phase_end claude_invoke ok
+  _phase_end agent_invoke ok
 fi
 
 # FIX-057: timed out — skip publish; EXIT trap writes cycle_end blocked + ALERT.
@@ -5323,6 +5625,14 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
     if [ "\$_cycle_commits" -eq 0 ]; then
       _worktree_cleanup "\$WT" "\$BRANCH"
       _loop_event idle "\${CYCLE_ID}" "" "" || true
+      # FIX-F (2026-05-25): explicitly write the terminal "idle" cycle_end +
+      # runs row here, otherwise the EXIT trap's catch-all fallback (which
+      # writes "aborted" when _CYCLE_END_WRITTEN is still 0) will reclassify
+      # this successful no-op as a failure on the dashboard.
+      _loop_event cycle_end "\${CYCLE_ID}" "" "idle" || true
+      _CYCLE_END_WRITTEN=1
+      _phases_idle=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_idle" ] && _phases_idle='{}'
+      _runs_append "idle" 0 "[]" "\$_phases_idle" 2>/dev/null || true
       echo "[loop] cycle \${CYCLE_ID}: idle (no new commits); worktree cleaned"
     else
       _is_doc_only=0
@@ -5525,7 +5835,14 @@ if command -v tmux >/dev/null 2>&1; then
   # Microsoft Teams.app).
   if [ -z "\${ROLL_LOOP_NO_POPUP:-}" ] && [ -z "\${BATS_TEST_NUMBER:-}" ] && [ ! -f "\$HOME/.shared/roll/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ]; then
     _attach_cmd="\$HOME/.shared/roll/loop/attach-\$SESSION.command"
-    printf '#!/bin/bash\\nexec tmux attach -t %s\\n' "\$SESSION" > "\$_attach_cmd" 2>/dev/null || true
+    # Drop \`exec\` so the wrapping shell survives \`tmux attach\` exiting,
+    # then \`read\` to hold the Terminal open until the user has had a
+    # chance to scroll back through the cycle's output. Without this the
+    # window closes the instant the tmux session ends (cycle_end kills
+    # the session) and the entire scrollback disappears with it; the
+    # cron-<slug>.log file still has the full transcript as a fallback.
+    printf '#!/bin/bash\\ntmux attach -t %s\\necho\\necho "================================================================"\\necho "  cycle ended. log: ~/.shared/roll/loop/cron-%s.log"\\necho "  press enter to close this window."\\necho "================================================================"\\nread _\\n' \\
+      "\$SESSION" "${slug}" > "\$_attach_cmd" 2>/dev/null || true
     chmod +x "\$_attach_cmd" 2>/dev/null || true
     open -g -a Terminal "\$_attach_cmd" >/dev/null 2>&1 || true
   fi
@@ -5646,6 +5963,9 @@ _install_launchd_plists() {
   # FIX-058: after FIX-056 introduced realpath normalization, the slug for an
   # existing project may have changed.  Migrate state before creating new files.
   _slug_migrate_from_legacy "$slug" "${shared}/loop"
+  # US-OBS-010: when slug changed from path-based to remote-based, merge
+  # old records into the new identity (dedup, atomic, .bak backup)
+  _slug_migrate_to_remote "$project_path" "${shared}/loop"
   for i in "${!services[@]}"; do
     local svc="${services[$i]}"
     local skill="${skill_names[$i]}"
@@ -6160,7 +6480,7 @@ _loop_attach() {
 # Pretty-print a duration in seconds as "Xs" / "Ym" / "Yh Zm".
 # US-VIEW-019: compute slowest phase + % from a JSON line's phases object.
 # Returns "<abbr> <pct>%" (e.g. "claude 97%") or empty when no phases data.
-# Abbreviations match the AC: claude_invoke→claude, publish_wait_merge→pr-wait,
+# Abbreviations match the AC: agent_invoke→agent, publish_wait_merge→pr-wait,
 # publish_push→publish, worktree_setup→worktree; others unchanged.
 _loop_runs_slowest_phase() {
   local line="$1"
@@ -6173,7 +6493,7 @@ _loop_runs_slowest_phase() {
   [ -z "$max_name" ] && return 0
   local abbr="$max_name"
   case "$max_name" in
-    claude_invoke) abbr="claude" ;;
+    agent_invoke) abbr="agent" ;;
     publish_wait_merge) abbr="pr-wait" ;;
     publish_push) abbr="publish" ;;
     worktree_setup) abbr="worktree" ;;
@@ -6380,9 +6700,14 @@ _notify() {
 }
 
 # Count `tcr:` prefixed commits in the current git repo since started_at timestamp.
+# FIX-D 2026-05-25: use --all so commits made on a cycle worktree branch (not
+# yet merged into the current HEAD) are still counted. Without --all the
+# enforce-tcr check inside a cycle-worktree cwd would miss the worktree's own
+# fresh commits when the runner happens to chdir to the main repo before
+# calling enforce-tcr.
 _loop_tcr_count() {
   local started_at="$1"
-  git log --oneline --since="${started_at}" 2>/dev/null \
+  git log --all --oneline --since="${started_at}" 2>/dev/null \
     | awk '/^[a-f0-9]+ tcr:/{n++} END{print n+0}'
 }
 
@@ -7416,6 +7741,33 @@ _worktree_merge_back() {
     _worktree_alert "pull --ff-only origin main failed (remote diverged?)"
     return 1
   fi
+  # FIX-E (2026-05-25): only doc-only branches may take the ff-merge fast path.
+  # Code changes must go through PR + CI; bypassing that gate has caused
+  # cycle commits to land on main with red CI, undetected. The check is the
+  # same one publish_push uses for the doc-vs-code split; here we apply it
+  # to the loop branch's diff against the (already-pulled) main HEAD so the
+  # bypass is also closed in the gh-unavailable fallback path. The ALERT
+  # body is targeted at the next cycle's agent (human-on-the-loop), telling
+  # it how to retry through the normal flow rather than waiting for a human.
+  local _changed
+  _changed=$(git diff --name-only HEAD.."$branch" 2>/dev/null)
+  if [ -n "$_changed" ] \
+     && echo "$_changed" | grep -qvE '^(\.roll/|CHANGELOG\.md|guide/|site/|\.claude/|BACKLOG\.md|PROPOSALS\.md|docs/)'; then
+    _worktree_alert "$(printf '%s\n' \
+      "## PRIOR CYCLE FAILED PUBLISH — REQUIRES NORMAL PR FLOW (FIX-E)" \
+      "branch: ${branch}" \
+      "reason: _loop_publish_pr failed (gh unavailable / API error); ff-merge" \
+      "        fallback was refused because the branch contains code changes." \
+      "        Code must not bypass PR+CI." \
+      "" \
+      "next-cycle action (agent reads this and retries automatically):" \
+      "  1. SKIP normal Todo scan this cycle." \
+      "  2. git push origin ${branch}" \
+      "  3. gh pr create --base main --head ${branch}" \
+      "  4. gh pr merge ${branch} --auto --squash --delete-branch" \
+      "  5. exit cleanly so CI runs and auto-merge takes over.")"
+    return 1
+  fi
   if ! git merge --ff-only "$branch" --quiet 2>/dev/null; then
     _worktree_alert "merge --ff-only ${branch} failed (not fast-forwardable from main)"
     return 1

package/lib/roll-home.py

@@ -31,7 +31,41 @@ from roll_render import COLS, c, row, section_head, strw, pad
 # ════════════════════════════════════════════════════════════════════════════
 # Paths
 # ════════════════════════════════════════════════════════════════════════════
+def _git_remote_url(repo_path: str) -> Optional[str]:
+    """Mirror lib/roll-loop-status.py::_git_remote_url — origin first, then any."""
+    try:
+        url = subprocess.check_output(
+            ["git", "-C", repo_path, "remote", "get-url", "origin"],
+            stderr=subprocess.DEVNULL, text=True,
+        ).strip()
+        if url:
+            return url
+    except Exception:
+        pass
+    try:
+        remotes = subprocess.check_output(
+            ["git", "-C", repo_path, "remote"],
+            stderr=subprocess.DEVNULL, text=True,
+        ).strip().splitlines()
+        if remotes:
+            url = subprocess.check_output(
+                ["git", "-C", repo_path, "remote", "get-url", remotes[0]],
+                stderr=subprocess.DEVNULL, text=True,
+            ).strip()
+            if url:
+                return url
+    except Exception:
+        pass
+    return None
+
+
 def _project_slug(path: Optional[str] = None) -> str:
+    # US-LOOP-006: cycle wrapper exports ROLL_MAIN_SLUG — honour it (parity with
+    # bin/roll _project_slug and lib/roll-loop-status.py project_slug).
+    env_slug = os.environ.get("ROLL_MAIN_SLUG", "").strip()
+    if env_slug:
+        return env_slug
+
     path = os.path.realpath(path or os.getcwd())
     try:
         common = subprocess.check_output(
@@ -42,6 +76,27 @@ def _project_slug(path: Optional[str] = None) -> str:
             path = common[:-5]
     except Exception:
         pass
+
+    # US-OBS-010: derive slug from git remote URL for stable cross-machine
+    # identity. Mirror normalization in bin/roll + lib/roll-loop-status.py
+    # so all three callers agree on the slug. Without this, `roll` home dash
+    # looks up plists at the old path-based slug while `roll loop status`
+    # looks them up at the new remote-based slug — dashboards diverge and
+    # the home page falsely reports the loop as "missing".
+    remote_url = _git_remote_url(path)
+    if remote_url:
+        remote_url = remote_url.rstrip("/")
+        if remote_url.endswith(".git"):
+            remote_url = remote_url[:-4]
+        m = re.match(r"^git@([^:]+):(.+)$", remote_url)
+        if m:
+            remote_url = f"https://{m.group(1)}/{m.group(2)}"
+        remote_url = remote_url.lower()
+        base = re.sub(r"[^A-Za-z0-9]+", "-", os.path.basename(remote_url)).strip("-")
+        h = hashlib.md5(remote_url.encode()).hexdigest()[:6]
+        return f"{base}-{h}"
+
+    # Fallback: path-based (pre-US-OBS-010 behaviour) when no remote configured.
     base = re.sub(r"[^A-Za-z0-9]+", "-", os.path.basename(path)).strip("-")
     h = hashlib.md5(path.encode()).hexdigest()[:6]
     return f"{base}-{h}"

package/lib/roll-loop-status.py

@@ -52,6 +52,11 @@ from roll_render import (
 # Paths — must match bin/roll's _project_slug + _SHARED_ROOT defaults
 # ════════════════════════════════════════════════════════════════════════════
 def project_slug(path: Optional[str] = None) -> str:
+    # US-LOOP-006: cycle wrapper exports ROLL_MAIN_SLUG — honour it.
+    env_slug = os.environ.get("ROLL_MAIN_SLUG", "").strip()
+    if env_slug:
+        return env_slug
+
     path = os.path.realpath(path or os.getcwd())
     try:  # resolve git worktree → main tree (FIX-034 in bin/roll)
         common = subprocess.check_output(
@@ -62,10 +67,57 @@ def project_slug(path: Optional[str] = None) -> str:
             path = common[:-5]
     except Exception:
         pass
+
+    # US-OBS-010: derive slug from git remote URL for stable cross-machine
+    # identity.  Normalize: strip .git, git@HOST:PATH → https://HOST/PATH,
+    # lowercase.  Fallback chain: origin → first remote → path-based.
+    remote_url = _git_remote_url(path)
+    if remote_url:
+        # Normalize
+        remote_url = remote_url.rstrip("/")
+        if remote_url.endswith(".git"):
+            remote_url = remote_url[:-4]
+        m = re.match(r"^git@([^:]+):(.+)$", remote_url)
+        if m:
+            remote_url = f"https://{m.group(1)}/{m.group(2)}"
+        remote_url = remote_url.lower()
+        base = re.sub(r"[^A-Za-z0-9]+", "-", os.path.basename(remote_url)).strip("-")
+        h = hashlib.md5(remote_url.encode()).hexdigest()[:6]
+        return f"{base}-{h}"
+
     base = re.sub(r"[^A-Za-z0-9]+", "-", os.path.basename(path)).strip("-")
     h = hashlib.md5(path.encode()).hexdigest()[:6]
     return f"{base}-{h}"
 
+
+def _git_remote_url(repo_path: str) -> Optional[str]:
+    """Return the normalized remote URL for a git repo, or None."""
+    try:
+        url = subprocess.check_output(
+            ["git", "-C", repo_path, "remote", "get-url", "origin"],
+            stderr=subprocess.DEVNULL, text=True
+        ).strip()
+        if url:
+            return url
+    except Exception:
+        pass
+    # Fallback: first available remote
+    try:
+        remotes = subprocess.check_output(
+            ["git", "-C", repo_path, "remote"],
+            stderr=subprocess.DEVNULL, text=True
+        ).strip().splitlines()
+        if remotes:
+            url = subprocess.check_output(
+                ["git", "-C", repo_path, "remote", "get-url", remotes[0]],
+                stderr=subprocess.DEVNULL, text=True
+            ).strip()
+            if url:
+                return url
+    except Exception:
+        pass
+    return None
+
 def shared_root() -> Path:
     return Path(os.environ.get("ROLL_SHARED_ROOT") or os.path.expanduser("~/.shared/roll"))
 

package/lib/roll_render.py

@@ -88,6 +88,17 @@ def fmt_dur(s: int) -> str:
         return f"{s // 60}m"
     return f"{s // 3600}h {(s % 3600) // 60}m"
 
+# FIX-121: agent → primary model used by `roll loop` dashboard's fallback
+# when an event stream lacks an explicit model name (non-claude agents'
+# stdout isn't stream-json so loop-fmt can't extract model). Keeps the
+# model column consistent with claude's "opus-4-7" style.
+_AGENT_PRIMARY_MODEL = {
+    "pi":       "deepseek-v4-pro",
+    "deepseek": "deepseek-v4-pro",
+    "kimi":     "kimi-k2-0905",
+}
+
+
 def fmt_model(model) -> str:
     """Short label for the cycle row's model column.
 
@@ -339,8 +350,11 @@ def cycle_row(cy: Dict[str, Any], backlog: Dict[str, str]) -> None:
     # FIX-119: fall back to cy["agent"] (from agent_used event) when model
     # is unknown — non-claude agents (pi, deepseek, kimi) don't expose model
     # info in stream-json, leaving a "—" or "?" on the dashboard.
+    # FIX-121: map agent → its configured primary model so the column shows
+    # the actual model name (e.g. "deepseek-v4-pro") consistently with
+    # claude's "opus-4-7", not the bare agent name ("pi").
     if model_label in ("—", "?") and cy.get("agent"):
-        model_label = cy["agent"]
+        model_label = _AGENT_PRIMARY_MODEL.get(cy["agent"], cy["agent"])
     # Auto-hide model column on narrow screens — keeps the dashboard readable
     # when terminal is < 100 cols (cost / story IDs are higher-priority).
     show_model = COLS >= 100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.524.2",
+  "version": "2026.525.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-loop/SKILL.md

@@ -6,7 +6,8 @@ description: |
   Autonomous BACKLOG executor. Runs on a schedule (hourly via cron or GitHub
   Actions), scans .roll/backlog.md for 📋 Todo items, and routes each to the
   appropriate skill: US-XXX → $roll-build, FIX-XXX → $roll-fix,
-  REFACTOR-XXX → $roll-build. Handles agent fallback on token/network failure.
+  REFACTOR-XXX → $roll-build. Retries the primary agent up to 3 times on
+  transient failure; pauses with ALERT on persistent failure.
   Never cuts a release autonomously — release is always a human decision.
   Triggers roll-brief when a Feature completes.
 ---
@@ -73,8 +74,7 @@ denied operations and the cycle will idle-exit.
 ```yaml
 # ~/.roll/config.yaml
 loop:
-  primary_agent: claude          # claude | deepseek | kimi
-  fallback_agent: deepseek       # used when primary fails
+  primary_agent: claude          # claude | deepseek | kimi | pi | ...
   max_items_per_run: 1           # one story per cycle — atomic delivery, predictable cycle time
   brief_on_feature_complete: true
   retry_backoff: [2, 4, 8, 16]  # seconds, exponential
@@ -103,12 +103,24 @@ this point, any `🔨 In Progress` row in `.roll/backlog.md` belongs to a
 previous cycle that crashed before flipping it back; reclaim it before
 scanning.
 
+**Important — skip `manual-only:*` rows.** A row tagged `manual-only:*`
+means a human (or another non-loop process) has explicitly claimed it;
+it is not loop's to reclaim. Reverting it would silently undo the
+human's claim and cause confusing churn for `roll-brief` / dashboard
+readers. The rule mirrors the gate in Step 2.
+
 1. Scan .roll/backlog.md for all rows whose Status column contains `🔨 In Progress`.
-2. For each row found: revert the status back to `📋 Todo`, commit
-   `chore: revert orphan 🔨 US-XXX to 📋`, and append a line to
-   `~/.shared/roll/loop/ALERT-<slug>.md` recording the orphan id and time
-   so the next brief surfaces it.
-3. After orphan sweep, proceed to Step 1.5 (Pre-run CI health check) before scanning.
+2. For each candidate row, run the manual-only gate before touching it:
+   ```bash
+   bash -c 'source "$(command -v roll)"; _loop_is_manual_only "<story-id>" .roll/backlog.md'
+   #   exit 0 → row has `manual-only:*` → SKIP (human-claimed; not orphan)
+   #   exit 1 → reclaimable orphan; continue to step 3
+   ```
+3. For each row that passes the gate: revert the status back to
+   `📋 Todo`, commit `chore: revert orphan 🔨 US-XXX to 📋`, and append
+   a line to `~/.shared/roll/loop/ALERT-<slug>.md` recording the orphan
+   id and time so the next brief surfaces it.
+4. After orphan sweep, proceed to Step 1.5 (Pre-run CI health check) before scanning.
 
 ### Step 1.5 — Pre-run CI Health Check
 
@@ -427,21 +439,20 @@ Attempt 1 fails
 
 ```
 Primary agent fails (non-network error)
-  → switch to fallback_agent from config
-  → retry current item with fallback
-  → if fallback also fails → PAUSE
+  → 3 attempts at the agent_invoke phase (with 30s back-off between)
+  → still failing → PAUSE
 ```
 
 ### Pause + Alert
 
-When both agents fail:
+When the primary agent exhausts its retry budget:
 
 1. Write state:
 ```yaml
 status: paused
 paused_at: "2026-05-10T02:07:00+08:00"
 paused_on: US-AUTH-003
-reason: "both primary (claude) and fallback (deepseek) unavailable"
+reason: "primary agent (claude) unavailable after 3 attempts"
 ```
 
 2. Write alert:
@@ -450,11 +461,11 @@ reason: "both primary (claude) and fallback (deepseek) unavailable"
 
 **Time**: 2026-05-10 02:07
 **Paused on**: US-AUTH-003
-**Reason**: claude: token exhausted; deepseek: network error after 5 retries
+**Reason**: claude exited non-zero on 3 consecutive attempts
 
 **Action required** (choose one):
 - Top up credits and run: `roll loop resume`
-- Switch agent: edit `~/.roll/config.yaml` → `loop.primary_agent`
+- Switch agent: edit `~/.roll/config.yaml` → `primary_agent`
 - Take over manually: `$roll-build US-AUTH-003`
 ```