@seanyao/roll 2026.523.1 → 2026.523.2

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.523.1"
+VERSION="2026.523.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -21,6 +21,10 @@ SCRIPT_DIR="$(cd "$(dirname "$_source")" && pwd)"
 ROLL_PKG_DIR="$(dirname "$SCRIPT_DIR")"
 ROLL_PKG_CONVENTIONS="${ROLL_PKG_DIR}/conventions"
 
+# US-I18N-001: i18n engine (locale resolution + message catalog).
+# shellcheck source=../lib/i18n.sh
+[[ -f "${ROLL_PKG_DIR}/lib/i18n.sh" ]] && source "${ROLL_PKG_DIR}/lib/i18n.sh"
+
 # Colors
 RED=$'\033[0;31m'
 GREEN=$'\033[0;32m'
@@ -3620,6 +3624,107 @@ EOF
   return "$rc"
 }
 
+# ─── cmd_prices (US-VIEW-013) ─────────────────────────────────────────────────
+# `roll prices show`     — print the current price snapshot table.
+# `roll prices refresh`  — fetch live pricing docs, diff vs latest snapshot,
+#                          write a new snapshot when rates have changed.
+_prices_help() {
+  cat <<'EOF'
+Usage: roll prices <subcommand> [--url URL]
+      roll prices <子命令> [--url 网址]
+
+Subcommands:
+  show     Print the current price snapshot table.
+           显示当前价格快照表。
+  refresh  Fetch the official pricing docs, diff against the latest snapshot,
+           and write a new snapshot only when rates have changed.
+           拉取官方价格文档与最新快照对比，有变化才落新快照。
+EOF
+}
+
+cmd_prices_show() {
+  local lib_dir="${ROLL_PKG_DIR}/lib"
+  python3 - "$lib_dir" <<'PY'
+import json, os, sys
+lib_dir = sys.argv[1]
+sys.path.insert(0, lib_dir)
+import model_prices as mp
+
+version, effective_at, source_url = mp.snapshot_meta()
+print(f"price snapshot  价格快照")
+print(f"  version        {version}")
+print(f"  effective_at   {effective_at}")
+print(f"  source         {source_url}")
+print(f"  default_model  {mp.DEFAULT}")
+print()
+print(f"  {'model':<22}{'in':>8}{'out':>8}{'cw':>8}{'cr':>8}")
+for model in sorted(mp.PRICES):
+    p = mp.PRICES[model]
+    print(f"  {model:<22}{p['in']:>8.2f}{p['out']:>8.2f}{p['cache_create']:>8.2f}{p['cache_read']:>8.2f}")
+print()
+print("rates per million tokens, USD  单位为每百万 token 美元")
+PY
+}
+
+cmd_prices_refresh() {
+  local url=""
+  while (( $# > 0 )); do
+    case "$1" in
+      --url) url="$2"; shift 2 ;;
+      *)     err "Unknown flag: $1  未知参数: $1"; return 1 ;;
+    esac
+  done
+  local lib_dir="${ROLL_PKG_DIR}/lib"
+  python3 - "$lib_dir" "$url" <<'PY'
+import os, sys
+lib_dir = sys.argv[1]
+override_url = sys.argv[2] if len(sys.argv) > 2 else ""
+sys.path.insert(0, lib_dir)
+import prices_fetcher as pf
+
+snapshot_dir = os.path.join(lib_dir, "prices")
+url = override_url or pf.DEFAULT_SOURCE_URL
+
+try:
+    action, changes = pf.refresh(snapshot_dir=snapshot_dir, url=url)
+except pf.FetchError as exc:
+    print(f"[roll] fetch failed: {exc}", file=sys.stderr)
+    print("[roll] keeping existing snapshot, no changes written  保留旧快照，未写入新文件",
+          file=sys.stderr)
+    sys.exit(2)
+except pf.ParseError as exc:
+    print(f"[roll] parse failed: {exc}", file=sys.stderr)
+    print("[roll] keeping existing snapshot, no changes written  保留旧快照，未写入新文件",
+          file=sys.stderr)
+    sys.exit(3)
+
+kind, _, _ = (action + "::").split(":", 2)
+if action == "unchanged":
+    print("[roll] up to date  价格快照已是最新")
+    sys.exit(0)
+if kind == "first":
+    print(f"[roll] baseline snapshot written  写入首份基线快照")
+elif kind == "written":
+    print(f"[roll] new snapshot written  写入新版价格快照")
+print(pf.format_diff(changes, colored=sys.stdout.isatty()))
+PY
+}
+
+cmd_prices() {
+  local subcmd="${1:-}"
+  shift || true
+  case "$subcmd" in
+    show)              cmd_prices_show "$@" ;;
+    refresh)           cmd_prices_refresh "$@" ;;
+    --help|-h|help|"") _prices_help ;;
+    *)
+      err "Unknown subcommand: ${subcmd}  未知子命令：${subcmd}"
+      _prices_help >&2
+      return 1
+      ;;
+  esac
+}
+
 cmd_slides() {
   local subcmd="${1:-}"
   shift || true
@@ -4085,8 +4190,39 @@ _loop_event() {
   esac
   mkdir -p "$(dirname "$evfile")"
 
-  # stdout: tab-separated for tmux display
-  printf '%s\t%s\t%s\t%s\t%s\n' "$ts" "$stage" "$label" "$detail" "$outcome"
+  # US-LOOP-007: human-friendly stdout for phase_* stages so tmux readers
+  # spot phase boundaries amid claude output. Other stages keep the legacy
+  # tab-separated format (consumers like tests grep on it).
+  case "$stage" in
+    phase_start)
+      local _emoji
+      case "$label" in
+        startup) _emoji="🚀" ;;
+        preflight) _emoji="🔍" ;;
+        worktree_setup) _emoji="🌳" ;;
+        claude_invoke) _emoji="🤖" ;;
+        publish_push) _emoji="📤" ;;
+        publish_wait_merge) _emoji="⏳" ;;
+        cleanup) _emoji="🧹" ;;
+        *) _emoji="▶" ;;
+      esac
+      printf '%s %-22s ─────────\n' "$_emoji" "$label"
+      ;;
+    phase_tick)
+      printf '   ⏱  %-20s ───── %s\n' "$label" "$detail"
+      ;;
+    phase_end)
+      local _mark
+      case "$outcome" in
+        fail) _mark="✗" ;;
+        *) _mark="✓" ;;
+      esac
+      printf '   %s %-20s ───── %s\n' "$_mark" "$label" "$detail"
+      ;;
+    *)
+      printf '%s\t%s\t%s\t%s\t%s\n' "$ts" "$stage" "$label" "$detail" "$outcome"
+      ;;
+  esac
 
   # JSON line appended to NDJSON file. FIX-067: drop the flock/lockf guard.
   # POSIX requires write() ≤ PIPE_BUF (≥512 bytes, 4 KiB on Linux/macOS) to
@@ -4321,9 +4457,47 @@ fi
 printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
 # FIX-038: background heartbeat writer — outer script uses this as primary liveness signal
 # 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.
 HEARTBEAT_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
+CURRENT_PHASE=""
+# bash 3.2 (macOS /bin/bash) lacks associative arrays — use namespaced
+# variables via 'printf -v' + indirect '\${!VAR}' expansion instead.
+# _PHASE_START_<name>  stores the unix-second start ts per phase
+# _PHASE_DUR_<name>    stores the computed duration in seconds per phase
+# _PHASE_NAMES_DONE    space-separated list of completed phase names, in order
+_PHASE_NAMES_DONE=""
+_phase_begin() {
+  local _name="\$1"
+  printf -v "_PHASE_START_\${_name}" '%s' "\$(date +%s)"
+  CURRENT_PHASE="\$_name"
+  _loop_event phase_start "\$_name" "" "" || true
+}
+_phase_end() {
+  local _name="\$1" _outcome="\${2:-ok}"
+  local _start_var="_PHASE_START_\${_name}"
+  local _start="\${!_start_var:-\$(date +%s)}"
+  local _dur=\$(( \$(date +%s) - _start ))
+  [ "\$_dur" -lt 0 ] && _dur=0
+  printf -v "_PHASE_DUR_\${_name}" '%s' "\$_dur"
+  case " \$_PHASE_NAMES_DONE " in *" \$_name "*) ;; *) _PHASE_NAMES_DONE="\${_PHASE_NAMES_DONE} \$_name" ;; esac
+  CURRENT_PHASE=""
+  _loop_event phase_end "\$_name" "\${_dur}s" "\$_outcome" || true
+}
 _heartbeat_writer() {
-  while true; do echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"; sleep 60; done
+  while true; do
+    echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"
+    if [ -n "\$CURRENT_PHASE" ]; then
+      local _start_var="_PHASE_START_\${CURRENT_PHASE}"
+      local _phase_start="\${!_start_var:-}"
+      if [ -n "\$_phase_start" ]; then
+        local _el=\$(( \$(date +%s) - _phase_start ))
+        _loop_event phase_tick "\$CURRENT_PHASE" "\${_el}s elapsed" "" 2>/dev/null || true
+      fi
+    fi
+    sleep 60
+  done
 }
 _heartbeat_writer &
 _HEARTBEAT_PID=\$!
@@ -4343,8 +4517,65 @@ trap '_on_sigterm' TERM
 # US-LOOP-005: idempotent runs.jsonl writer shared by normal exit, timeout
 # trap, and worktree-setup-failure early exit. Guards on jq + run_id dedupe so
 # multiple callers in the same cycle are safe.
+# US-LOOP-008: build a JSON object {"<phase>": <duration_sec>, ...} from
+# the ordered list of completed phases. Returns "{}" if no phases ran.
+_phases_to_json() {
+  command -v jq >/dev/null 2>&1 || { printf '{}'; return 0; }
+  local _name _var _dur _args="" _filter="{}"
+  local _first=1
+  for _name in \$_PHASE_NAMES_DONE; do
+    [ -z "\$_name" ] && continue
+    _var="_PHASE_DUR_\${_name}"
+    _dur="\${!_var:-0}"
+    if [ "\$_first" -eq 1 ]; then
+      _filter="{\\"\${_name}\\": \\\$d_\${_name}}"
+      _first=0
+    else
+      _filter="\${_filter} + {\\"\${_name}\\": \\\$d_\${_name}}"
+    fi
+    _args="\${_args} --argjson d_\${_name} \${_dur}"
+  done
+  if [ "\$_first" -eq 1 ]; then
+    printf '{}'
+  else
+    eval "jq -nc \${_args} '\${_filter}'" 2>/dev/null || printf '{}'
+  fi
+}
+
+# US-LOOP-008: print phase breakdown panel sorted by duration desc.
+# Idle/failed/aborted cycles only list phases that actually entered — no
+# placeholder rows. Panel is best-effort (skips silently if no phases).
+_print_phase_breakdown() {
+  [ -n "\$_PHASE_NAMES_DONE" ] || return 0
+  local _name _var _dur _total=0 _rows=""
+  for _name in \$_PHASE_NAMES_DONE; do
+    [ -z "\$_name" ] && continue
+    _var="_PHASE_DUR_\${_name}"
+    _dur="\${!_var:-0}"
+    _total=\$(( _total + _dur ))
+    _rows="\${_rows}\${_dur} \${_name}\n"
+  done
+  [ "\$_total" -le 0 ] && _total=1
+  printf '\\n─── Cycle %s Phase Breakdown ───\\n' "\${CYCLE_ID:-unknown}"
+  printf '%b' "\$_rows" | sort -rn | while read -r _d _n; do
+    [ -z "\$_n" ] && continue
+    local _pct=\$(( (_d * 1000) / _total ))
+    local _pct_str
+    _pct_str=\$(printf '%d.%d%%' \$(( _pct / 10 )) \$(( _pct % 10 )))
+    local _bar="" _bar_len=\$(( (_d * 20) / _total ))
+    [ "\$_bar_len" -gt 0 ] && _bar=\$(printf '█%.0s' \$(seq 1 \$_bar_len))
+    printf '  %-22s %6ds  (%6s)  %s\\n' "\$_n" "\$_d" "\$_pct_str" "\$_bar"
+  done
+  printf '  %s\\n' "──────────────────────────────────────"
+  printf '  %-22s %6ds\\n\\n' "Total" "\$_total"
+}
+
 _runs_append() {
   local _status="\$1"; local _tcr="\${2:-0}"; local _built="\${3:-[]}"
+  # bash parameter expansion \${4:-{}} stops at the first \} so the default
+  # leaks a trailing \} into a real 4th arg ("{...}}"). Test explicit empty.
+  local _phases_json="\${4:-}"
+  [ -z "\$_phases_json" ] && _phases_json="{}"
   local _runs_dst="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/runs.jsonl"
   command -v jq >/dev/null 2>&1 || return 0
   local _cid="\${CYCLE_ID:-pre-cycle-\$\$}"
@@ -4366,14 +4597,21 @@ _runs_append() {
     --argjson alerts '[]' \\
     --argjson tcr_count "\$_tcr" \\
     --argjson duration_sec "\$_dur" \\
+    --argjson phases "\$_phases_json" \\
     '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
       cycle_id:\$cycle_id,
       built:\$built, skipped:\$skipped, alerts:\$alerts,
-      tcr_count:\$tcr_count, duration_sec:\$duration_sec}' \\
+      tcr_count:\$tcr_count, duration_sec:\$duration_sec, phases:\$phases}' \\
     >> "\$_runs_dst" 2>/dev/null || true
 }
 _inner_cleanup() {
   local _rc=\$?
+  # US-LOOP-007: close any CURRENT_PHASE that wasn't ended explicitly
+  # (sigterm / set -e fire / aborted exit paths). Marks as fail so the
+  # breakdown panel shows where we died.
+  if [ -n "\${CURRENT_PHASE:-}" ]; then
+    _phase_end "\$CURRENT_PHASE" fail 2>/dev/null || true
+  fi
   # Kill heartbeat + every remaining background job (watchdog, orphan
   # loop-fmt.py, publish subshells) — bash's foreground 'wait' for the
   # pipe has already returned by the time the EXIT trap runs.
@@ -4385,7 +4623,8 @@ _inner_cleanup() {
     # US-LOOP-005 T9: timeout path must also write runs.jsonl row so dashboard
     # has a terminal record (cycle_end alone is insufficient — runs.jsonl is
     # the canonical history feed for 'roll loop runs').
-    _runs_append "failed" 0 "[]" 2>/dev/null || true
+    _phases_t=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_t" ] && _phases_t='{}'
+_runs_append "failed" 0 "[]" "\$_phases_t" 2>/dev/null || true
     _worktree_alert "cycle \${CYCLE_ID:-unknown}: \${LOOP_CYCLE_TIMEOUT_SEC}s timeout — claude/python killed; in-progress story marked Blocked" 2>/dev/null || true
   fi
   # FIX-086: aborted-path orphan safety net. When the inner script is killed
@@ -4430,7 +4669,8 @@ _inner_cleanup() {
         _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "done" 2>/dev/null || true
         _CYCLE_END_WRITTEN=1
         # FIX-099: pass real tcr_count + built[] instead of 0/"[]"
-        _runs_append "done" "\${_orphan_tcr}" "\${_orphan_built}" 2>/dev/null || true
+        _phases_t=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_t" ] && _phases_t='{}'
+        _runs_append "done" "\${_orphan_tcr}" "\${_orphan_built}" "\$_phases_t" 2>/dev/null || true
         # FIX-099: three-field ALERT so callers can distinguish recovered orphan
         # from a cycle's normally-picked story (was: "FIX-091 published as PR"
         # which leaked a hardcoded string regardless of what was actually built).
@@ -4443,7 +4683,8 @@ _inner_cleanup() {
           _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "orphan" 2>/dev/null || true
           _CYCLE_END_WRITTEN=1
           # FIX-099: pass real tcr_count + built[] for the orphan-tag path too
-          _runs_append "orphan" "\${_orphan_tcr}" "\${_orphan_built}" 2>/dev/null || true
+          _phases_t=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_t" ] && _phases_t='{}'
+          _runs_append "orphan" "\${_orphan_tcr}" "\${_orphan_built}" "\$_phases_t" 2>/dev/null || true
           _worktree_alert "cycle \${CYCLE_ID}: recovered_from_orphan=yes; tcr_commits=\${_orphan_tcr}; stories=\${_orphan_built}; FIX-086 pushed orphan tag \${_orphan_tag}" 2>/dev/null || true
         fi
       fi
@@ -4455,7 +4696,8 @@ _inner_cleanup() {
   # "still running" until the next successful cycle rolls past it.
   if [ "\${_CYCLE_END_WRITTEN:-0}" -eq 0 ] && [ -n "\${CYCLE_ID:-}" ]; then
     _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "aborted" 2>/dev/null || true
-    _runs_append "aborted" 0 "[]" 2>/dev/null || true
+    _phases_t=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_t" ] && _phases_t='{}'
+    _runs_append "aborted" 0 "[]" "\$_phases_t" 2>/dev/null || true
   fi
   rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
   exit "\$_rc"
@@ -4494,6 +4736,11 @@ CYCLE_START=\$(date +%s)
 WT="\$(_worktree_path "${slug}" "cycle-\${CYCLE_ID}")"
 BRANCH="loop/cycle-\${CYCLE_ID}"
 _USE_WORKTREE=0
+# US-LOOP-007: startup phase covers env / lock / heartbeat setup. End it now
+# that cycle vars are bound and we're about to do real work.
+_phase_begin startup
+_phase_end startup ok
+_phase_begin preflight
 cd "${project_path}" 2>/dev/null || true
 # FIX-104: GC stale merged temp branches at cycle entry — before worktree setup
 # and before any early-exit gate (pre-run abort, CI red precheck). The post-claude
@@ -4536,6 +4783,8 @@ done
 # US-AUTO-038: snapshot orphan claude/* branches before claude runs so the
 # post-claude cleanup can diff and delete only this session's additions.
 CLAUDE_BRANCH_SNAPSHOT="\$(_claude_remote_snapshot "${project_path}")"
+_phase_end preflight ok
+_phase_begin worktree_setup
 if _worktree_fetch_origin main \\
    && _worktree_create "\$WT" "\$BRANCH" "origin/main"; then
   _USE_WORKTREE=1
@@ -4547,16 +4796,19 @@ 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
+  _phase_end worktree_setup ok
 else
   # P3 fix: skip the cycle entirely when worktree isolation fails.
   # --dangerously-skip-permissions is only safe paired with worktree isolation;
   # falling back to the main tree without isolation is unacceptable.
   _worktree_alert "cycle \${CYCLE_ID}: worktree setup failed — skipping cycle to avoid running without isolation"
   echo "[loop] cycle \${CYCLE_ID}: worktree setup failed; skipping cycle (no isolation)"
+  _phase_end worktree_setup fail
   # US-LOOP-005 T10: worktree-setup-failed path leaves no commits and never
   # emits cycle_start, but dashboard still needs a runs.jsonl row marking the
   # cycle as failed (otherwise the scheduled tick appears to have vanished).
-  _runs_append "failed" 0 "[]" 2>/dev/null || true
+  _phases_t=\$(_phases_to_json 2>/dev/null); [ -z "\$_phases_t" ] && _phases_t='{}'
+_runs_append "failed" 0 "[]" "\$_phases_t" 2>/dev/null || true
   exit 0
 fi
 
@@ -4568,6 +4820,7 @@ FMT="${fmt_script}"
 export LOOP_PROJECT_SLUG="${slug}"
 export LOOP_CYCLE_ID="\${CYCLE_ID}"
 export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
+_phase_begin claude_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
@@ -4605,6 +4858,12 @@ for _attempt in 1 2 3; do
   fi
 done
 
+if [ "\$_CYCLE_TIMED_OUT" -eq 1 ] || [ "\$_exit" -ne 0 ]; then
+  _phase_end claude_invoke fail
+else
+  _phase_end claude_invoke ok
+fi
+
 # FIX-057: timed out — skip publish; EXIT trap writes cycle_end blocked + ALERT.
 if [ "\$_CYCLE_TIMED_OUT" -eq 1 ]; then
   echo "[loop] cycle \${CYCLE_ID}: \${LOOP_CYCLE_TIMEOUT_SEC}s timeout — aborting cycle (worktree preserved at \$WT)"
@@ -4653,6 +4912,7 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
     else
       _is_doc_only=0
       ( cd "\$WT" && _loop_is_doc_only_change ) && _is_doc_only=1
+      _phase_begin publish_push
       if [ "\$_is_doc_only" -eq 1 ]; then
         ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
       else
@@ -4660,18 +4920,25 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
       fi
       _publish_status=\$?
       if [ "\$_publish_status" -eq 0 ]; then
+        _phase_end publish_push ok
         # FIX-047: CI green ≠ delivered — wait for actual PR merge before cycle complete
         if [ "\$_is_doc_only" -eq 0 ]; then
+          _phase_begin publish_wait_merge
           if ! ( cd "\$WT" && _loop_wait_pr_merge "\$BRANCH" ); then
             _worktree_alert "cycle \${CYCLE_ID}: FIX-047: PR not merged within timeout — code may not be in main (BRANCH=\${BRANCH})"
+            _phase_end publish_wait_merge fail
+          else
+            _phase_end publish_wait_merge ok
           fi
         fi
+        _phase_begin cleanup
         # US-VIEW-011: emit terminal PR state (merged/closed/open) before cycle_end
         # so dashboard renders #NN ✓/↩/… correctly. Must run while branch ref
         # is still resolvable on remote — gh pr view <branch> needs the head ref.
         _loop_emit_pr_final "\$BRANCH" 2>/dev/null || true
         _worktree_cleanup "\$WT" "\$BRANCH"
         _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
+        _phase_end cleanup ok
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
       elif [ "\$_publish_status" -eq 2 ]; then
         if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
@@ -4726,11 +4993,15 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
   fi
 fi
 
+# US-LOOP-008: cycle Phase Breakdown panel — printed to stdout (tmux readers)
+# before runs.jsonl is appended, so the user sees timings even if jq is missing.
+_print_phase_breakdown 2>/dev/null || true
+_phases_for_runs=\$(_phases_to_json 2>/dev/null || echo '{}')
 # FIX-044 / Step 5: Write loop cycle run summary to runs.jsonl
 # Deterministic — runs in shell regardless of whether agent executes SKILL.md Step 5.
 # US-LOOP-005: now routed through _runs_append so timeout/worktree-setup-fail
 # share the same write logic. _runs_append is idempotent on run_id.
-_runs_append "\$_cycle_status" "\$_cycle_tcr" "\$_cycle_built" 2>/dev/null || true
+_runs_append "\$_cycle_status" "\$_cycle_tcr" "\$_cycle_built" "\$_phases_for_runs" 2>/dev/null || true
 INNER
   chmod +x "$inner_path"
 
@@ -5453,6 +5724,71 @@ _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,
+# publish_push→publish, worktree_setup→worktree; others unchanged.
+_loop_runs_slowest_phase() {
+  local line="$1"
+  command -v jq >/dev/null 2>&1 || return 0
+  local total max_name max_dur
+  total=$(jq -r '(.phases // {}) | to_entries | map(.value) | add // 0' <<<"$line")
+  [ -z "$total" ] || [ "$total" = "0" ] || [ "$total" = "null" ] && return 0
+  max_name=$(jq -r '(.phases // {}) | to_entries | sort_by(-.value) | .[0].key // ""' <<<"$line")
+  max_dur=$(jq -r '(.phases // {}) | to_entries | sort_by(-.value) | .[0].value // 0' <<<"$line")
+  [ -z "$max_name" ] && return 0
+  local abbr="$max_name"
+  case "$max_name" in
+    claude_invoke) abbr="claude" ;;
+    publish_wait_merge) abbr="pr-wait" ;;
+    publish_push) abbr="publish" ;;
+    worktree_setup) abbr="worktree" ;;
+  esac
+  local pct=$(( (max_dur * 100 + total / 2) / total ))
+  printf '%s %d%%' "$abbr" "$pct"
+}
+
+# US-VIEW-019: render the full Phase Breakdown panel for a cycle by re-using
+# the same shape that the inner runner script prints. Reads runs.jsonl,
+# locates the row by cycle_id, prints sorted-desc table.
+_loop_runs_detail() {
+  local cycle_id="$1"
+  command -v jq >/dev/null 2>&1 || { err "jq required for --detail"; return 1; }
+  if [[ ! -f "$_LOOP_RUNS" ]]; then
+    echo "No runs.jsonl yet  尚无运行记录"
+    return 0
+  fi
+  local row
+  row=$(jq -c --arg cid "$cycle_id" 'select(.cycle_id == $cid)' "$_LOOP_RUNS" | head -1)
+  if [[ -z "$row" ]]; then
+    echo "Cycle not found: $cycle_id  未找到对应 cycle"
+    return 1
+  fi
+  local has_phases
+  has_phases=$(jq -r '(.phases // {}) | length' <<<"$row")
+  if [[ "$has_phases" == "0" ]]; then
+    echo "Cycle $cycle_id has no phases data (pre-US-LOOP-008)  无 phase 数据"
+    return 0
+  fi
+  echo ""
+  echo "─── Cycle $cycle_id Phase Breakdown ───"
+  local total
+  total=$(jq -r '(.phases // {}) | to_entries | map(.value) | add // 0' <<<"$row")
+  [ "$total" -le 0 ] && total=1
+  jq -r '(.phases // {}) | to_entries | sort_by(-.value) | .[] | "\(.value) \(.key)"' <<<"$row" \
+    | while read -r dur name; do
+        [[ -z "$name" ]] && continue
+        local pct=$(( (dur * 1000) / total ))
+        local pct_str
+        pct_str=$(printf '%d.%d%%' $((pct / 10)) $((pct % 10)))
+        local bar="" bar_len=$(( (dur * 20) / total ))
+        [ "$bar_len" -gt 0 ] && bar=$(printf '█%.0s' $(seq 1 "$bar_len"))
+        printf '  %-22s %6ds  (%6s)  %s\n' "$name" "$dur" "$pct_str" "$bar"
+      done
+  echo "  ──────────────────────────────────────"
+  printf '  %-22s %6ds\n\n' "Total" "$total"
+}
+
 _loop_runs_dur() {
   local s="${1:-0}"
   if [[ "$s" -lt 60 ]]; then printf "%ds" "$s"
@@ -5497,8 +5833,12 @@ _loop_runs_format_line() {
       local skipped_note=""
       [[ "$skipped_count" -gt 0 ]] && skipped_note=", ${skipped_count} skipped"
       local items_word; [[ "$built_count" -eq 1 ]] && items_word="item" || items_word="items"
-      printf "  %s  %s✅ built %d %s (%d tcr%s, %s)\n" \
-        "$hhmm" "$prefix" "$built_count" "$items_word" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")"
+      # US-VIEW-019: append slowest phase summary when phases data is present.
+      local slowest_note=""
+      local slowest_str; slowest_str=$(_loop_runs_slowest_phase "$line")
+      [[ -n "$slowest_str" ]] && slowest_note=", slowest=${slowest_str}"
+      printf "  %s  %s✅ built %d %s (%d tcr%s, %s%s)\n" \
+        "$hhmm" "$prefix" "$built_count" "$items_word" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")" "$slowest_note"
       local id desc
       while IFS= read -r id; do
         [[ -z "$id" ]] && continue
@@ -5535,15 +5875,23 @@ _loop_runs_format_line() {
 
 # `roll loop runs [N] [--all]` — show recent loop iteration summaries.
 _loop_runs() {
-  local n=10 all_flag=false
+  local n=10 all_flag=false detail_cycle=""
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --all) all_flag=true; shift ;;
+      --detail) detail_cycle="${2:-}"; shift 2 ;;
+      --detail=*) detail_cycle="${1#--detail=}"; shift ;;
       [0-9]*) n="$1"; shift ;;
       *) shift ;;
     esac
   done
 
+  # US-VIEW-019: --detail <cycle_id> prints the Phase Breakdown panel.
+  if [[ -n "$detail_cycle" ]]; then
+    _loop_runs_detail "$detail_cycle"
+    return $?
+  fi
+
   # FIX-060: refresh merged status before reading, so paused-window merges show up.
   _loop_backfill_merged >/dev/null 2>&1 || true
 
@@ -6872,6 +7220,9 @@ _loop_wait_pr_merge() {
   local elapsed=0
   local slug; _gh_resolve slug || return 0
   while (( elapsed < timeout )); do
+    # US-LOOP-007: emit phase_tick at the top of each poll iteration so the
+    # tmux reader sees "still waiting" every 30s during merge wait.
+    (( elapsed > 0 )) && _loop_event phase_tick publish_wait_merge "${elapsed}s elapsed" "" 2>/dev/null || true
     local state; state=$(gh -R "$slug" pr view "$branch" --json state -q .state 2>/dev/null || echo "UNKNOWN")
     case "$state" in
       MERGED) return 0 ;;
@@ -7323,6 +7674,57 @@ cmd_alert() {
   esac
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# LANG — switch / inspect Roll's UI language (US-I18N-001)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_lang() {
+  local arg="${1:-}"
+
+  case "$arg" in
+    "")
+      unset ROLL_LANG_RESOLVED
+      local current src
+      current=$(_i18n_resolve_lang)
+      if [[ -n "${ROLL_LANG:-}" ]]; then
+        src="ROLL_LANG env"
+      elif [[ -f "$ROLL_CONFIG" ]] && grep -qE '^lang:' "$ROLL_CONFIG"; then
+        src="config (${ROLL_CONFIG})"
+      elif [[ -n "${LC_ALL:-}" || -n "${LANG:-}" ]]; then
+        src="LC_ALL/LANG"
+      else
+        src="default"
+      fi
+      echo "current: ${current}, source: ${src}"
+      ;;
+    zh|en)
+      mkdir -p "$(dirname "$ROLL_CONFIG")"
+      [[ -f "$ROLL_CONFIG" ]] || : > "$ROLL_CONFIG"
+      local tmp; tmp=$(mktemp)
+      grep -vE '^lang:' "$ROLL_CONFIG" > "$tmp" || true
+      printf 'lang: %s\n' "$arg" >> "$tmp"
+      mv "$tmp" "$ROLL_CONFIG"
+      unset ROLL_LANG_RESOLVED
+      ok "Language set to ${arg}  语言已设置为 ${arg}"
+      ;;
+    --reset)
+      if [[ -f "$ROLL_CONFIG" ]]; then
+        local tmp; tmp=$(mktemp)
+        grep -vE '^lang:' "$ROLL_CONFIG" > "$tmp" || true
+        mv "$tmp" "$ROLL_CONFIG"
+      fi
+      unset ROLL_LANG_RESOLVED
+      ok "Language preference cleared (will follow locale)  语言偏好已清除（跟随系统 locale）"
+      ;;
+    *)
+      err "Unknown language: ${arg}  未知语言: ${arg}"
+      echo "  Valid values: zh, en, --reset"
+      echo "  可选值: zh, en, --reset"
+      return 1
+      ;;
+  esac
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 
 cmd_ci() {
@@ -8117,11 +8519,13 @@ main() {
     brief)         cmd_brief "$@" ;;
     backlog)       cmd_backlog "$@" ;;
     alert)         cmd_alert "$@" ;;
+    lang)          cmd_lang "$@" ;;
     agent)         cmd_agent "$@" ;;
     ci)            cmd_ci "$@" ;;
     doctor)        cmd_doctor "$@" ;;
     review-pr)     cmd_review_pr "$@" ;;
     slides)        cmd_slides "$@" ;;
+    prices)        cmd_prices "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) _help "$@" ;;
     "") [[ -f ".roll/backlog.md" ]] && _home || { _help; _show_changelog; } ;;