@seanyao/roll 2026.522.2 → 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.522.2"
+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'
@@ -322,16 +326,25 @@ safe_copy() {
     if diff -q "$src" "$dst" &>/dev/null; then
       return  # identical, skip silently
     fi
+    # Non-interactive (stdin is not a terminal): silently overwrite.
+    # _run_setup_step / cmd_update redirect stdin to /dev/null and all
+    # stdout/stderr is suppressed — prompting here would either hang on a
+    # hidden read or silently default to overwrite. Be explicit.
+    if [[ ! -t 0 ]]; then
+      cp "$src" "$dst"
+      ok "Wrote: ${dst/#$HOME/~}  已写入: ${dst/#$HOME/~}"
+      return
+    fi
     echo ""
     warn "File exists and differs: ${dst/#$HOME/~}  文件已存在且内容不同: ${dst/#$HOME/~}"
     echo -e "  ${BOLD}Overwrite?${NC} [Y/n/d(iff)] "
-    read -r answer
+    read -r answer || answer="Y"
     case "$answer" in
       d|D|diff)
         diff --color=auto "$dst" "$src" || true
         echo ""
         echo -e "  ${BOLD}Overwrite?${NC} [Y/n] "
-        read -r answer2
+        read -r answer2 || answer2="Y"
         [[ "$answer2" =~ ^[Nn]$ ]] && { info "Skipped: ${dst/#$HOME/\~}  已跳过: ${dst/#$HOME/\~}"; return; }
         ;;
       n|N) info "Skipped: ${dst/#$HOME/~}  已跳过: ${dst/#$HOME/~}"; return ;;
@@ -726,7 +739,7 @@ _run_setup_step() {
   local watch="$1"; shift
   local before after
   before=$(_setup_snapshot "$watch")
-  if "$@" >/dev/null 2>&1; then
+  if "$@" </dev/null >/dev/null 2>&1; then
     after=$(_setup_snapshot "$watch")
     if [[ "$before" == "$after" ]]; then
       _ROLL_SETUP_STATE="unchanged"
@@ -883,6 +896,40 @@ HINT
 # in (or opted out) don't get spammed each upgrade.
 cmd_doctor() {
   _doctor_pr_section
+  _doctor_launchd_stale_section
+}
+
+# FIX-097: scan ${_LAUNCHD_DIR}/com.roll.*.plist for entries whose
+# WorkingDirectory no longer exists on disk. These are the ghost agents left
+# behind when a user manually reproduces a bug under /private/tmp/ or
+# /var/folders/ — the auto-sandbox redirects plist writes but launchctl
+# bootstrap (before this fix) registered them anyway. Print labels +
+# cleanup hint; never auto-delete (host launchctl state is user-owned).
+_doctor_launchd_stale_section() {
+  [[ "$(uname)" == "Darwin" ]] || return 0
+  local dir="${_LAUNCHD_DIR:-${HOME}/Library/LaunchAgents}"
+  [[ -d "$dir" ]] || return 0
+
+  local found=0 plist label wd
+  for plist in "$dir"/com.roll.*.plist; do
+    [[ -e "$plist" ]] || continue
+    wd=$(awk '
+      /<key>WorkingDirectory<\/key>/ { getline; gsub(/.*<string>|<\/string>.*/, ""); print; exit }
+    ' "$plist" 2>/dev/null)
+    [[ -n "$wd" ]] || continue
+    [[ -d "$wd" ]] && continue
+    if [[ "$found" -eq 0 ]]; then
+      echo ""
+      echo "Stale launchd plists  无效的 launchd 服务"
+      echo ""
+      found=1
+    fi
+    label=$(basename "$plist" .plist)
+    echo "  ⚠ ${label}"
+    echo "    WorkingDirectory missing: ${wd}"
+    echo "    路径已失效，可清理: launchctl bootout gui/$(id -u)/${label}; rm '${plist}'"
+  done
+  return 0
 }
 
 _doctor_pr_section() {
@@ -1904,7 +1951,7 @@ PY
   fi
   if [ "${#plists[@]}" -gt 0 ]; then
     for item in "${plists[@]}"; do
-      launchctl unload -w "$HOME/Library/LaunchAgents/$item" 2>/dev/null && echo "    unloaded     $item"
+      _launchctl_safe unload -w "$HOME/Library/LaunchAgents/$item" 2>/dev/null && echo "    unloaded     $item"
       rm -f "$HOME/Library/LaunchAgents/$item" 2>/dev/null
     done
   fi
@@ -3577,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
@@ -3892,7 +4040,7 @@ PYEOF
 
   local old_plist=~/Library/LaunchAgents/com.roll.loop.${old_slug}.plist
   if [[ -f "$old_plist" ]]; then
-    launchctl unload "$old_plist" 2>/dev/null || true
+    _launchctl_safe unload "$old_plist" 2>/dev/null || true
     rm -f "$old_plist"
   fi
 
@@ -3969,6 +4117,13 @@ if [ -z "${_LAUNCHD_DIR:-}" ]; then
         _LAUNCHD_DIR="${_SHARED_ROOT}/LaunchAgents"
         mkdir -p "$_LAUNCHD_DIR"
         export _LAUNCHD_DIR
+        # FIX-097: same trigger that sandboxed the plist FILE path must also
+        # short-circuit every `launchctl bootstrap/load/unload/enable` against
+        # that path. Otherwise a user who reproduces a bug under /private/tmp/
+        # or /var/folders/ ends up with sandboxed plists registered in their
+        # real gui/<uid> domain — when the tmp dir is cleaned, the agents become
+        # ghosts that fire forever (the historical 23:13 CST Terminal popup).
+        export _LAUNCHD_SKIP_REGISTRY=1
       fi
       unset _roll_in_test_ctx _roll_caller
       ;;
@@ -4035,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
@@ -4095,6 +4281,25 @@ _launchd_label() {
   printf 'com.roll.%s.%s' "$service" "$(_project_slug "$project_path")"
 }
 
+# FIX-097: central skip predicate consulted by every launchctl invocation that
+# operates on a plist path Roll wrote. Returns 0 (skip) when either:
+#   - explicit: _LAUNCHD_SKIP_REGISTRY=1 was exported (tests, future opt-out)
+#   - implicit: _LAUNCHD_DIR is a child of _SHARED_ROOT (auto-sandbox active)
+# Returns 1 (do not skip) in production.
+#
+# History: FIX-090 introduced the same logic INSIDE _install_launchd_plists.
+# FIX-097 hoists it to a helper because the bootstrap call inside
+# _install_launchd_plists was not the only leak: _loop_on / _loop_off /
+# _loop_pause / _loop_resume each had bare `launchctl load/unload/enable`
+# calls that bypassed the gate.
+_launchd_should_skip_registry() {
+  [[ "${_LAUNCHD_SKIP_REGISTRY:-}" == "1" ]] && return 0
+  case "${_LAUNCHD_DIR:-}/" in
+    "${_SHARED_ROOT:-/nonexistent}"/*) return 0 ;;
+  esac
+  return 1
+}
+
 _launchd_plist_path() {
   local service="$1" project_path="$2"
   printf '%s/%s.plist' "$_LAUNCHD_DIR" "$(_launchd_label "$service" "$project_path")"
@@ -4123,16 +4328,34 @@ _write_launchd_plist() {
       ;;
   esac
 
-  local hour_xml=""
-  [[ -n "$hour" ]] && hour_xml="    <key>Hour</key>
-    <integer>${hour}</integer>
-"
-
   # FIX-050: bake PATH into the plist so launchd-spawned bash can find tmux,
   # claude, node, etc. The runner script also re-asserts PATH at runtime as
   # a second layer (covers stale plists where brew was installed after setup).
   local path_value; path_value=$(_detect_path_prepend)
 
+  # FIX-105: macOS 26.4 launchd silently refuses to fire StartCalendarInterval
+  # entries that contain BOTH Hour and Minute keys (verified: runs stays 0,
+  # last exit "never exited", no log output, the calendarinterval trigger is
+  # registered but never invoked by UserEventAgent-Aqua). Single-Minute (hourly)
+  # entries still fire fine. Workaround: when an Hour is provided (daily
+  # schedule), emit StartInterval=86400 (24h period) instead. First fire is
+  # bootstrap+24h rather than the exact requested wall-clock time — acceptable
+  # trade since the alternative was "never fires at all" (dream/brief broken
+  # for 4+ days). The Minute/Hour args are still kept in the function signature
+  # for callers that may want to filter at runtime, but they no longer steer
+  # the plist trigger format for daily schedules.
+  local schedule_xml
+  if [[ -n "$hour" ]]; then
+    schedule_xml="  <key>StartInterval</key>
+  <integer>86400</integer>"
+  else
+    schedule_xml="  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Minute</key>
+    <integer>${minute}</integer>
+  </dict>"
+  fi
+
   local content
   content="<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 <!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">
@@ -4151,11 +4374,7 @@ _write_launchd_plist() {
     <key>PATH</key>
     <string>${path_value}</string>
   </dict>
-  <key>StartCalendarInterval</key>
-  <dict>
-    <key>Minute</key>
-    <integer>${minute}</integer>
-${hour_xml}  </dict>
+${schedule_xml}
   <key>WorkingDirectory</key>
   <string>${project_path}</string>
 </dict>
@@ -4238,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=\$!
@@ -4260,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-\$\$}"
@@ -4283,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.
@@ -4302,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
@@ -4329,13 +4651,30 @@ _inner_cleanup() {
       # FIX-091: prefer a real PR so auto-merge lands the work; tag-only is the
       # last-resort because it requires manual cherry-pick. Emit cycle_end "done"
       # (canonical success status the dashboard recognizes) when PR publishes.
+      # FIX-099: compute tcr_count + built[] from the worktree (it's still alive
+      # at EXIT trap time) so runs.jsonl and ALERT carry truthful data.
+      _orphan_tcr=0
+      _orphan_built="[]"
+      if command -v jq >/dev/null 2>&1; then
+        _orphan_tcr=\$(cd "\$WT" && git log --oneline "origin/main..HEAD" 2>/dev/null | grep -c ' tcr:' || echo 0)
+        _orphan_built=\$(cd "\$WT" && git log --oneline "origin/main..HEAD" 2>/dev/null \
+          | grep ' tcr:' \
+          | grep -oE '\b(FIX|US|REFACTOR|CHORE)-[0-9]+\b' \
+          | sort -u \
+          | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
+      fi
       _slug=""
       if _gh_resolve _slug \\
          && ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" ) >/dev/null 2>&1; then
         _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "done" 2>/dev/null || true
         _CYCLE_END_WRITTEN=1
-        _runs_append "done" 0 "[]" 2>/dev/null || true
-        _worktree_alert "cycle \${CYCLE_ID}: aborted with \${_unpushed} commits; FIX-091 published as PR" 2>/dev/null || true
+        # FIX-099: pass real tcr_count + built[] instead of 0/"[]"
+        _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).
+        _worktree_alert "cycle \${CYCLE_ID}: recovered_from_orphan=yes; tcr_commits=\${_orphan_tcr}; stories=\${_orphan_built}; pr_branch=\${BRANCH:-unknown}" 2>/dev/null || true
       else
         _orphan_tag="loop-orphan-\${CYCLE_ID}"
         if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \\
@@ -4343,8 +4682,10 @@ _inner_cleanup() {
              && git push origin "\$_orphan_tag" 2>/dev/null ); then
           _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "orphan" 2>/dev/null || true
           _CYCLE_END_WRITTEN=1
-          _runs_append "orphan" 0 "[]" 2>/dev/null || true
-          _worktree_alert "cycle \${CYCLE_ID}: aborted with \${_unpushed} commits; FIX-086 pushed orphan tag \${_orphan_tag}" 2>/dev/null || true
+          # FIX-099: pass real tcr_count + built[] for the orphan-tag path too
+          _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
     fi
@@ -4355,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"
@@ -4394,7 +4736,16 @@ 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
+# call site doesn't cover those paths, so merged branches accumulated on origin.
+_loop_cleanup_stale_cycle_branches "${project_path}" || true
 # FIX-040: orphan worktree recovery — scan for worktrees left by previous failed
 # cycles (publish failed or inner script was SIGKILL'd). Attempt to publish each
 # before starting the new cycle. Glob is chronological via timestamp in name.
@@ -4432,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
@@ -4443,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
 
@@ -4464,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
@@ -4501,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)"
@@ -4549,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
@@ -4556,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
@@ -4622,14 +4993,15 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
   fi
 fi
 
-# US-AUTO-040: fallback GC — delete remote loop/cycle-* branches already merged to main.
-_loop_cleanup_stale_cycle_branches "${project_path}" || true
-
+# 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"
 
@@ -4760,17 +5132,67 @@ SCRIPT
 }
 
 _launchd_is_loaded() {
-  launchctl print-disabled "gui/$(id -u)" 2>/dev/null | grep -qF "\"$1\" => enabled"
+  # FIX-098: probe actual launchd registry via `launchctl print`, NOT
+  # `launchctl print-disabled`. The disabled-overrides DB only tracks
+  # labels explicitly enabled/disabled by the user — after `roll loop off`
+  # (bootout) + `roll update` the label stays absent from the overrides DB,
+  # so the old grep returned false-positive "loaded". `launchctl print`
+  # returns exit 0 only when the agent is actually registered in the current
+  # launchd session; non-zero means the label is unknown to launchd.
+  launchctl print "gui/$(id -u)/$1" >/dev/null 2>&1
+}
+
+# FIX-101 tripwire: refuse to mutate the host's launchd session when
+# _LAUNCHD_DIR has been sandboxed (i.e. is not the canonical
+# ${HOME}/Library/LaunchAgents). Tests that auto-sandbox _LAUNCHD_DIR for
+# isolation (FIX-087) may still forget to set _LAUNCHD_SKIP_REGISTRY=1 or
+# stub the launchctl binary; without this defensive layer the production
+# label's plist path can get overwritten with a transient sandbox path,
+# leading to launchd EX_CONFIG (exit 78) when the tmp dir is later cleaned
+# and the next scheduled fire can't find the plist. Read-only ops (print*,
+# list, version) are always allowed since they have no side effects.
+_launchctl_safe() {
+  # Read-only ops are always safe (no host launchd state mutation).
+  case "${1:-}" in
+    print|print-disabled|list|version|dumpstate|examine)
+      launchctl "$@"
+      return $?
+      ;;
+  esac
+  # If `launchctl` has been replaced by a function stub (typical in bats tests
+  # that want to assert against captured calls), pass through to the stub.
+  # Stubs by definition don't touch host launchd, so this is safe; and tests
+  # like `_install_launchd_plists: bootout targets gui/<uid>/<label>` rely on
+  # the literal call landing in their captured log.
+  if [[ "$(type -t launchctl 2>/dev/null)" == "function" ]]; then
+    launchctl "$@"
+    return $?
+  fi
+  # Real launchctl binary path: refuse to mutate when _LAUNCHD_DIR has been
+  # sandboxed (i.e. is not the canonical ${HOME}/Library/LaunchAgents). This
+  # is the FIX-101 defensive layer — when a test forgets to stub launchctl
+  # AND has _LAUNCHD_DIR sandboxed, prevent the call from reaching the host's
+  # production launchd and overwriting a live label's plist path.
+  local canonical="${HOME}/Library/LaunchAgents"
+  if [[ "${_LAUNCHD_DIR:-$canonical}" != "$canonical" ]]; then
+    return 0
+  fi
+  launchctl "$@"
 }
 
 _launchd_svc_state() {
+  # FIX-098: three-state classification:
+  #   enabled       — plist on disk AND registered in launchd
+  #   stale         — plist on disk BUT NOT registered in launchd
+  #   installed-off — kept for back-compat (maps to stale semantics)
+  #   not-installed — no plist
   local svc="$1" project_path="$2"
   local label; label=$(_launchd_label "$svc" "$project_path")
   local plist; plist=$(_launchd_plist_path "$svc" "$project_path")
   if _launchd_is_loaded "$label"; then
     echo "enabled"
   elif [[ -f "$plist" ]]; then
-    echo "installed-off"
+    echo "stale"
   else
     echo "not-installed"
   fi
@@ -4833,42 +5255,25 @@ _install_launchd_plists() {
     local after; after=$(cat "$plist")
     if [[ "$before" != "$after" ]]; then
       updated=$((updated + 1))
-      # FIX-090: gate launchctl writes so a sandboxed plist never gets
-      # registered into the user's REAL gui/<uid> domain. Without this,
-      # `launchctl bootstrap gui/<uid> <sandbox-plist>` outlives TEST_TMP
-      # cleanup as a zombie that either fails silently (EX_CONFIG) or, when
-      # the label collides with the dev's project slug, displaces the real
-      # registration and kills the autonomous loop. Two gate paths:
-      #   - explicit: integration_setup exports _LAUNCHD_SKIP_REGISTRY=1
-      #   - implicit: if _LAUNCHD_DIR was auto-sandboxed under _SHARED_ROOT
-      #     (FIX-087 inner-runner.sh re-source path) we infer skip — callers
-      #     that genuinely want the launchctl flow override _LAUNCHD_DIR to
-      #     a path outside _SHARED_ROOT (unit tests; production has no
-      #     _SHARED_ROOT match against ~/Library/LaunchAgents).
-      # See helpers.bash and tests/unit/launchd_sandbox.bats.
-      local _skip_reg="${_LAUNCHD_SKIP_REGISTRY:-}"
-      if [[ -z "$_skip_reg" ]]; then
-        case "${_LAUNCHD_DIR:-}/" in
-          "${_SHARED_ROOT:-/nonexistent}"/*) _skip_reg=1 ;;
-          *) _skip_reg=0 ;;
-        esac
-      fi
-      if [[ "$_skip_reg" != "1" ]]; then
+      # FIX-090/FIX-097: gate launchctl writes via central helper so a
+      # sandboxed plist never gets registered into the user's REAL gui/<uid>
+      # domain. See _launchd_should_skip_registry for the predicate rules.
+      if ! _launchd_should_skip_registry; then
         if _launchd_is_loaded "$label"; then
           # FIX-027: use bootout/bootstrap so we don't disturb the label's
           # enabled flag in the launchd overrides db (which legacy
           # unload/load no-`-w` wipes on macOS Sonoma+, causing
           # `roll loop status` to falsely report off after `roll update`).
           local uid; uid=$(id -u)
-          launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
-          launchctl bootstrap "gui/${uid}" "$plist" 2>/dev/null || true
+          _launchctl_safe bootout "gui/${uid}/${label}" 2>/dev/null || true
+          _launchctl_safe bootstrap "gui/${uid}" "$plist" 2>/dev/null || true
         elif [[ -z "$before" ]]; then
           # FIX-059: brand-new plist — macOS FSEvents auto-bootstraps any new
           # file dropped in ~/Library/LaunchAgents/, so projects never enabled
           # via 'roll loop on' would fire every hour. Immediately mark disabled
           # in the overrides db to block that auto-load.
           local uid; uid=$(id -u)
-          launchctl disable "gui/${uid}/${label}" 2>/dev/null || true
+          _launchctl_safe disable "gui/${uid}/${label}" 2>/dev/null || true
         fi
       fi
     fi
@@ -4925,7 +5330,8 @@ cmd_loop() {
     notify)       _notify "${1:-roll}" "${2:-}" ;;
     enforce-tcr)  _loop_enforce_tcr "${1:-}" "${2:-}" ;;
     precheck-ci)  _loop_precheck_ci ;;
-    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|events|attach|mute|unmute|pause|resume|reset|notify|enforce-tcr|precheck-ci>"; exit 1 ;;
+    branches)     _loop_branches "$(pwd -P)" ;;
+    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|events|attach|mute|unmute|pause|resume|reset|notify|enforce-tcr|precheck-ci|branches>"; exit 1 ;;
   esac
 }
 
@@ -4945,12 +5351,25 @@ _loop_on() {
   if [[ "$(uname)" == "Darwin" ]]; then
     _install_launchd_plists "$project_path" >/dev/null
 
+    # FIX-098: use launchctl bootstrap/enable instead of load -w.
+    # `load -w` writes to the disabled-overrides DB which causes FIX-027's
+    # re-source to break after `roll update`. bootstrap is idem-potent and
+    # does not disturb the overrides DB.
+    local uid; uid=$(id -u)
     local all_loaded=true
     for svc in loop dream brief; do
       local label; label=$(_launchd_label "$svc" "$project_path")
+      local plist; plist=$(_launchd_plist_path "$svc" "$project_path")
       if ! _launchd_is_loaded "$label"; then
         all_loaded=false
-        launchctl load -w "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
+        # FIX-097 guard: skip real launchctl when _LAUNCHD_DIR was auto-sandboxed.
+        _launchd_should_skip_registry && continue
+        # FIX-098 semantic: enable+bootstrap pair (better than load -w).
+        # enable clears any disable-override; bootstrap registers with launchd.
+        # FIX-101 wrapper additionally tripwire-gates each call so a sandboxed
+        # _LAUNCHD_DIR can't accidentally touch host launchd state.
+        _launchctl_safe enable "gui/${uid}/${label}" 2>/dev/null || true
+        _launchctl_safe bootstrap "gui/${uid}" "$plist" 2>/dev/null || true
       fi
     done
 
@@ -5002,11 +5421,15 @@ _loop_off() {
 
   if [[ "$(uname)" == "Darwin" ]]; then
     local any_loaded=false
+    local _skip_off; _launchd_should_skip_registry && _skip_off=1 || _skip_off=0
     for svc in loop dream brief; do
       local label; label=$(_launchd_label "$svc" "$project_path")
       if _launchd_is_loaded "$label"; then
         any_loaded=true
-        launchctl unload -w "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
+        # FIX-097: skip real launchctl in sandbox to avoid touching the user's
+        # real launchd registry.
+        [[ "$_skip_off" == "1" ]] && continue
+        _launchctl_safe unload -w "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
       fi
     done
     if ! $any_loaded; then
@@ -5025,7 +5448,9 @@ _loop_off() {
       # disable list, polluting `launchctl print-disabled` forever even after
       # the project dir, plists, and ~/.roll are gone.
       local label; label=$(_launchd_label "$svc" "$project_path")
-      launchctl enable "gui/${uid}/${label}" 2>/dev/null || true
+      # FIX-097: same gate — never touch host launchctl from a sandbox.
+      [[ "$_skip_off" == "1" ]] && continue
+      _launchctl_safe enable "gui/${uid}/${label}" 2>/dev/null || true
     done
     ok "Loop disabled  已停用"
     return 0
@@ -5169,7 +5594,7 @@ _legacy_loop_status() {
       else
         case "$state" in
           enabled)       echo -e "    ${GREEN}${svc}     ● enabled${NC}" ;;
-          installed-off) echo -e "    ${YELLOW}${svc}     ⚠ installed/off${NC}   run: roll loop on" ;;
+          stale|installed-off) echo -e "    ${YELLOW}${svc}     ⚠ STALE — plist present but not loaded${NC}   run: roll loop on" ;;
           not-installed) echo -e "    ${RED}${svc}     ○ not installed${NC}   run: roll setup" ;;
         esac
       fi
@@ -5205,7 +5630,10 @@ _loop_pause() {
     if ! _launchd_is_loaded "$label"; then
       warn "Loop not enabled — nothing to pause  loop 未启用，无需暂停"; return 0
     fi
-    launchctl unload -w "$(_launchd_plist_path "loop" "$project_path")" 2>/dev/null || true
+    # FIX-097: never touch host launchctl from a sandboxed plist path.
+    if ! _launchd_should_skip_registry; then
+      _launchctl_safe unload -w "$(_launchd_plist_path "loop" "$project_path")" 2>/dev/null || true
+    fi
   else
     local slug; slug=$(_project_slug "$project_path")
     mkdir -p "${_SHARED_ROOT}/loop"
@@ -5225,8 +5653,9 @@ _loop_resume() {
     if [[ "$(uname)" == "Darwin" ]]; then
       local label; label=$(_launchd_label "loop" "$project_path")
       local plist; plist=$(_launchd_plist_path "loop" "$project_path")
-      if [[ -f "$plist" ]]; then
-        launchctl load -w "$plist" 2>/dev/null || true
+      if [[ -f "$plist" ]] && ! _launchd_should_skip_registry; then
+        # FIX-097: never touch host launchctl from a sandboxed plist path.
+        _launchctl_safe load -w "$plist" 2>/dev/null || true
       fi
     else
       local slug; slug=$(_project_slug "$project_path")
@@ -5295,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"
@@ -5339,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
@@ -5377,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
 
@@ -5562,15 +6068,28 @@ _loop_precheck_ci() {
 
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || return 0
 
+  # FIX-103: fetch both `status` and `conclusion`. Pre-run gate must distinguish
+  # a still-running CI (status=in_progress/queued/waiting, conclusion=null) from
+  # a genuinely red CI (conclusion=failure/cancelled/timed_out/...). Treating
+  # in_progress as red kills every cycle started within the first ~30s of a
+  # merge-triggered CI run.
   local runs
-  runs=$(gh -R "$slug" run list --commit "$commit" --json conclusion 2>/dev/null) || return 0
+  runs=$(gh -R "$slug" run list --commit "$commit" --json conclusion,status 2>/dev/null) || return 0
   [[ -z "$runs" || "$runs" == "[]" ]] && return 0
 
-  local failed
-  failed=$(echo "$runs" | jq -r '[.[] | select(.conclusion != null and .conclusion != "success" and .conclusion != "skipped")] | length' 2>/dev/null || echo "0")
+  # Conclusions that block the loop. Anything else (success, skipped, neutral,
+  # or null while still running) is treated as pass/pending.
+  local failed_conclusions
+  failed_conclusions=$(echo "$runs" \
+    | jq -r '[.[] | select(.conclusion=="failure" or .conclusion=="cancelled" or .conclusion=="timed_out" or .conclusion=="action_required" or .conclusion=="startup_failure") | .conclusion] | unique | join(",")' \
+    2>/dev/null || echo "")
 
-  if [[ "$failed" -gt 0 ]]; then
+  if [[ -n "$failed_conclusions" ]]; then
     local short; short=$(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+    local run_states
+    run_states=$(echo "$runs" \
+      | jq -r '[.[] | "\(.status // "?")/\(.conclusion // "null")"] | unique | join(", ")' \
+      2>/dev/null || echo "?")
     err "Pre-run CI check: HEAD CI is red — refuse to build on broken base (${short})  HEAD CI 红，拒绝在破损的基础上构建"
     mkdir -p "$(dirname "$_LOOP_ALERT")"
     cat > "$_LOOP_ALERT" << EOF
@@ -5579,6 +6098,8 @@ _loop_precheck_ci() {
 **Time**: $(date '+%Y-%m-%d %H:%M')
 **Commit**: ${short}
 **Reason**: HEAD CI is red — loop refused to build on a broken base  HEAD CI 红，loop 拒绝在破损的基础上构建
+**Failing conclusions**: ${failed_conclusions}
+**Run states**: ${run_states}
 
 **Action required**:
 - Investigate and fix CI: \`gh -R ${slug} run list --commit ${commit}\`
@@ -6082,10 +6603,24 @@ _loop_mark_in_progress() {
   [ -n "$story_id" ] || return 1
   [ -f "$backlog" ] || return 0
   local tmp; tmp=$(mktemp "${backlog}.XXXXXX") || return 1
+  # FIX-106: match the story-id column (col 2) for equality instead of doing
+  # substring match on the whole row. Pre-fix, picking US-X-001 also flipped
+  # any row whose description contained "depends-on:US-X-001" — leaving the
+  # dashboard claiming work on stories no one had picked.
   awk -v sid="$story_id" '
     {
-      if (index($0, sid) > 0 && index($0, "📋 Todo") > 0) {
-        sub(/📋 Todo/, "🔨 In Progress")
+      if (index($0, "📋 Todo") > 0) {
+        n = split($0, cols, "|")
+        if (n >= 2) {
+          id_cell = cols[2]
+          gsub(/[[:space:]]/, "", id_cell)
+          # Markdown link form "[ID](path)" → keep just "ID"
+          sub(/^\[/, "", id_cell)
+          sub(/\].*$/, "", id_cell)
+          if (id_cell == sid) {
+            sub(/📋 Todo/, "🔨 In Progress")
+          }
+        }
       }
       print
     }
@@ -6101,10 +6636,20 @@ _loop_mark_todo() {
   [ -n "$story_id" ] || return 1
   [ -f "$backlog" ] || return 0
   local tmp; tmp=$(mktemp "${backlog}.XXXXXX") || return 1
+  # FIX-106: same column-2 equality match as _loop_mark_in_progress.
   awk -v sid="$story_id" '
     {
-      if (index($0, sid) > 0 && index($0, "🔨 In Progress") > 0) {
-        sub(/🔨 In Progress/, "📋 Todo")
+      if (index($0, "🔨 In Progress") > 0) {
+        n = split($0, cols, "|")
+        if (n >= 2) {
+          id_cell = cols[2]
+          gsub(/[[:space:]]/, "", id_cell)
+          sub(/^\[/, "", id_cell)
+          sub(/\].*$/, "", id_cell)
+          if (id_cell == sid) {
+            sub(/🔨 In Progress/, "📋 Todo")
+          }
+        }
       }
       print
     }
@@ -6512,14 +7057,29 @@ _claude_cleanup_stale_worktrees() {
   return 0
 }
 
+# FIX-104: scan multiple ephemeral prefixes (loop/cycle-, worktree-agent-,
+# claude/) and delete any already merged to origin/main. Unmerged branches
+# are preserved — they may be active WIP. Caller can pass a custom prefix
+# list via $2 (newline-separated `refs/heads/<prefix>*` patterns) but the
+# default whitelist covers every temp prefix the loop / Claude session /
+# worktree-agent paths create.
 _loop_cleanup_stale_cycle_branches() {
   local project_path="${1:-.}"
   local url; url=$(git -C "$project_path" remote get-url origin 2>/dev/null) || return 0
   [[ "$url" == *github.com* ]] || return 0
 
-  local branches
-  branches=$(git -C "$project_path" ls-remote --heads origin 'refs/heads/loop/cycle-*' 2>/dev/null \
-    | awk '{print $2}' | sed 's|^refs/heads/||')
+  local prefixes="${2:-refs/heads/loop/cycle-*
+refs/heads/worktree-agent-*
+refs/heads/claude/*}"
+
+  local branches=""
+  while IFS= read -r pat; do
+    [ -z "$pat" ] && continue
+    local found
+    found=$(git -C "$project_path" ls-remote --heads origin "$pat" 2>/dev/null \
+      | awk '{print $2}' | sed 's|^refs/heads/||')
+    [ -n "$found" ] && branches+="${found}"$'\n'
+  done <<< "$prefixes"
   [ -z "$branches" ] && return 0
 
   while IFS= read -r branch; do
@@ -6534,6 +7094,41 @@ _loop_cleanup_stale_cycle_branches() {
   return 0
 }
 
+# FIX-104: residual-visibility command. List origin's ephemeral temp branches
+# (loop/cycle-*, worktree-agent-*, claude/*) with their merge status so the
+# user can see what GC will clean up next cycle and what's still active WIP.
+# Output: TAB-separated `<branch>\t<merged|open>` lines, one per branch.
+# Silent on non-GitHub remote / empty / unreachable.
+_loop_branches() {
+  local project_path="${1:-.}"
+  local url; url=$(git -C "$project_path" remote get-url origin 2>/dev/null) || return 0
+  [[ "$url" == *github.com* ]] || return 0
+
+  local prefixes="refs/heads/loop/cycle-*
+refs/heads/worktree-agent-*
+refs/heads/claude/*"
+
+  local branches=""
+  while IFS= read -r pat; do
+    [ -z "$pat" ] && continue
+    local found
+    found=$(git -C "$project_path" ls-remote --heads origin "$pat" 2>/dev/null \
+      | awk '{print $2}' | sed 's|^refs/heads/||')
+    [ -n "$found" ] && branches+="${found}"$'\n'
+  done <<< "$prefixes"
+  [ -z "$branches" ] && return 0
+
+  while IFS= read -r branch; do
+    [ -z "$branch" ] && continue
+    local status="open"
+    if git -C "$project_path" merge-base --is-ancestor "$branch" origin/main 2>/dev/null; then
+      status="merged"
+    fi
+    printf "%s\t%s\n" "$branch" "$status"
+  done <<< "$branches"
+  return 0
+}
+
 # US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
 #
 # _loop_publish_pr <branch> [title]
@@ -6625,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 ;;
@@ -7076,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() {
@@ -7114,7 +7763,19 @@ cmd_ci() {
 # will switch to hard-fail. Output format mirrors a linter ("file:line:
 # message") so editors can navigate from it.
 _backlog_lint() {
-  local backlog="${1:-.roll/backlog.md}"
+  # FIX-102: --gate flag flips Phase 1 warn-only behavior to hard-fail.
+  # When passed, any violation makes the command exit 1 — used by the
+  # PreToolUse / Stop hook in ~/.claude/settings.json to actually block
+  # the assistant from leaving the backlog dirty.
+  local gate=0
+  local backlog=".roll/backlog.md"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --gate) gate=1 ;;
+      *) backlog="$1" ;;
+    esac
+    shift
+  done
   [ -f "$backlog" ] || { err "backlog not found: $backlog"; return 1; }
 
   local violations=0
@@ -7139,6 +7800,18 @@ _backlog_lint() {
       | sed -E 's|^\[[A-Z]+-[0-9]+\]\([^)]*\)[[:space:]]*||' \
       | sed -E 's|^[A-Z]+-[0-9]+[[:space:]]*||')
     local issues=""
+    # FIX-102: length check — backlog rows are an index page; descriptions
+    # must be one human sentence (≤120 chars). Longer = technical detail
+    # that belongs in the linked .roll/features/<epic>/<slug>.md.
+    if [ "${#body}" -gt 120 ]; then
+      issues="${issues:+${issues}, }length>${#body}"
+    fi
+    # FIX-102: code-fence check — backticks (`code`) signal technical jargon
+    # (commands, identifiers, paths). Keep description prose plain text;
+    # any code goes in the feature file.
+    if echo "$body" | grep -qF '`'; then
+      issues="${issues:+${issues}, }code-fence"
+    fi
     # Filenames: bare `something.ext` for common code/config extensions
     if echo "$body" | grep -qE '\b[A-Za-z_][A-Za-z0-9_.-]*\.(sh|bash|yaml|yml|json|js|ts|tsx|py|rb|go|rs|c|cpp|h)\b'; then
       issues="${issues:+${issues}, }filename"
@@ -7165,11 +7838,14 @@ _backlog_lint() {
   echo ""
   if [ "$violations" -gt 0 ]; then
     echo "  ${violations} violation(s) — see conventions/global/AGENTS.md §4"
+    if [ "$gate" = 1 ]; then
+      echo "  ${violations} 条违规 — --gate enabled, exiting 1"
+      return 1
+    fi
     echo "  ${violations} 条违规 — Phase 1: warn-only, not blocking"
   else
     echo "  No violations  无违规"
   fi
-  # Phase 1: warn-only. Exit 0 regardless.
   return 0
 }
 
@@ -7185,7 +7861,8 @@ cmd_backlog() {
   # ── Status management subcommands ─────────────────────────────────────────
   case "$subcmd" in
     lint)
-      _backlog_lint "$backlog"
+      shift
+      _backlog_lint "$@" "$backlog"
       return
       ;;
     block|defer|unblock|promote)
@@ -7842,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; } ;;