@seanyao/roll 2026.518.3 → 2026.518.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v2026.518.4
+
+### Improved
+
+- **`roll` 主页焕新** — 一屏看清 loop / dream / peer 状态、四道防线、Pipeline 进度和待你处理的事 `[loop]`
+- **`roll --help` 焕新** — 命令按日常 / 项目 / 全局三组分类，常用命令 ★ 高亮，不再被大字 ASCII banner 占屏 `[loop]`
+- **`roll status` 焕新** — 一行看健康总览，AI 客户端同步状态、约定文件清单、项目模板逐段展示，drift 行直接给修复命令 `[loop]`
+- **`roll backlog`** — 待办任务按缺陷 / 故事 / 重构 / 创意四类分组显示，进行中的条目紫色高亮，Blocked / Deferred 分区附带原因 `[loop]`
+- **`roll brief`** — 简报现在用终端三段式渲染：摘要数字、已完成亮点、待决策清单按 D1/D2 编号 `[loop]`
+- **`roll setup`** — 首次安装流程现在显示 6 步编号进度，每步完成打勾，结尾显示"Setup complete" `[loop]`
+
+### Fixed
+
+- **loop 弹窗现在固定走 Terminal.app** — 不再按终端偏好挑来挑去，省得在新版 Ghostty 上弹窗假成功、备选方案也失效 `[loop]`
+- **与 roll agent 对话** — 不再因工具不同而忽冷忽热 `[loop]`
+- **大小写不同路径进同一项目** — 不再被 loop 当成两个独立项目、LOCK 和状态不再分裂 `[loop]`
+- **loop 跑完一轮** — 不再挡死后续调度、卡到手动 kill `[loop]`
+- **binary 升级后 loop dashboard 回落 IDLE 问题** — 旧 binary 用不同路径大小写算出不同 slug，新 binary 启动时自动把旧 slug 的状态文件、日志、历史记录全部迁到新 slug，upgrade 无感无损 `[loop]`
+- **loop status 费用显示严重偏低** — `$9.25` 的 cycle 显示为 `$0.04`：读取了最后一次 API 调用的 token 数重新算价，改为直接用 `cost_reported_usd`（loop-fmt 写入的权威累计值） `[loop]`
+
 ## v2026.518.3
 
 ### Fixed

package/bin/roll

@@ -4,14 +4,14 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.518.3"
+VERSION="2026.518.4"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
 ROLL_TEMPLATES="${ROLL_HOME}/conventions/templates"
 
 # Find package root (resolve symlinks so it works from ~/.local/bin/roll or npm global bin)
-_source="${BASH_SOURCE[0]}"
+_source="${BASH_SOURCE[0]:-$0}"
 while [[ -L "$_source" ]]; do
   _dir="$(cd "$(dirname "$_source")" && pwd)"
   _source="$(readlink "$_source")"
@@ -574,13 +574,20 @@ _ensure_tmux() {
 
 cmd_setup() {
   local force=false
+  local demo=false
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --force|-f) force=true; shift ;;
+      --demo)     demo=true;  shift ;;
       *) err "Unknown argument: $1  未知参数: $1"; exit 1 ;;
     esac
   done
 
+  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-setup.py" --demo
+    if [[ "$demo" == "true" ]]; then return; fi
+  fi
+
   info "Setting up Roll on this machine...  正在初始化 Roll..."
   echo ""
 
@@ -1070,7 +1077,7 @@ EOF
 # COMMAND: status
 # Show current state of conventions
 # ═══════════════════════════════════════════════════════════════════════════════
-cmd_status() {
+_legacy_status() {
   echo -e "${BOLD}Roll Convention Status  Roll 约定状态${NC}"
   echo ""
 
@@ -1187,6 +1194,14 @@ cmd_status() {
   _status_loop_overview
 }
 
+cmd_status() {
+  if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-status.py" "$@"
+  else
+    _legacy_status "$@"
+  fi
+}
+
 _status_loop_overview() {
   [[ "$(uname)" != "Darwin" ]] && return 0
 
@@ -1352,41 +1367,20 @@ _peer_route() {
   return 1
 }
 
-# Open a terminal window attached to the given tmux session (peer auto-attach).
-# No-ops when muted, non-macOS, or tmux unavailable. Mirrors loop popup logic.
+# Open a Terminal.app window attached to the given tmux session (peer
+# auto-attach). No-ops when muted, non-macOS, or osascript unavailable.
+# FIX-054: terminal selection removed — always dispatches to macOS
+# Terminal.app for predictability (per-user detection silently failed on
+# Ghostty upgrades).
 _peer_auto_attach() {
   local session="$1"
   [ "$(uname)" = "Darwin" ] || return 0
   [ -f "$_LOOP_MUTE_FILE" ] && return 0
-  local terminal_pref
-  terminal_pref=$(config_get "loop_attach_terminal" "")
-  if [[ -z "$terminal_pref" ]]; then
-    case "${TERM_PROGRAM:-}" in
-      ghostty)   terminal_pref="ghostty" ;;
-      iTerm.app) terminal_pref="iTerm2" ;;
-      *)         terminal_pref="Terminal" ;;
-    esac
-  fi
-  local launched=0
-  if [[ "$terminal_pref" = "ghostty" || "$terminal_pref" = "Ghostty" ]]; then
-    open -na Ghostty.app --args -e tmux attach -t "$session" >/dev/null 2>&1 && launched=1 || true
-  fi
-  if [[ $launched -eq 0 ]] && { [[ "$terminal_pref" = "iTerm2" || "$terminal_pref" = "iTerm" ]] || [[ -d "/Applications/iTerm.app" ]]; }; then
-    osascript \
-      -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \
-      -e "tell application \"iTerm2\" to create window with default profile command \"tmux attach -t $session\"" \
-      -e 'delay 0.3' -e 'try' -e 'tell application _prev to activate' -e 'end try' >/dev/null 2>&1 \
-      && launched=1 || true
-  fi
-  if [[ $launched -eq 0 ]] && [[ -d "/Applications/Ghostty.app" ]]; then
-    open -na Ghostty.app --args -e tmux attach -t "$session" >/dev/null 2>&1 && launched=1 || true
-  fi
-  if [[ $launched -eq 0 ]] && command -v osascript >/dev/null 2>&1; then
-    osascript \
-      -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \
-      -e "tell application \"Terminal\" to do script \"tmux attach -t $session\"" \
-      -e 'delay 0.3' -e 'try' -e 'tell application _prev to activate' -e 'end try' >/dev/null 2>&1 || true
-  fi
+  command -v osascript >/dev/null 2>&1 || return 0
+  osascript \
+    -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \
+    -e "tell application \"Terminal\" to do script \"tmux attach -t $session\"" \
+    -e 'delay 0.3' -e 'try' -e 'tell application _prev to activate' -e 'end try' >/dev/null 2>&1 || true
 }
 
 # Dispatch a peer CLI command inside an existing tmux session (window 0).
@@ -2005,6 +1999,13 @@ cmd_agent() {
 # hash of the full path, ensuring uniqueness across sibling dirs with same name.
 _project_slug() {
   local path="${1:-$(pwd -P 2>/dev/null || pwd)}"
+  # FIX-056: normalize path to canonical case on macOS case-insensitive filesystem.
+  # Two paths differing only in case point to the same directory; realpath
+  # resolves both symlinks and case variations to the canonical filesystem path.
+  if [[ "$(uname -s 2>/dev/null)" == "Darwin" ]]; then
+    local _canon
+    _canon=$(realpath "$path" 2>/dev/null) && path="$_canon"
+  fi
   # FIX-034: when inside a git worktree, git-common-dir returns the main tree's
   # absolute .git path; resolve to the main tree so worktree and main-tree runs
   # produce the same slug.
@@ -2024,6 +2025,90 @@ _project_slug() {
   printf '%s' "${base}-${hash}"
 }
 
+# FIX-058: migrate loop state files when the per-project slug changed due to
+# FIX-056 (realpath case-normalization on macOS).  Called by
+# _install_launchd_plists before generating new runner/plist so existing state
+# (paused/running/etc.) is not silently lost.
+#
+# Usage: _slug_migrate_from_legacy <new_slug> [<loop_dir>] [<old_slug>]
+#   new_slug   — the correct slug computed by the current _project_slug
+#   loop_dir   — optional override of ${_SHARED_ROOT}/loop (for unit tests)
+#   old_slug   — optional explicit old slug (for unit tests; auto-computed otherwise)
+_slug_migrate_from_legacy() {
+  local new_slug="$1"
+  local loop_dir="${2:-${_SHARED_ROOT}/loop}"
+  local old_slug="${3:-}"
+
+  if [[ -z "$old_slug" ]]; then
+    [[ "$(uname -s 2>/dev/null)" == "Darwin" ]] || return 0
+    # Compute the pre-FIX-056 slug: same algorithm but without realpath.
+    local raw_path; raw_path=$(pwd 2>/dev/null)
+    local _common
+    _common=$(git -C "$raw_path" rev-parse --git-common-dir 2>/dev/null)
+    if [[ -n "$_common" && "$_common" == *"/.git" ]]; then
+      raw_path="${_common%/.git}"
+    fi
+    local old_base; old_base=$(basename "$raw_path")
+    local old_hash
+    if command -v md5 &>/dev/null; then
+      old_hash=$(printf '%s' "$raw_path" | md5 | cut -c1-6)
+    else
+      old_hash=$(printf '%s' "$raw_path" | md5sum | cut -c1-6)
+    fi
+    old_base=$(printf '%s' "$old_base" | tr -cs '[:alnum:]' '-' | sed 's/-*$//')
+    old_slug="${old_base}-${old_hash}"
+  fi
+
+  [[ "$old_slug" == "$new_slug" ]] && return 0
+  [[ -f "${loop_dir}/state-${old_slug}.yaml" ]] || return 0
+
+  printf 'roll: migrating loop state %s → %s\n' "$old_slug" "$new_slug" >&2
+
+  mv "${loop_dir}/state-${old_slug}.yaml" "${loop_dir}/state-${new_slug}.yaml"
+
+  [[ -f "${loop_dir}/cron-${old_slug}.log" ]] && \
+    mv "${loop_dir}/cron-${old_slug}.log" "${loop_dir}/cron-${new_slug}.log"
+
+  if [[ -f "${loop_dir}/events-${old_slug}.ndjson" ]]; then
+    if [[ -f "${loop_dir}/events-${new_slug}.ndjson" ]]; then
+      cat "${loop_dir}/events-${old_slug}.ndjson" >> "${loop_dir}/events-${new_slug}.ndjson"
+      rm "${loop_dir}/events-${old_slug}.ndjson"
+    else
+      mv "${loop_dir}/events-${old_slug}.ndjson" "${loop_dir}/events-${new_slug}.ndjson"
+    fi
+  fi
+
+  local runs_file="${loop_dir}/runs.jsonl"
+  if [[ -f "$runs_file" ]]; then
+    local tmp; tmp=$(mktemp)
+    python3 - "$old_slug" "$new_slug" "$runs_file" > "$tmp" << 'PYEOF'
+import json, sys
+old, new, path = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(path) as f:
+    for line in f:
+        line = line.rstrip('\n')
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+            if 'project' in d and old in str(d['project']):
+                d['project'] = str(d['project']).replace(old, new)
+            print(json.dumps(d))
+        except Exception:
+            print(line)
+PYEOF
+    mv "$tmp" "$runs_file"
+  fi
+
+  local old_plist=~/Library/LaunchAgents/com.roll.loop.${old_slug}.plist
+  if [[ -f "$old_plist" ]]; then
+    launchctl unload "$old_plist" 2>/dev/null || true
+    rm -f "$old_plist"
+  fi
+
+  rm -f "${loop_dir}/run-${old_slug}.sh" "${loop_dir}/run-${old_slug}-inner.sh"
+}
+
 _LOOP_TAG="# roll-loop"
 : "${_SHARED_ROOT:=${HOME}/.shared/roll}"
 # FIX-052: per-project loop state — ALERT/state/mute were globally shared,
@@ -2202,7 +2287,10 @@ _write_runner_script() {
 # Falls back to headless execution when tmux is not installed.
 _write_loop_runner_script() {
   local script_path="$1" project_path="$2" cmd="$3" log_path="$4"
-  local active_start="${5:-10}" active_end="${6:-18}" terminal_pref="${7:-Terminal}"
+  local active_start="${5:-10}" active_end="${6:-18}"
+  # FIX-054: terminal preference detection removed. Popup is hard-coded to
+  # macOS Terminal.app; the 7th positional arg, if any, is ignored for
+  # backwards compatibility with existing callers.
   mkdir -p "$(dirname "$script_path")"
 
   local inner_path="${script_path%.sh}-inner.sh"
@@ -2262,7 +2350,29 @@ _heartbeat_writer() {
 }
 _heartbeat_writer &
 _HEARTBEAT_PID=\$!
-trap 'kill "\${_HEARTBEAT_PID}" 2>/dev/null; rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"' EXIT
+# FIX-057: cycle hard timeout — 45 minute SLA per loop cycle. If a cycle runs
+# longer, kill claude / loop-fmt.py / all backgrounded children, mark the
+# in-progress backlog item Blocked (caller decides), and exit cleanly so the
+# next cron tick can proceed. Overridable via env for tests.
+LOOP_CYCLE_TIMEOUT_SEC="\${ROLL_LOOP_CYCLE_TIMEOUT_SEC:-2700}"
+_CYCLE_TIMED_OUT=0
+_on_sigterm() { _CYCLE_TIMED_OUT=1; }
+trap '_on_sigterm' TERM
+_inner_cleanup() {
+  local _rc=\$?
+  # 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.
+  kill "\${_HEARTBEAT_PID}" 2>/dev/null
+  for _pid in \$(jobs -p); do kill "\$_pid" 2>/dev/null; done
+  if [ "\${_CYCLE_TIMED_OUT:-0}" -eq 1 ]; then
+    _loop_event cycle_end "\${CYCLE_ID:-unknown}" "\${BRANCH:-}" "blocked" 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
+  rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
+  exit "\$_rc"
+}
+trap '_inner_cleanup' EXIT
 
 # US-AUTO-037: pull in worktree helpers (US-AUTO-036). Sourcing bin/roll is
 # safe — its main() only runs when invoked directly (BASH_SOURCE == \$0).
@@ -2350,12 +2460,21 @@ 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
+  # FIX-057: watchdog — fires SIGTERM at the inner script (and its direct
+  # children) when the cycle exceeds LOOP_CYCLE_TIMEOUT_SEC. Signal the inner
+  # script first so _on_sigterm sets _CYCLE_TIMED_OUT before pkill takes out
+  # the watchdog subshell itself (pkill -P \$\$ matches this subshell too).
+  ( sleep "\$LOOP_CYCLE_TIMEOUT_SEC" && { kill -TERM \$\$ 2>/dev/null; pkill -TERM -P \$\$ 2>/dev/null; } ) &
+  _WATCHDOG_PID=\$!
   if [ -f "\$FMT" ]; then
     ( cd "\$WT" && ${claude_cmd} ) | python3 "\$FMT"
   else
     ( cd "\$WT" && ${claude_cmd} )
   fi
   _exit=\$?
+  kill "\$_WATCHDOG_PID" 2>/dev/null
+  wait "\$_WATCHDOG_PID" 2>/dev/null
+  [ "\$_CYCLE_TIMED_OUT" -eq 1 ] && break
   [ "\$_exit" -eq 0 ] && break
   if [ "\$_attempt" -lt 3 ]; then
     echo "[loop] claude exited \$_exit (attempt \$_attempt/3) — retrying in 30s..."
@@ -2363,6 +2482,12 @@ for _attempt in 1 2 3; do
   fi
 done
 
+# 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)"
+  exit 0
+fi
+
 # FIX-044: capture cycle data from worktree before cleanup removes it
 _cycle_tcr=0
 _cycle_status="idle"
@@ -2587,33 +2712,28 @@ if command -v tmux >/dev/null 2>&1; then
   done
   tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
   tmux pipe-pane -t "\$SESSION" "cat >> \"\$LOG\""
-  # 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 [ -z "\${ROLL_LOOP_NO_POPUP:-}" ] && [ -z "\${BATS_TEST_NUMBER:-}" ] && [ ! -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
-    case "${terminal_pref}" in
-      ghostty|Ghostty)
-        open -na Ghostty.app --args -e tmux attach -t \$SESSION >/dev/null 2>&1 && _launched=1 || true
-        ;;
-      iTerm2|iTerm)
-        osascript \\
-          -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \\
-          -e "tell application \"iTerm2\" to create window with default profile command \"tmux attach -t \$SESSION\"" \\
-          -e 'delay 0.3' -e 'try' -e 'tell application _prev to activate' -e 'end try' >/dev/null 2>&1 \\
-          && _launched=1 || true
-        ;;
-    esac
-    if [ "\$_launched" -eq 0 ] && command -v osascript >/dev/null 2>&1; then
-      osascript \\
-        -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \\
-        -e "tell application \"Terminal\" to do script \"tmux attach -t \$SESSION\"" \\
-        -e 'delay 0.3' -e 'try' -e 'tell application _prev to activate' -e 'end try' >/dev/null 2>&1 || true
-    fi
+  # Auto-attach popup: when not muted, spawn a Terminal.app window attached
+  # to the tmux session so the user can watch the loop work in real time.
+  # FIX-054: terminal selection removed — fixed to macOS Terminal.app for
+  # predictability (per-user detection silently failed on Ghostty upgrades).
+  # Best-effort focus retention: capture the current frontmost app and
+  # re-activate after.
+  if [ -z "\${ROLL_LOOP_NO_POPUP:-}" ] && [ -z "\${BATS_TEST_NUMBER:-}" ] && [ ! -f "\$HOME/.shared/roll/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ] && command -v osascript >/dev/null 2>&1; then
+    osascript \\
+      -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \\
+      -e "tell application \"Terminal\" to do script \"tmux attach -t \$SESSION\"" \\
+      -e 'delay 0.3' -e 'try' -e 'tell application _prev to activate' -e 'end try' >/dev/null 2>&1 || true
   fi
-  while tmux has-session -t "\$SESSION" 2>/dev/null; do sleep 5; done
+  _OUTER_TIMEOUT=\$(( \${ROLL_LOOP_CYCLE_TIMEOUT_SEC:-2700} + 300 ))
+  _outer_wait_start=\$(date +%s)
+  while tmux has-session -t "\$SESSION" 2>/dev/null; do
+    sleep 5
+    if (( \$(date +%s) - _outer_wait_start > _OUTER_TIMEOUT )); then
+      echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-057: outer timeout (\${_OUTER_TIMEOUT}s) — killing tmux session \$SESSION" >> "\$LOG"
+      tmux kill-session -t "\$SESSION" 2>/dev/null || true
+      break
+    fi
+  done
 else
   bash "\$INNER_SCRIPT" >> "\$LOG" 2>&1
 fi
@@ -2659,16 +2779,7 @@ _install_launchd_plists() {
   brief_hour=$(_config_read_int "loop_brief_hour" "9")
   brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
 
-  # Terminal preference: config wins, then TERM_PROGRAM env, then "Terminal"
-  local terminal_pref
-  terminal_pref=$(config_get "loop_attach_terminal" "")
-  if [[ -z "$terminal_pref" ]]; then
-    case "${TERM_PROGRAM:-}" in
-      ghostty)    terminal_pref="ghostty" ;;
-      iTerm.app)  terminal_pref="iTerm2" ;;
-      *)          terminal_pref="Terminal" ;;
-    esac
-  fi
+  # FIX-054: terminal preference removed — runner always uses Terminal.app.
 
   local services=("loop" "dream" "brief")
   local skill_names=("roll-loop" "roll-.dream" "roll-brief")
@@ -2677,6 +2788,9 @@ _install_launchd_plists() {
 
   local updated=0
   local slug; slug=$(_project_slug "$project_path")
+  # FIX-058: after FIX-056 introduced realpath normalization, the slug for an
+  # existing project may have changed.  Migrate state before creating new files.
+  _slug_migrate_from_legacy "$slug" "${shared}/loop"
   for i in "${!services[@]}"; do
     local svc="${services[$i]}"
     local skill="${skill_names[$i]}"
@@ -2690,7 +2804,7 @@ _install_launchd_plists() {
     local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
 
     if [[ "$svc" == "loop" ]]; then
-      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end" "$terminal_pref"
+      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end"
     else
       _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
     fi
@@ -2709,6 +2823,13 @@ _install_launchd_plists() {
         local uid; uid=$(id -u)
         launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
         launchctl 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
       fi
     fi
   done
@@ -2934,17 +3055,7 @@ _loop_test() {
   local log="${_SHARED_ROOT}/loop/cron-${slug}.log"
   local test_runner="${_SHARED_ROOT}/loop/run-${slug}-test.sh"
 
-  # Detect terminal pref same way _install_launchd_plists does
-  local terminal_pref
-  terminal_pref=$(config_get "loop_attach_terminal" "")
-  if [[ -z "$terminal_pref" ]]; then
-    case "${TERM_PROGRAM:-}" in
-      ghostty)    terminal_pref="ghostty" ;;
-      iTerm.app)  terminal_pref="iTerm2" ;;
-      *)          terminal_pref="Terminal" ;;
-    esac
-  fi
-
+  # FIX-054: terminal preference removed — runner always uses Terminal.app.
   local active_start active_end
   active_start=$(_config_read_int "loop_active_start" "10")
   active_end=$(_config_read_int "loop_active_end" "18")
@@ -2952,7 +3063,7 @@ _loop_test() {
   info "Generating test runner...  正在生成测试启动脚本..."
   _write_loop_runner_script "$test_runner" "$project_path" \
     'claude -p "Reply with a single word: hello"; sleep 10' \
-    "$log" "$active_start" "$active_end" "$terminal_pref"
+    "$log" "$active_start" "$active_end"
 
   info "Starting smoke test (real claude, trivial prompt)...  正在运行 smoke 测试（真实 claude）..."
   info "Watch for: tmux session + terminal popup + stream-json events flowing"
@@ -4057,7 +4168,7 @@ _changelog_audit_bullet() {
   # Rule 1: length cap 30 (user-command in backticks bypasses this rule).
   if ! printf '%s' "$bullet" | grep -q '`'; then
     local len
-    len=$(LC_ALL=en_US.UTF-8 printf '%s' "$bullet" | LC_ALL=en_US.UTF-8 wc -m | tr -d ' ')
+    len=$(printf '%s' "$bullet" | LC_ALL=C.UTF-8 wc -m | tr -d ' ')
     if [ "${len:-0}" -gt 30 ]; then
       echo "over-length-30"
     fi
@@ -4080,7 +4191,7 @@ _changelog_audit_bullet() {
   fi
 
   # Rule 5: required shape — em dash, 不再, or 现在.
-  if ! printf '%s' "$bullet" | grep -qE '—|不再|现在'; then
+  if ! printf '%s' "$bullet" | LC_ALL=C.UTF-8 grep -qE '—|不再|现在'; then
     echo "bad-shape"
   fi
 
@@ -4654,7 +4765,17 @@ cmd_brief() {
     fi
   fi
 
-  [[ -f "$latest" ]] && cat "$latest"
+  if [[ ! -f "$latest" ]]; then
+    return 1
+  fi
+
+  # ── Display mode ──────────────────────────────────────────────────────────
+  if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-brief.py" "$@"
+    return
+  fi
+
+  cat "$latest"
 }
 
 _promote_unreleased() {
@@ -4861,6 +4982,10 @@ cmd_backlog() {
   esac
 
   # ── Display mode ──────────────────────────────────────────────────────────
+  if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-backlog.py" "$@"
+    return
+  fi
   local DIM='\033[2m'
 
   local us_items fix_items refactor_items idea_items total=0
@@ -5150,7 +5275,7 @@ _dash_brief_summary() {
   ' "$latest" 2>/dev/null | head -1 | cut -c1-60
 }
 
-_dashboard() {
+_legacy_home() {
   local project_path; project_path=$(pwd -P)
   local project_name; project_name=$(basename "$project_path")
   local agent; agent=$(_project_agent)
@@ -5331,10 +5456,18 @@ _dashboard() {
   echo ""
 }
 
+_home() {
+  if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-home.py" "$@"
+  else
+    _legacy_home "$@"
+  fi
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # MAIN
 # ═══════════════════════════════════════════════════════════════════════════════
-usage() {
+_legacy_help() {
   echo -e "${CYAN} ██████╗  ██████╗ ██╗     ██╗     ${NC}"
   echo -e "${CYAN} ██╔══██╗██╔═══██╗██║     ██║     ${NC}"
   echo -e "${CYAN} ██████╔╝██║   ██║██║     ██║     ${NC}"
@@ -5376,6 +5509,14 @@ usage() {
 
 }
 
+_help() {
+  if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-help.py" "$@"
+  else
+    _legacy_help "$@"
+  fi
+}
+
 main() {
   local cmd="${1:-}"
   shift || true
@@ -5395,8 +5536,8 @@ main() {
     doctor)        cmd_doctor "$@" ;;
     review-pr)     cmd_review_pr "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
-    help|--help|-h) usage ;;
-    "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;
+    help|--help|-h) _help "$@" ;;
+    "") [[ -f "BACKLOG.md" ]] && _home || { _help; _show_changelog; } ;;
     *)
       err "Unknown command: $cmd  未知命令: $cmd"
       echo ""

package/conventions/global/AGENTS.md

@@ -9,6 +9,7 @@
 - **Ambiguity resolution**: When user says "explicit" in automation contexts,
   interpret as "logged/observable with clear output", NOT "requiring manual
   intervention". Confirm with one question if uncertain.
+- **Voice**: Natural, colleague-like tone — neither robotic ("Executing…") nor over-enthusiastic ("Great!"). "Done — here's what changed." instead of "Task completed successfully." Consistent warmth for success and failure alike.
 - **Bilingual output**: EN + ZH on separate lines, never inline.
   ```
   Processing...