@seanyao/roll 2026.517.9 → 2026.518.2

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## v2026.518.2
+
+### Fixed
+
+- **`roll loop status` dashboard 崩溃 / 列对齐** — `_dash_release_ready` 用 `grep -c` 在零匹配时返回 "0" + 非零退出码再被 `|| echo 0` 追加一个 "0"，拼成 "0\n0" 让 `[[ -gt ]]` 报语法错；改用 `grep | wc -l | tr -d ' '` 单值返回。Today 表头去掉 "(in progress)" 后缀（曾溢出到 Yesterday 列），数值列宽 6→8 让指标行对齐表头 `[loop]`
+- **v2026.518.1 在刚发版的仓库里 dashboard 不可用** — 上面那个崩溃在 HEAD == latest tag、或 tag 之后只有 docs/chore commit 的仓库中必触发；本版作为追加修复，升到 v2026.518.2 即恢复 `[release]`
+
+## v2026.518.1
+
+### Improved
+
+- **`roll loop status` 焕新** — 重设计的 dashboard 替换原本的扁平列表：按天 Today / Yesterday / −2d 分列总账（轮次、PR、耗时、tokens、成本、失败计数），下面每天分段列出 cycle 详情；idle / done / fail 用 `·` / `✓` / `✗` 区分，不再统统挂"运行中"；时间统一显示 UTC+8；同一 cycle 的 pr 事件与 cycle_start 不再被错切成两条；多 story cycle 用 `|` 连起来一行展示；走 `ROLL_UI=v2` 默认开，`ROLL_UI=v1` 一键回退到旧实现 `[loop]`
+- **loop 每轮成本和 token 真实可见** — 每个 cycle 结束时把模型用量（input / output / cache_creation / cache_read tokens、claude 上报的折后价、耗时）写进永久事件流，dashboard 按模型公开单价（list price）算出真实成本、按 k / m / b 显示 token，多机器 / 多项目可横向对比；历史 cycle 没写过这条事件的，自动从 claude 自己的会话日志里回灌一份 `[loop]`
+- **`roll update` 不再每次刷 PR 评审两档安装提示** — 两段安装命令挪到 `roll doctor`，在 git repo 内探测分支保护和事件 workflow 的当前状态，只对未启用项显示安装指令 `[pr]`
+
+### Fixed
+
+- **发版管道空版本雪球** — release.sh AI changelog 调用失败时硬退出（不再静默发空 tag）；release.yml 同日合并检测到 fallback notes 时跳过合并，避免把前一个 release body 累积到新版本里 `[release]`
+
+## v2026.517.9
+
+### Improved
+
+- **`roll-loop` 环境变量文档化** — `ROLL_LOOP_FORCE` / `ROLL_LOOP_NO_HEAL` / `ROLL_LOOP_HEAL_MAX` / `ROLL_LOOP_PR_MERGE_TIMEOUT` 四个配置项补入中英双语 configuration 指南，并加 bats 测试守护 `[loop]`
+- **BACKLOG 四种条目渲染折叠** — Story / FIX / REFACTOR / IDEA 四组解析循环结构完全一样，合并为单一渲染函数，格式变更不再需要同步四处 `[refactor]`
+
+## v2026.517.8
+
+> 空版本：发版脚本 AI 调用失败 fallback 未拦截，导致无实际内容的 tag 被推出。缺陷已在后续 commit `005601a` 修复（release.sh 和 release.yml 双重校验），见 Unreleased 段。
+
+## v2026.517.7
+
+> 空版本：原因同 v2026.517.8。
+
 ## v2026.517.6
 
 ### Fixed

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.517.9"
+VERSION="2026.518.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -611,10 +611,7 @@ cmd_setup() {
 
   echo ""
   info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
-
-  echo ""
-  _print_pr_pipeline_hint
-  _print_pr_event_hint
+  info "Optional gates: run ${BOLD}roll doctor${NC} inside a repo to see which PR review extras are still off.  可选闸门：在仓库内运行 roll doctor 查看 PR 评审两档开关状态"
 }
 
 # ─── PR pipeline hint ────────────────────────────────────────────────────────
@@ -644,6 +641,82 @@ _print_pr_pipeline_hint() {
 HINT
 }
 
+# ─── Doctor: PR review extras section (US-PR-004) ────────────────────────────
+# `roll doctor` is the single home for "things you could tune". The PR review
+# extras section probes whether the two optional gates are enabled and only
+# prints install commands for the ones that aren't, so users who already opted
+# in (or opted out) don't get spammed each upgrade.
+cmd_doctor() {
+  _doctor_pr_section
+}
+
+_doctor_pr_section() {
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+
+  echo ""
+  echo "PR review extras  PR 评审两档开关"
+  echo ""
+
+  local protection_state event_state
+  protection_state="$(_doctor_branch_protection_state)"
+  event_state="$(_doctor_event_workflow_state)"
+
+  case "$protection_state" in
+    enabled)
+      echo "  ✅ AI review double gate enabled  AI 评审双门已启用"
+      ;;
+    disabled)
+      echo "  ⚪ AI review double gate not enabled  双门未启用"
+      _print_pr_pipeline_hint
+      ;;
+    *)
+      echo "  ⚪ AI review double gate state unknown — requires gh auth  状态未知（需要 gh auth）"
+      _print_pr_pipeline_hint
+      ;;
+  esac
+
+  case "$event_state" in
+    present)
+      echo "  ✅ Event-driven PR review installed  事件驱动 PR 评审已安装"
+      ;;
+    *)
+      echo "  ⚪ Event-driven PR review not installed  事件驱动 PR 评审未安装"
+      _print_pr_event_hint
+      ;;
+  esac
+}
+
+# Returns one of: enabled | disabled | unknown
+_doctor_branch_protection_state() {
+  command -v gh >/dev/null 2>&1 || { echo unknown; return; }
+
+  local slug
+  slug="$(gh repo view --json owner,name --jq '.owner.login + "/" + .name' 2>/dev/null)"
+  [[ -n "$slug" ]] || { echo unknown; return; }
+
+  local required
+  required="$(gh api "repos/${slug}/branches/main/protection" \
+    --jq '.required_pull_request_reviews.required_approving_review_count // 0' \
+    2>/dev/null)"
+
+  if [[ -z "$required" ]]; then
+    echo unknown
+  elif (( required >= 1 )); then
+    echo enabled
+  else
+    echo disabled
+  fi
+}
+
+# Returns one of: present | absent
+_doctor_event_workflow_state() {
+  if [[ -f ".github/workflows/pr-review-event.yml" ]]; then
+    echo present
+  else
+    echo absent
+  fi
+}
+
 _print_pr_event_hint() {
   cat <<'HINT'
 
@@ -982,7 +1055,6 @@ _write_features_md() {
 # Features
 
 > 产品视角的功能索引。每次发版时更新，使之与 BACKLOG 保持一致。
-> Product-level feature index. Updated at release to stay in sync with BACKLOG.
 
 ---
 
@@ -2270,6 +2342,13 @@ else
 fi
 
 FMT="${fmt_script}"
+# US-LOOP-004: hand loop-fmt the slug + cycle id + shared root so it can
+# append a per-cycle 'usage' event into events-<slug>.ndjson with
+# tokens / cost / model / duration. Reader (roll loop status) consumes
+# that instead of having to scrape the overwritten cron.log.
+export LOOP_PROJECT_SLUG="${slug}"
+export LOOP_CYCLE_ID="\${CYCLE_ID}"
+export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
 for _attempt in 1 2 3; do
   if [ -f "\$FMT" ]; then
     ( cd "\$WT" && ${claude_cmd} ) | python3 "\$FMT"
@@ -2511,7 +2590,7 @@ if command -v tmux >/dev/null 2>&1; then
   # Auto-attach popup: when not muted, spawn a Terminal window attached to the
   # tmux session so the user can watch the loop work in real time. Best-effort
   # focus retention: capture the current frontmost app and re-activate after.
-  if [ ! -f "\$HOME/.shared/roll/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ]; then
+  if [ -z "\${ROLL_LOOP_NO_POPUP:-}" ] && [ ! -f "\$HOME/.shared/roll/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ]; then
     # Runtime terminal detection: try preferred first, fallback through installed apps.
     # open -na returns non-zero when app not found, so || chain works as fallback.
     _launched=0
@@ -2893,6 +2972,16 @@ _loop_test() {
 }
 
 _loop_status() {
+  # ROLL_UI=v2 (default) routes to the redesigned Python view.
+  # Set ROLL_UI=v1 to fall back to the legacy bash implementation.
+  if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-loop-status.py" "$@"
+    return
+  fi
+  _legacy_loop_status "$@"
+}
+
+_legacy_loop_status() {
   local project_path; project_path=$(pwd -P)
   local agent; agent=$(_project_agent)
   local _is_paused=false
@@ -5038,8 +5127,8 @@ _dash_release_ready() {
   latest_tag=$(git describe --tags --abbrev=0 2>/dev/null) || return 1
   local commits_with_code
   commits_with_code=$(git log "${latest_tag}..HEAD" --pretty=format:%s 2>/dev/null \
-    | grep -cvE '^(docs|chore)(\([^)]*\))?:[[:space:]]' 2>/dev/null \
-    || echo 0)
+    | grep -vE '^(docs|chore)(\([^)]*\))?:[[:space:]]' \
+    | wc -l | tr -d ' ')
   [[ "${commits_with_code:-0}" -gt 0 ]] || return 1
   local latest
   latest=$(ls docs/briefs/*.md 2>/dev/null | sort | tail -1 || true)
@@ -5303,6 +5392,7 @@ main() {
     alert)         cmd_alert "$@" ;;
     agent)         cmd_agent "$@" ;;
     ci)            cmd_ci "$@" ;;
+    doctor)        cmd_doctor "$@" ;;
     review-pr)     cmd_review_pr "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;

package/lib/loop-fmt.py

@@ -116,6 +116,11 @@ class LoopFmt:
         self.pending_ci      = False
         self.pending_story   = False
         self.spinner         = Spinner()
+        # Track the most recent usage / model seen on assistant turns so
+        # the result event handler can emit a 'usage' event even when
+        # result.usage is missing.
+        self._last_usage     = None
+        self._last_model     = None
 
     def _extract_cycle_num(self, text):
         m = re.search(r'cycle[#\s]+(\d+)', text, re.IGNORECASE)
@@ -156,6 +161,12 @@ class LoopFmt:
 
     def _handle_assistant(self, ev):
         msg = ev.get("message", {})
+        # Remember the latest usage / model so the trailing result event
+        # can emit a 'usage' event even if result.usage is empty.
+        if msg.get("usage"):
+            self._last_usage = msg["usage"]
+        if msg.get("model"):
+            self._last_model = msg["model"]
         for blk in msg.get("content", []):
             btype = blk.get("type", "")
             if btype == "thinking":
@@ -318,6 +329,46 @@ class LoopFmt:
             cycle_str = f"cycle #{self.cycle_num}" if self.cycle_num else "cycle done"
             print(stamp(f"{cycle_str} — done · {detail}" if detail else f"{cycle_str} — done", muted=True))
 
+        # US-LOOP-004 partial: emit a per-cycle 'usage' event into the
+        # durable events.ndjson so dashboards don't have to rely on the
+        # cron.log (overwritten every cycle). Skips silently when the
+        # required env vars aren't set (e.g. running outside roll loop).
+        self._emit_usage_event(ev, dur_ms, cost_usd)
+
+    def _emit_usage_event(self, result_ev, dur_ms, cost_usd):
+        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")
+        if not (slug and cycle):
+            return
+        # Pull usage off the result event itself if present, otherwise off
+        # the most recent assistant turn we observed.
+        usage = (result_ev.get("usage") or self._last_usage or {})
+        model = result_ev.get("model") or self._last_model or ""
+        payload = {
+            "model": model,
+            "input_tokens":            int(usage.get("input_tokens") or 0),
+            "output_tokens":           int(usage.get("output_tokens") or 0),
+            "cache_creation_tokens":   int(usage.get("cache_creation_input_tokens") or 0),
+            "cache_read_tokens":       int(usage.get("cache_read_input_tokens") or 0),
+            "cost_reported_usd":       float(cost_usd or 0),
+            "duration_ms":             int(dur_ms or 0),
+        }
+        evfile = os.path.join(shared, "loop", f"events-{slug}.ndjson")
+        line = json.dumps({
+            "ts":      datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "stage":   "usage",
+            "label":   cycle,
+            "detail":  payload,
+            "outcome": "ok",
+        }) + "\n"
+        try:
+            os.makedirs(os.path.dirname(evfile), exist_ok=True)
+            with open(evfile, "a") as f:
+                f.write(line)
+        except Exception:
+            pass  # best-effort; never break tmux output
+
 
 def main():
     fmt = LoopFmt()

package/lib/model_prices.py

@@ -0,0 +1,64 @@
+"""
+model_prices — list-price table for Anthropic Claude API models.
+
+Pricing is per million tokens (MTok), USD. These are the public list rates;
+discounts (Pro subscription, prepay credits, etc.) are intentionally not
+modeled — IDEA-025 is about cross-account / cross-project comparable cost.
+
+Update this table when Anthropic changes pricing. Unknown models fall back
+to sonnet rates with a stderr warning so dashboards don't blank out.
+"""
+
+import sys
+from typing import Dict, Optional
+
+# Rates per million tokens (USD).
+PRICES: Dict[str, Dict[str, float]] = {
+    # Claude 4.x family (current as of 2026-05).
+    "claude-opus-4-7":    {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
+    "claude-opus-4-6":    {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
+    "claude-sonnet-4-6":  {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-sonnet-4":    {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-haiku-4-5":   {"in":  1.00, "out":  5.00, "cache_create":  1.25, "cache_read": 0.10},
+    # Older fallbacks
+    "claude-3-5-sonnet":  {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+}
+
+DEFAULT = "claude-sonnet-4-6"
+_warned: set = set()
+
+def _resolve(model: Optional[str]) -> Dict[str, float]:
+    if not model:
+        return PRICES[DEFAULT]
+    # Strip date suffixes like '-20251001' or '[1m]' context tags.
+    base = model.split("[")[0].rstrip("0123456789-")
+    # Try a prefix match against the table; longest match wins.
+    candidates = [k for k in PRICES if model.startswith(k) or base.startswith(k)]
+    if candidates:
+        return PRICES[max(candidates, key=len)]
+    if model not in _warned:
+        _warned.add(model)
+        print(f"[model_prices] warn: unknown model {model!r}, falling back to {DEFAULT}",
+              file=sys.stderr)
+    return PRICES[DEFAULT]
+
+def compute_list_cost(model: Optional[str],
+                      *,
+                      input_tokens: int = 0,
+                      output_tokens: int = 0,
+                      cache_creation_tokens: int = 0,
+                      cache_read_tokens: int = 0) -> float:
+    """Return USD cost at list price for one cycle's token usage."""
+    p = _resolve(model)
+    total = (input_tokens         * p["in"]
+           + output_tokens        * p["out"]
+           + cache_creation_tokens * p["cache_create"]
+           + cache_read_tokens    * p["cache_read"]) / 1_000_000
+    return round(total, 4)
+
+def total_tokens(*,
+                 input_tokens: int = 0,
+                 output_tokens: int = 0,
+                 cache_creation_tokens: int = 0,
+                 cache_read_tokens: int = 0) -> int:
+    return int(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens)