@seanyao/roll 2026.524.1 → 2026.524.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v2026.524.2
+
+### Added
+
+- **用 pi / deepseek / kimi 跑的 loop 也能在终端里实时看到进度** — 不再黑屏 `[loop]`
+- **`roll slides new` 可以用项目自己的模板** — 不只用内置的了 `[deck]`
+- **`roll slides list` 一眼看出 slide 状态** — 哪些能看、哪些生成失败、失败原因也能查 `[deck]`
+
+### Fixed
+
+- **loop 不再一次吞太多故事** — 每次只做一个，时间可预期 `[loop]`
+- **dashboard 不再对非 Claude 模型显示空白** — 能看出每轮谁跑的 `[loop]`
+
 ## v2026.524.1
 
 ### Added

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.1"
+VERSION="2026.524.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -3342,11 +3342,13 @@ USAGE  用法
   roll slides new "<topic>" [--template <name>] [--no-build]
                           Generate deck.md via AI, then auto-build + open HTML
                           通过 AI 生成 deck.md，自动渲染并打开 HTML
-  roll slides list        List all decks under .roll/slides/ as a table
-                          列出 .roll/slides/ 下所有幻灯片
+  roll slides list        List all decks (built / stale / failed / unbuilt)
+                          列出 .roll/slides/ 下所有幻灯片（四态）
   roll slides preview <slug> [--no-open]
                           Open .roll/slides/<slug>.html in the default browser
                           在浏览器中打开已渲染的幻灯片
+  roll slides logs <slug> Show the last build failure log for a deck
+                          显示幻灯片上次构建失败日志
 
 OPTIONS  选项
   --no-open               Skip auto-opening the rendered HTML in a browser
@@ -3367,6 +3369,12 @@ _slides_lib() {
 # Returns 0 + prints the path if the template exists, else returns 1.
 _slides_template_path() {
   local name="$1"
+  # US-DECK-013: project-level template override takes priority over built-in.
+  local proj_tpl=".roll/slides/templates/${name}.html"
+  if [[ -f "$proj_tpl" ]]; then
+    printf '%s' "$proj_tpl"
+    return 0
+  fi
   local tpl="${ROLL_PKG_DIR}/lib/slides/templates/${name}.html"
   if [[ -f "$tpl" ]]; then
     printf '%s' "$tpl"
@@ -3459,8 +3467,19 @@ cmd_slides_build() {
     return 1
   fi
 
+  # US-DECK-011: capture failure to .last-build.err for slides logs
+  local err_file=".roll/slides/${slug}/.last-build.err"
+
   # 1. Validate first (fail-fast on AI-generated decks).
-  if ! python3 "$validator" "$deck"; then
+  # Exit 2 = grounding warning (schema OK, evidence below threshold) — warn but don't fail.
+  local val_out val_exit
+  val_out=$(python3 "$validator" "$deck" 2>&1) || val_exit=$?
+  if [[ "${val_exit:-0}" -eq 2 ]]; then
+    echo "[roll] ${val_out}" >&2
+  elif [[ "${val_exit:-0}" -ne 0 ]]; then
+    local ts; ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    mkdir -p ".roll/slides/${slug}"
+    printf '[%s] stage=validate\n%s\n' "$ts" "$val_out" > "$err_file"
     err "deck.md validation failed — fix the issues above before building."
     echo "  deck.md 校验失败，请先修复上方提示再重试。" >&2
     return 1
@@ -3470,16 +3489,25 @@ cmd_slides_build() {
   local tpl_name; tpl_name=$(_slides_template_for_deck "$deck")
   local tpl_path
   if ! tpl_path=$(_slides_template_path "$tpl_name"); then
+    local ts; ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    mkdir -p ".roll/slides/${slug}"
+    printf '[%s] stage=template\ntemplate not found: %s\n' "$ts" "$tpl_name" > "$err_file"
     err "Template not found: ${tpl_name}  未找到模板：${tpl_name}"
     return 1
   fi
 
   local out=".roll/slides/${slug}.html"
   mkdir -p ".roll/slides"
-  if ! python3 "$renderer" "$deck" "$tpl_path" "$out"; then
+  local render_out; render_out=$(python3 "$renderer" "$deck" "$tpl_path" "$out" 2>&1) || {
+    local ts; ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    mkdir -p ".roll/slides/${slug}"
+    printf '[%s] stage=render\n%s\n' "$ts" "$render_out" > "$err_file"
     err "Render failed for ${deck}  渲染失败：${deck}"
     return 1
-  fi
+  }
+
+  # US-DECK-011: build succeeded — remove any stale .last-build.err
+  rm -f "$err_file" 2>/dev/null || true
 
   # 3. Default-ignore the HTML artefact so it doesn't accidentally get committed.
   _slides_ensure_gitignore
@@ -3571,31 +3599,42 @@ cmd_slides_list() {
   IFS=$'\n' sorted_slugs=($(printf '%s\n' "${slugs[@]}" | sort))
   unset IFS
 
-  printf '%-20s  %-20s  %-12s  %-12s  %-5s  %s\n' \
+  printf '%-20s  %-20s  %-12s  %-12s  %-8s  %s\n' \
     "slug" "template" "total_slides" "created" "built" "size"
-  printf '%-20s  %-20s  %-12s  %-12s  %-5s  %s\n' \
-    "----" "--------" "------------" "-------" "-----" "----"
+  printf '%-20s  %-20s  %-12s  %-12s  %-8s  %s\n' \
+    "----" "--------" "------------" "-------" "------" "----"
 
-  local s deck html template total created built size bytes
+  local s deck html err_file template total created built size bytes
   for s in "${sorted_slugs[@]}"; do
     deck="${slides_dir}/${s}/deck.md"
     html="${slides_dir}/${s}.html"
+    err_file="${slides_dir}/${s}/.last-build.err"
     template=$(_slides_frontmatter_field "$deck" "template")
     [[ -z "$template" ]] && template="-"
     total=$(_slides_frontmatter_field "$deck" "total_slides")
     [[ -z "$total" ]] && total="-"
     created=$(_slides_frontmatter_field "$deck" "created")
     [[ -z "$created" ]] && created="-"
-    if [[ -f "$html" ]]; then
-      built="✓"
-      bytes=$(wc -c <"$html" 2>/dev/null | tr -d ' ')
-      [[ -z "$bytes" ]] && bytes=0
-      size=$(_slides_human_size "$bytes")
+    # US-DECK-011: 4-state built column
+    if [[ -f "$err_file" ]]; then
+      built="⚠ failed"
+      size="-"
+    elif [[ -f "$html" ]]; then
+      # Check if deck.md is newer than the HTML (stale)
+      if [[ "$deck" -nt "$html" ]]; then
+        built="≈ stale"
+        size="-"
+      else
+        built="✓ built"
+        bytes=$(wc -c <"$html" 2>/dev/null | tr -d ' ')
+        [[ -z "$bytes" ]] && bytes=0
+        size=$(_slides_human_size "$bytes")
+      fi
     else
-      built="✗"
+      built="✗ unbuilt"
       size="-"
     fi
-    printf '%-20s  %-20s  %-12s  %-12s  %-5s  %s\n' \
+    printf '%-20s  %-20s  %-12s  %-12s  %-8s  %s\n' \
       "$s" "$template" "$total" "$created" "$built" "$size"
   done
   return 0
@@ -3645,6 +3684,46 @@ cmd_slides_preview() {
   return 0
 }
 
+# ─── US-DECK-011 ─────────────────────────────────────────────────────────────
+cmd_slides_logs() {
+  local slug=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --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 logs <slug>"
+    echo "用法: roll slides logs <slug>" >&2
+    return 1
+  fi
+
+  local deck_dir=".roll/slides/${slug}"
+  local err_file="${deck_dir}/.last-build.err"
+
+  if [[ ! -d "$deck_dir" ]] || [[ ! -f "${deck_dir}/deck.md" ]]; then
+    err "Deck not found: ${slug}  未找到幻灯片：${slug}"
+    return 1
+  fi
+
+  if [[ ! -f "$err_file" ]]; then
+    info "No failure records for ${slug}  该幻灯片没有失败记录"
+    return 0
+  fi
+
+  cat "$err_file"
+  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,
@@ -4001,6 +4080,9 @@ cmd_slides() {
     preview)
       cmd_slides_preview "$@"
       ;;
+    logs)
+      cmd_slides_logs "$@"
+      ;;
     --help|-h|help)
       _slides_help
       return 0
@@ -5083,6 +5165,7 @@ if _worktree_fetch_origin main \\
   _worktree_sync_meta "\$WT" 2>/dev/null || true
   echo "[loop] cycle \${CYCLE_ID}: worktree \$WT on \$BRANCH"
   _loop_event cycle_start "\${CYCLE_ID}" "" "" || true
+  _loop_event agent_used "\${CYCLE_ID}" "\$(_project_agent)" "primary" || true
   _phase_end worktree_setup ok
 else
   # P3 fix: skip the cycle entirely when worktree isolation fails.
@@ -5107,6 +5190,9 @@ FMT="${fmt_script}"
 export LOOP_PROJECT_SLUG="${slug}"
 export LOOP_CYCLE_ID="\${CYCLE_ID}"
 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}"
@@ -5153,8 +5239,12 @@ done
 # 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" && {
@@ -5166,7 +5256,11 @@ if [ "\$_CYCLE_TIMED_OUT" -eq 0 ] && [ "\$_exit" -ne 0 ] && [ -n "\$FALLBACK_AGE
         pkill -KILL -f "\$WT" 2>/dev/null
       } ) &
     _WATCHDOG_PID=\$!
-    ( cd "\$WT" && \$FALLBACK_CMD )
+    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
@@ -5637,7 +5731,7 @@ cmd_loop() {
     on)      _loop_on ;;
     off)     _loop_off ;;
     now)     _loop_now ;;
-    test)    _loop_test ;;
+    test)    shift; _loop_test "$@" ;;
     status)  _loop_status "$@" ;;
     monitor) _loop_monitor "${1:-3}" ;;
     runs)    _loop_runs "$@" ;;
@@ -5852,17 +5946,36 @@ _loop_test() {
   local log="${_SHARED_ROOT}/loop/cron-${slug}.log"
   local test_runner="${_SHARED_ROOT}/loop/run-${slug}-test.sh"
 
+  # US-LOOP-010: --agent <name> lets integration tests exercise the
+  # multi-agent passthrough path without needing a real pi binary.
+  local agent="claude"
+  local agent_cmd=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --agent) agent="${2:-claude}"; shift 2 ;;
+      --cmd)   agent_cmd="${2}"; shift 2 ;;
+      *)       shift ;;
+    esac
+  done
+  if [[ -z "$agent_cmd" ]]; then
+    if [[ "$agent" == "claude" ]]; then
+      agent_cmd='claude -p "Reply with a single word: hello"; sleep 10'
+    else
+      agent_cmd="echo 'mock ${agent} output line 1'; echo 'mock ${agent} output line 2'"
+    fi
+  fi
+
   # FIX-054: terminal preference removed — runner always uses Terminal.app.
   local active_start active_end
   active_start=$(_config_read_int "loop_active_start" "10")
   active_end=$(_config_read_int "loop_active_end" "18")
 
-  info "Generating test runner...  正在生成测试启动脚本..."
+  info "Generating test runner (agent: ${agent})...  正在生成测试启动脚本 (agent: ${agent})..."
   _write_loop_runner_script "$test_runner" "$project_path" \
-    'claude -p "Reply with a single word: hello"; sleep 10' \
+    "${agent_cmd}" \
     "$log" "$active_start" "$active_end"
 
-  info "Starting smoke test (real claude, trivial prompt)...  正在运行 smoke 测试（真实 claude）..."
+  info "Starting smoke test (agent: ${agent})...  正在运行 smoke 测试 (agent: ${agent})..."
   info "Watch for: tmux session + terminal popup + stream-json events flowing"
   info "观察：tmux 会话 + 终端弹窗 + stream-json 事件流"
 
@@ -5872,9 +5985,9 @@ _loop_test() {
   local elapsed=$(( $(date +%s) - start_time ))
 
   if [[ $exit_code -eq 0 ]]; then
-    ok "Smoke test passed (${elapsed}s)  smoke 测试通过 (${elapsed}秒)"
+    ok "Smoke test passed (${elapsed}s, agent: ${agent})  smoke 测试通过 (${elapsed}秒, agent: ${agent})"
   else
-    err "Smoke test failed (exit ${exit_code}, ${elapsed}s)  smoke 测试失败 (退出码 ${exit_code}, ${elapsed}秒)"
+    err "Smoke test failed (exit ${exit_code}, ${elapsed}s, agent: ${agent})  smoke 测试失败 (退出码 ${exit_code}, ${elapsed}s, agent: ${agent})"
     return 1
   fi
 }

package/lib/loop-fmt.py

@@ -441,11 +441,73 @@ class LoopFmt:
             pass  # best-effort; never break tmux output
 
 
-def main():
-    fmt = LoopFmt()
+def _passthrough_main(agent):
+    """Transparent forwarding for non-claude agents (pi, deepseek, kimi, …).
+
+    Writes every stdin line to stdout with a HH:MM:SS timestamp prefix so
+    tmux shows real-time progress.  Also appends each line as a lightweight
+    'usage'-type event to the per-slug events ndjson — token / cost fields
+    are set to null (agent-specific parsing is out of scope for this US).
+    """
+    slug   = os.environ.get("LOOP_PROJECT_SLUG")
+    cycle  = os.environ.get("LOOP_CYCLE_ID")
+    shared = os.environ.get("LOOP_SHARED_ROOT") or os.path.expanduser("~/.shared/roll")
+    evfile = None
+    if slug and cycle:
+        evfile = os.path.join(shared, "loop", f"events-{slug}.ndjson")
+        try:
+            os.makedirs(os.path.dirname(evfile), exist_ok=True)
+        except Exception:
+            evfile = None
+
     for line in sys.stdin:
-        fmt.process(line)
+        if not line.rstrip():
+            continue
+        # Timestamp prefix so tmux shows activity (even if agent output has
+        # no timestamps of its own).
+        ts = datetime.now(timezone.utc).strftime("%H:%M:%S")
+        out = f"{DARK_GRAY}{ts}{RESET}  {line.rstrip()}"
+        sys.stdout.write(out + "\n")
         sys.stdout.flush()
+        # Emit a lightweight usage event so the cycle has *some* event trace
+        # (token/cost are null — parsing those is agent-specific and out of
+        # scope for the minimal transparent-passthrough US).
+        if evfile:
+            _emit_passthrough_event(evfile, cycle, agent, line.rstrip())
+
+
+def _emit_passthrough_event(evfile, cycle, agent, text):
+    """Best-effort append a usage-type event to evfile."""
+    payload = {
+        "model":        agent,
+        "input_tokens":  None,
+        "output_tokens": None,
+        "cost_list_usd": None,
+        "duration_ms":   None,
+    }
+    record = json.dumps({
+        "ts":      datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "stage":   "usage",
+        "label":   cycle,
+        "detail":  payload,
+        "outcome": "ok",
+    }) + "\n"
+    try:
+        with open(evfile, "a") as f:
+            f.write(record)
+    except Exception:
+        pass
+
+
+def main():
+    agent = os.environ.get("ROLL_LOOP_AGENT", "claude")
+    if agent == "claude":
+        fmt = LoopFmt()
+        for line in sys.stdin:
+            fmt.process(line)
+            sys.stdout.flush()
+    else:
+        _passthrough_main(agent)
 
 if __name__ == "__main__":
     main()

package/lib/roll-loop-status.py

@@ -231,6 +231,12 @@ def aggregate(events: List[Dict[str, Any]], cron: List[Dict[str, Any]]) -> List[
             sid = _extract_story_id(detail)
             if sid:
                 cy["story"] = sid
+        elif stage == "agent_used":
+            # FIX-119: non-claude agents don't expose model in stream-json.
+            # The inner runner emits an agent_used event with the agent name
+            # so the dashboard can show it when cy["model"] is None.
+            if detail:
+                cy["agent"] = detail
         elif stage == "usage":
             # US-LOOP-004: loop-fmt emits this with full token / cost data.
             # Detail is a dict (not the legacy string form).

package/lib/roll_render.py

@@ -336,6 +336,11 @@ def cycle_row(cy: Dict[str, Any], backlog: Dict[str, str]) -> None:
     sid_c   = "red" if outcome == "fail" else "blue"
 
     model_label = fmt_model(cy.get("model"))
+    # 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.
+    if model_label in ("—", "?") and cy.get("agent"):
+        model_label = 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.1",
+  "version": "2026.524.2",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-loop/SKILL.md

@@ -75,13 +75,25 @@ denied operations and the cycle will idle-exit.
 loop:
   primary_agent: claude          # claude | deepseek | kimi
   fallback_agent: deepseek       # used when primary fails
-  max_items_per_run: 3           # limit parallel risk; adjust as needed
+  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
 ```
 
 ## Workflow
 
+> **One story per cycle (强约束)**: 每个 cycle 只 pick 一个 Todo、跑完 Step 4
+> 立刻退出，不再回 Step 2 找下一个。理由：
+> - cycle 时间可预测（不会因贪心一连串 PR 撞 45 分钟 hard timeout）
+> - PR / events / dashboard 每行一个故事，归因清晰
+> - 一个故事一个 PR 一次 review，blast radius 最小
+>
+> 唯一例外是依赖修复（CI self-heal 等）已经内嵌在当前故事的 Step 4 里——
+> 那部分不算"新挑故事"。
+>
+> 实现层：max_items_per_run 默认 1，executor skill 跑完 Step 5 必须 exit。
+> 不要在同一个 cycle 内多次 emit `pick_todo` 事件。
+
 ### Step 1 — Orphan 🔨 Recovery
 
 Process-level crash recovery (LOCK, heartbeat, retry budget) is handled by
@@ -311,6 +323,8 @@ After each item completes:
 3. Update state file: `status: idle`
 4. Check if a Feature is now fully complete (all its Stories ✅)
 5. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`
+6. **EXIT the cycle.** 不要回 Step 2 找下一个故事，不要再 emit `pick_todo`。
+   一个 cycle 只交付一个故事；剩下的 Todo 等下一个 launchd tick 起新 cycle 处理。
 
 ### Step 5 — Write Run Summary