@seanyao/roll 2026.528.2 → 2026.529.1

package/CHANGELOG.md

@@ -1,26 +1,39 @@
 # Changelog
 
-## v2026.528.2
+## v2026.529.1
 
 ### Added
 
-- **loop 换机器跑不会再拿过期 backlog** — 每轮自动拉最新项目元数据 `[loop]`
-- **CI 红了 loop 不再干等** — 先试着自己修，修不好再找人 `[loop]`
+- **loop 运行时间可以按项目设** — 不用再全局迁就
 
 ### Fixed
 
-- **`roll loop log` 现在真的能看了** — 每轮 cycle 的留档修好了 `[loop]`
-- **loop 跑完的终端窗口不再瞬间清空** — 关闭前能看到本轮摘要 `[loop]`
+- **`roll loop on` 不再显示全 00:00** — 时间显示正常了
+- **agent 检测不再误报** — 没装的工具不会被当成可用
 
-## v2026.528.1
+## v2026.528.2
 
 ### Added
 
-- **`roll test` — 测试隔离运行，不再误伤本机 loop 服务** `[loop]`
+- **loop 换机器跑不会再拿过期 backlog** — 以前在 A 机器跑的 loop，搬到 B 机器继续时会用本地的旧 backlog，不知道有什么新待办；现在每轮开始前自动拉一次最新状态，多台机器始终看同一份 `[loop]`
+
+- **CI 红了 loop 不再干等** — 主干测试挂掉时，loop 以前会停下等人去修；现在先自己分析失败原因、发一个修复，试满 3 次还没修好才发告警找人；自己开的 PR 被 CI 标红后也会自动续上去修，不会因为"本轮 loop 已经结束"就悄悄放弃 `[loop]`
+
+- **`roll test` — 测试跑在独立环境里，不会再误伤本机** — 以前跑完整测试套件会触碰本机的 loop 调度服务，测试一过就把正在运行的 loop 打掉；现在测试在独立的 macOS VM 里跑，本机的 loop 完全不受影响 `[test]`
 
 ### Fixed
 
-- **Kimi CLI 升级改名为 kimi-code 后，roll 现在能正常识别** `[loop]`
+- **Kimi CLI 改名后全链路都能识别了** — Kimi 把工具从 kimi-cli 改名为 kimi-code、安装目录也换了；Roll 现在新旧名字都能认出来，kimi-code 的安装路径也加进了自动查找范围，调度环境里也能找到，已设好的旧配置不需要动 `[agent]`
+
+- **`roll loop log` 现在真的能看了** — 每轮 cycle 的日志存档修好了；以前文件根本没生成，现在用 `roll loop log` 能查到每一轮跑了什么 `[loop]`
+
+- **loop 跑完的终端窗口不再瞬间消失** — 以前 cycle 结束 Terminal 窗口立刻关掉，来不及看本轮干了什么；现在窗口留着直到你自己关 `[loop]`
+
+### Improved
+
+- **提交安全检查不会再被静默绕过** — Roll 的 TCR 要求每次提交前先过测试；以前在新终端或新机器上开工，这道检查会因为 git 配置没自动生效而悄悄失效，自动化环境尤其容易中招；现在每次打开 Claude Code 新会话、或跑 `roll setup` 都会自动配好，这个漏洞从源头堵死 `[infra]`
+
+- **macOS 自带 bash 下中文命名的测试用例不再被静默跳过** — macOS 系统自带的旧版 bash 在处理中文或特殊字符测试名时会截断，导致这些测试根本没执行却也不报错，本地看起来全绿但实际上漏了一批用例；已修复，本地和 CI 结果现在一致 `[test]`
 
 ## v2026.527.1
 

package/README.md

@@ -50,6 +50,7 @@ roll loop on        # let AI work through the backlog (optional)
 | `roll status` | Show current state and drift |
 | `roll agent [use <name>]` | Per-project agent selection |
 | `roll ci [--wait]` | Show or wait for current commit's CI status |
+| `roll test [--where] [--reset]` | Run the test suite (routes through isolation adapter; Tart VM on Apple Silicon) |
 | `roll release` | Run the release script (human-only) |
 | `roll review-pr <number>` | AI-powered code review for a PR |
 | **Machine · global** | |

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.528.2"
+VERSION="2026.529.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -83,31 +83,80 @@ lower_name() {
 }
 
 
-# Check if an AI tool is actually installed.
-# Most tools create their own config dir; Trae on macOS uses Library/Application Support
-# and expects roll to manage ~/.trae/ — so we detect via the app directory instead.
-_is_ai_installed() {
-  local ai_dir="$1"
-  [[ -d "$ai_dir" ]] && return 0
-  local bn
-  bn="$(basename "$ai_dir" | sed 's/^\.//')"
-  case "$bn" in
+# FIX-128: agent → binary-name(s) lookup. First binary found wins. Used by
+# _agent_installed_by_name to enforce "CLI must exist on PATH" detection
+# instead of the old "config dir exists" check (which Roll's own convention
+# sync would fake — see FIX-128).
+_agent_bin_names() {
+  case "$1" in
+    claude)            echo "claude" ;;
+    codex|openai)      echo "codex" ;;        # openai is a Roll alias for codex
+    agy|gemini)        echo "agy gemini" ;;   # gemini reuses ~/.gemini for agy
+    kimi)              echo "kimi-code kimi-cli kimi" ;;  # FIX-126
+    deepseek)          echo "deepseek" ;;
+    qwen)              echo "qwen" ;;
+    pi)                echo "pi" ;;
+    *)                 return 1 ;;
+  esac
+}
+
+# FIX-128: detect whether an AI agent (by canonical name) is actually
+# usable on this machine. For CLI-only agents this means "binary on PATH";
+# GUI / bundled-binary agents keep their special-case paths. Falls back
+# to dir-existence only for unknown agents the operator has registered
+# manually (forward-compatible with future additions).
+_agent_installed_by_name() {
+  local agent="$1"
+  local dir="${2:-}"
+  case "$agent" in
     trae)
-      [[ -d "$HOME/Library/Application Support/Trae" ]] ||
-      [[ -d "$HOME/.config/Trae" ]]
+      [[ -d "$HOME/Library/Application Support/Trae" ]] || [[ -d "$HOME/.config/Trae" ]]
       return
       ;;
     opencode)
       [[ -x "$HOME/.opencode/bin/opencode" ]]
       return
       ;;
-    agent)
-      if [[ "$(basename "$(dirname "$ai_dir")")" == ".pi" ]]; then
-        command -v pi &>/dev/null && return
-      fi
+    cursor)
+      # cursor ships a GUI + an optional CLI; either path counts as "installed".
+      command -v cursor >/dev/null 2>&1 || [[ -d "$HOME/.cursor" ]]
+      return
+      ;;
+    openclaw)
+      [[ -d "$HOME/.openclaw/workspace" ]]
+      return
       ;;
   esac
-  return 1
+  local bins
+  if bins=$(_agent_bin_names "$agent" 2>/dev/null); then
+    local b
+    for b in $bins; do
+      command -v "$b" >/dev/null 2>&1 && return 0
+    done
+    return 1
+  fi
+  # Unknown agent — fall back to dir presence so user-added entries still work.
+  [[ -n "$dir" && -d "$dir" ]]
+}
+
+# Check if an AI tool is actually installed (back-compat shim around
+# _agent_installed_by_name; preserves the dir-path-based signature used
+# throughout bin/roll).
+_is_ai_installed() {
+  local ai_dir="$1"
+  local bn
+  bn="$(basename "$ai_dir" | sed 's/^\.//')"
+  # Nested-dir layouts collapse to their parent agent name.
+  case "$bn" in
+    agent|workspace)
+      bn="$(basename "$(dirname "$ai_dir")" | sed 's/^\.//')"
+      ;;
+  esac
+  # Mirror ai_tool_name's alias normalization so detection routes to the
+  # canonical agent record (e.g. ~/.gemini → agy, ~/.kimi-code → kimi).
+  [[ "$bn" == "gemini" ]] && bn="agy"
+  [[ "$bn" == "kimi-code" ]] && bn="kimi"
+  _agent_installed_by_name "$bn" "$ai_dir"
 }
 
 # ─── Spinner: TTY-aware status display for long-running steps (US-REL-003) ───
@@ -512,8 +561,7 @@ editor: ${EDITOR:-vim}
 
 # Loop schedule (24h format, machine local timezone)
 # Minute fields auto-derive from project path hash when omitted — avoids contention across projects.
-loop_active_start: 10   # loop only fires inside this window (after human reviews brief)
-loop_active_end: 18
+# active_start/active_end moved to per-project .roll/local.yaml loop_schedule block (default 0/24).
 # loop_minute: 5        # omit to auto-derive from project hash
 loop_dream_hour: 3
 # loop_dream_minute: 10 # omit to auto-derive
@@ -522,6 +570,19 @@ loop_brief_hour: 9
 primary_agent: claude
 YAML
     ok "$(msg shared.created_roll_config_yaml)"
+
+    # FIX-128: the heredoc template hardcodes `primary_agent: claude` for
+    # the first-time case. Replace it with the first agent that actually
+    # has its CLI on PATH so users without Claude installed don't get a
+    # silently-broken default. If nothing detected, leave `claude` so the
+    # user still has a clear handle to fix manually.
+    local _detected_primary
+    _detected_primary="$(_first_installed_agent || true)"
+    if [[ -n "$_detected_primary" && "$_detected_primary" != "claude" ]]; then
+      _replace_primary_agent "$_detected_primary"
+      info "$(msg shared.primary_agent_auto_detected "$_detected_primary" 2>/dev/null \
+             || echo "primary_agent → $_detected_primary (auto-detected from installed CLIs)")"
+    fi
   fi
 
   # Ensure all expected ai_* keys exist (handles upgrades where new tools were added)
@@ -529,6 +590,32 @@ YAML
 
 }
 
+# FIX-128: pick the first agent whose CLI is on PATH, scanning the same
+# order the default config template lists them. Empty stdout when none
+# detected; never errors.
+_first_installed_agent() {
+  local agent
+  for agent in claude codex kimi deepseek qwen agy pi cursor opencode trae openclaw; do
+    if _agent_installed_by_name "$agent"; then
+      echo "$agent"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# FIX-128: rewrite the `primary_agent:` line in $ROLL_CONFIG to the given
+# value. Single-line in-place edit, preserves the rest of the file.
+_replace_primary_agent() {
+  local new="$1"
+  [[ -f "$ROLL_CONFIG" && -n "$new" ]] || return 0
+  local tmp; tmp="$(mktemp)"
+  awk -v new="$new" '
+    /^primary_agent:/ { print "primary_agent: " new; next }
+    { print }
+  ' "$ROLL_CONFIG" > "$tmp" && mv "$tmp" "$ROLL_CONFIG"
+}
+
 # ─── Internal: create or repair per-skill symlinks (non-destructive) ─────────
 _link_skills() {
   local force="${1:-false}"
@@ -539,7 +626,18 @@ _link_skills() {
   while IFS= read -r entry; do
     local ai_dir
     ai_dir="$(_ai_dir "$entry")"
-    _is_ai_installed "$ai_dir" || continue
+    # FIX-128: detection is now binary-on-PATH, but skill linking keeps
+    # the same Claude-always-syncs semantics as _apply_conventions and
+    # tolerates pre-existing config dirs (an agent the user is mid-
+    # upgrade or installed via nvm/asdf still has its convention dir;
+    # we don't want to silently stop linking skills there). Strict
+    # binary detection drives chooser logic (primary_agent /
+    # _onboard_discover_agents) — see FIX-128.
+    if [[ "$ai_dir" != "$HOME/.claude" ]] \
+       && ! _is_ai_installed "$ai_dir" \
+       && [[ ! -d "$ai_dir" ]]; then
+      continue
+    fi
     mkdir -p "$ai_dir"
 
     local ai_name ai_dir_real skills_dir
@@ -639,8 +737,13 @@ _sync_convention_for_tool() {
   local dst_dir
   dst_dir="$(dirname "$main_dst")"
 
-  # Only proceed if Claude (always) or the tool is installed
-  if [[ "$dst_dir" != "$HOME/.claude" ]] && ! _is_ai_installed "$dst_dir"; then
+  # Only proceed if Claude (always), the tool is installed (binary-on-PATH
+  # per FIX-128), or the convention dir already exists (mid-upgrade /
+  # nvm-installed binaries that aren't on this shell's PATH still get
+  # their convention refresh).
+  if [[ "$dst_dir" != "$HOME/.claude" ]] \
+     && ! _is_ai_installed "$dst_dir" \
+     && [[ ! -d "$dst_dir" ]]; then
     return
   fi
   mkdir -p "$dst_dir"
@@ -927,10 +1030,46 @@ HINT
 # prints install commands for the ones that aren't, so users who already opted
 # in (or opted out) don't get spammed each upgrade.
 cmd_doctor() {
+  _doctor_agent_section
   _doctor_pr_section
   _doctor_launchd_stale_section
 }
 
+# FIX-128: list every ai_* entry from config, tag each with binary-on-PATH
+# status and config-dir existence so the user can see at a glance which
+# agents are actually usable vs only have Roll-maintained dirs.
+_doctor_agent_section() {
+  [[ -f "$ROLL_CONFIG" ]] || return 0
+  echo ""
+  echo "$(ROLL_LANG_RESOLVED=en msg doctor.agent_detection)"
+  echo "$(ROLL_LANG_RESOLVED=zh msg doctor.agent_detection)"
+  echo ""
+  local _key _value _name _dir _installed _dir_exists _is_primary
+  _is_primary=$(grep -E '^primary_agent:' "$ROLL_CONFIG" 2>/dev/null | sed 's/^primary_agent: *//')
+  while IFS=: read -r _key _value; do
+    [[ "$_key" =~ ^ai_ ]] || continue
+    _name="${_key#ai_}"
+    [[ "$_name" == "kimi_code" ]] && continue  # dedupe
+    _dir="${_value%%|*}"
+    _dir="${_dir# }"
+    _dir="${_dir/#\~/$HOME}"
+    if _agent_installed_by_name "$_name" "$_dir"; then
+      _installed="$(msg doctor.agent_installed)"
+    else
+      _installed="$(msg doctor.agent_missing)"
+    fi
+    if [[ -d "$_dir" ]]; then
+      _dir_exists="$(msg doctor.agent_dir_exists)"
+    else
+      _dir_exists="$(msg doctor.agent_dir_missing)"
+    fi
+    local _tag=""
+    [[ "$_name" == "$_is_primary" ]] && _tag="  ($(msg doctor.agent_primary_label))"
+    printf "  %-10s  %-14s  %s%s\n" "$_name" "$_installed" "$_dir_exists" "$_tag"
+  done < "$ROLL_CONFIG"
+  return 0
+}
+
 # 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
@@ -1467,15 +1606,31 @@ _onboard_discover_agents() {
   while IFS=: read -r _key _value; do
     [[ "$_key" =~ ^ai_ ]] || continue
     _name="${_key#ai_}"
+    # ai_kimi_code → kimi (avoid listing the same agent twice).
+    [[ "$_name" == "kimi_code" ]] && _name="kimi"
     _dir="${_value%%|*}"
     _dir="${_dir# }"
     _dir="${_dir/#\~/$HOME}"
-    if [[ -d "$_dir" ]]; then
-      _ONBOARD_INSTALLED+=("$_name")
+    # FIX-128: route via _agent_installed_by_name so "installed" means the
+    # CLI is actually on PATH for known agents, not just the config dir
+    # that Roll's own convention sync would have created.
+    if _agent_installed_by_name "$_name" "$_dir"; then
+      # Dedupe — kimi may appear under both ai_kimi and ai_kimi_code.
+      # `${arr[@]+...}` keeps `set -u` happy when the array is still empty.
+      local _already=0 _existing
+      for _existing in ${_ONBOARD_INSTALLED[@]+"${_ONBOARD_INSTALLED[@]}"}; do
+        if [[ "$_existing" == "$_name" ]]; then _already=1; break; fi
+      done
+      if [[ $_already -eq 0 ]]; then _ONBOARD_INSTALLED+=("$_name"); fi
     else
-      _ONBOARD_MISSING+=("$_name")
+      local _already=0 _existing
+      for _existing in ${_ONBOARD_MISSING[@]+"${_ONBOARD_MISSING[@]}"}; do
+        if [[ "$_existing" == "$_name" ]]; then _already=1; break; fi
+      done
+      if [[ $_already -eq 0 ]]; then _ONBOARD_MISSING+=("$_name"); fi
     fi
   done < "$ROLL_CONFIG"
+  return 0
 }
 
 # US-ONBOARD-018: pick an agent for the onboard flow.
@@ -4624,13 +4779,16 @@ _isolation_tart_check_binary() {
 # returns 1 silently otherwise. Caller decides what to do.
 _isolation_tart_vm_present() {
   local name; name=$(_isolation_tart_vm_name)
-  tart list 2>/dev/null | awk -v n="$name" '$1 == n { found=1 } END { exit !found }'
+  tart list 2>/dev/null | awk -v n="$name" '$2 == n { found=1 } END { exit !found }'
 }
 
 # Returns the VM's IP on stdout when reachable; exit non-zero when the VM
 # is stopped or `tart ip` fails for any other reason.
 _isolation_tart_ip() {
   local name; name=$(_isolation_tart_vm_name)
+  # FIX: tart ip returns a stale DHCP-cached IP even for stopped VMs.
+  # Gate on tart list State field before trusting the IP.
+  tart list 2>/dev/null | awk -v n="$name" '$2 == n && $NF == "running" { found=1 } END { exit !found }' || return 1
   local ip; ip=$(tart ip "$name" 2>/dev/null) || return 1
   [[ "$ip" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]] || return 1
   printf '%s\n' "$ip"
@@ -4680,7 +4838,7 @@ _isolation_tart_provision() {
   local ip; ip=$(_isolation_tart_ip) || { err "tart provision: VM not running"; return 1; }
   local user; user=$(_isolation_tart_ssh_user)
   ssh -o BatchMode=yes -o StrictHostKeyChecking=no \
-      "${user}@${ip}" "brew list bats >/dev/null 2>&1 || brew install bats-core; \
+      "${user}@${ip}" "export PATH=/opt/homebrew/bin:/usr/local/bin:\$PATH; brew list bats >/dev/null 2>&1 || brew install bats-core; \
                        brew list node >/dev/null 2>&1 || brew install node; \
                        brew list bash >/dev/null 2>&1 || brew install bash"
 }
@@ -4695,7 +4853,7 @@ _isolation_tart_exec() {
   if ! ip=$(_isolation_tart_ip); then
     # VM stopped — start it in the background with the repo mounted.
     local repo_root; repo_root="$(pwd -P)"
-    tart run --dir="roll:${repo_root}" "$name" >/dev/null 2>&1 &
+    tart run --no-graphics --dir="roll:${repo_root}" "$name" >/dev/null 2>&1 &
     # Wait up to ~30s for IP to come up.
     local i=0
     while (( i < 30 )); do
@@ -4706,7 +4864,9 @@ _isolation_tart_exec() {
     [[ -n "${ip:-}" ]] || { err "tart exec: VM failed to start in 30s"; return 1; }
   fi
   local user; user=$(_isolation_tart_ssh_user)
-  ssh -o BatchMode=yes -o StrictHostKeyChecking=no "${user}@${ip}" "$@"
+  local remote_cmd
+  remote_cmd=$(printf '%q ' "$@")
+  ssh -o BatchMode=yes -o StrictHostKeyChecking=no "${user}@${ip}" "export PATH=/opt/homebrew/bin:/usr/local/bin:\$PATH; cd '/Volumes/My Shared Files/roll' && $remote_cmd"
 }
 
 # reset: stop, delete, re-clone from base image, then re-provision.
@@ -4810,7 +4970,8 @@ Flags:
   --help, -h     Show this help.
 
 Examples:
-  roll test                    Run the suite in whatever the config says.
+  roll test                    Run affected tests (default: --affected HEAD~1).
+  roll test -- tests/          Run the full suite explicitly.
   roll test -- --tier=fast     Forward arguments to npm test.
   roll test --where            Don't run; just report routing.
   roll test --reset            Rebuild the VM (or host no-op).
@@ -4855,7 +5016,16 @@ EOF
   fi
 
   # Pass remaining args through to npm test inside the configured adapter.
-  _isolation_dispatch exec npm test "$@"
+  # Default to --affected (HEAD~1 base) when the caller passes no extra args —
+  # mirrors the pre-commit hook's intent and keeps VM runs fast.
+  # To run the full suite explicitly: roll test -- tests/
+  local _npm_args=("$@")
+  if [[ "${#_npm_args[@]}" -eq 0 ]]; then
+    _npm_args=(--affected)
+  fi
+  # Always pass args via `--` so npm doesn't intercept flags like --affected
+  # as npm config options (npm warns and silently drops them otherwise).
+  _isolation_dispatch exec npm test -- "${_npm_args[@]}"
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -5431,6 +5601,28 @@ _loop_schedule_spec() {
   echo "60 $offset"
 }
 
+# Read loop active window from .roll/local.yaml loop_schedule block.
+# Resolution order:
+#   1. .roll/local.yaml  loop_schedule.{active_start,active_end}
+#   2. default           0 / 24  (full day)
+# Validation: both values must be integers 0–24, active_start < active_end.
+# Output: "<start> <end>" on stdout.
+_loop_read_active_window() {
+  local project_path="${1:-$(pwd -P)}"
+  local local_file="${project_path}/.roll/local.yaml"
+  if [[ -f "$local_file" ]]; then
+    local val_start val_end
+    val_start=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+active_start:/{print $2; exit}' "$local_file")
+    val_end=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+active_end:/{print $2; exit}' "$local_file")
+    if [[ "$val_start" =~ ^[0-9]+$ && "$val_end" =~ ^[0-9]+$ ]] \
+        && (( val_start < val_end && val_end <= 24 )); then
+      echo "$val_start $val_end"
+      return 0
+    fi
+  fi
+  echo "0 24"
+}
+
 # US-LOOP-032: human-readable schedule description.
 # Args: period offset [lang]
 #   lang: en (default) or zh
@@ -6625,8 +6817,8 @@ _install_launchd_plists() {
   mkdir -p "${shared}/loop" "${shared}/dream" "${shared}/brief"
 
   local active_start active_end dream_hour dream_minute brief_hour brief_minute loop_period loop_offset
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
   # US-LOOP-012: use _loop_schedule_spec instead of raw loop_minute
   local loop_spec; loop_spec=$(_loop_schedule_spec "$project_path")
   loop_period="${loop_spec%% *}"
@@ -6802,8 +6994,8 @@ _loop_on() {
   local agent; agent=$(_project_agent)
 
   local active_start active_end loop_minute dream_hour dream_minute brief_hour brief_minute
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
   # US-LOOP-011: read schedule spec from project or global config
   local loop_spec loop_period loop_offset
   loop_spec=$(_loop_schedule_spec "$project_path")
@@ -6849,10 +7041,10 @@ _loop_on() {
     fi
 
     ok "$(msg loop.loop_enabled)"
-    printf "$(msg loop.roll_loop_s_active_02d_00)" \
+    msg loop.roll_loop_s_active_02d_00 \
       "$loop_sched_en" "$active_start" "$active_end" "$loop_sched_zh" "$active_start" "$active_end"
-    printf "$(msg loop.roll_dream_daily_at_02d_02d)" "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
-    printf "$(msg loop.roll_brief_daily_at_02d_02d)" "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
+    msg loop.roll_dream_daily_at_02d_02d "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
+    msg loop.roll_brief_daily_at_02d_02d "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
     echo "  • Agent: ${agent}  (change: roll agent use <name>)"
     return 0
   fi
@@ -6880,10 +7072,10 @@ _loop_on() {
   ) | crontab -
 
   ok "$(msg loop.loop_enabled_2)"
-  printf "$(msg loop.roll_loop_s_active_02d_00_2)" \
+  msg loop.roll_loop_s_active_02d_00_2 \
     "$loop_sched_en" "$active_start" "$active_end" "$loop_sched_zh" "$active_start" "$active_end"
-  printf "$(msg loop.roll_dream_daily_at_02d_02d_2)" "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
-  printf "$(msg loop.roll_brief_daily_at_02d_02d_2)" "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
+  msg loop.roll_dream_daily_at_02d_02d_2 "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
+  msg loop.roll_brief_daily_at_02d_02d_2 "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
   echo "  • Agent: ${agent}  (change: roll agent use <name>)"
 }
 
@@ -7023,8 +7215,8 @@ _loop_test() {
 
   # 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")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
 
   info "$(msg loop.generating_test_runner_agent ${agent})"
   _write_loop_runner_script "$test_runner" "$project_path" \
@@ -9307,8 +9499,8 @@ _loop_monitor() {
     echo -e "$(msg loop.services ${BOLD} ${NC} ${CYAN} ${agent})"
     if [[ "$(uname)" == "Darwin" ]]; then
       local active_start active_end dream_hour dream_minute brief_hour brief_minute
-      active_start=$(_config_read_int "loop_active_start" "10")
-      active_end=$(_config_read_int "loop_active_end" "18")
+      local _aw; _aw=$(_loop_read_active_window "$project_path")
+      active_start="${_aw%% *}"; active_end="${_aw##* }"
       # US-LOOP-013: use schedule spec for display
       local loop_spec loop_period loop_offset
       loop_spec=$(_loop_schedule_spec "$project_path")
@@ -10178,8 +10370,8 @@ _legacy_home() {
     crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}" && loop_state="enabled"
   fi
   local active_start active_end dream_hour dream_minute brief_hour brief_minute
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
   # US-LOOP-013: use schedule spec for display
   local loop_spec loop_period loop_offset
   loop_spec=$(_loop_schedule_spec "$project_path")

package/lib/README.md

@@ -0,0 +1,42 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/ — Python helpers and i18n runtime
+
+Python scripts and shell libraries that `bin/roll` delegates to for rendering-heavy or data-processing tasks.
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `roll-loop-status.py` | Renders the `roll loop status` health dashboard — reads cycle event NDJSON, computes per-cycle rows, daily rollups, and phase-tracing breakdown |
+| `roll-loop-story.py` | Per-story rollup: aggregates cycles, tokens, cost, and PR outcomes for `roll loop story <ID>` |
+| `roll-status.py` | Renders the `roll status` one-screen sync health view |
+| `roll-init.py` | Init-flow helpers called by `roll init` |
+| `roll-setup.py` | Setup-flow helpers (convention sync, tool config write) |
+| `roll-brief.py` | Brief generation: reads cycle records and produces the feature brief |
+| `roll-backlog.py` | Backlog read/write helpers |
+| `roll-peer.py` | Peer review coordination helpers |
+| `roll-help.py` | Renders `roll --help` output |
+| `roll-plan-validate.py` | Validates plan files before story execution |
+| `model_prices.py` | List-price table for AI model API pricing (per MTok, native currency) |
+| `prices_fetcher.py` | Fetches fresh price snapshots from vendor APIs |
+| `roll_render.py` | Shared rendering utilities (tables, color, formatting) |
+| `loop-fmt.py` | Loop log formatter (ANSI-strip, timestamp alignment) |
+| `loop_unstick.py` | Diagnostic: detects and unsticks hung loop state |
+| `backfill-pi-usage.py` | Backfills pi/deepseek token and cost data into existing cycle records |
+| `changelog_audit.py` | Audits CHANGELOG.md against backlog entries |
+| `i18n.sh` | Shell wrapper that delegates i18n string lookups to `lib/i18n/` |
+| `slides-render.py` | Renders `.deck.md` → HTML slides |
+| `slides-validate.py` | Validates deck file syntax and asset references |
+
+## Sub-directories
+
+- `agent_usage/` — token-usage capture and cost attribution per agent invocation
+- `i18n/` — localized string tables for all CLI output (EN + ZH)
+- `prices/` — price snapshot JSON files (per-vendor, dated)
+- `slides/` — slide component library for `roll deck`
+
+## Dependencies
+
+Imported by `bin/roll` via subprocess calls (`python3 lib/<script>.py`).
+No third-party pip dependencies — standard library only (json, sys, os, re, datetime).

package/lib/i18n/README.md

@@ -0,0 +1,54 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/i18n/ — Localized string tables
+
+All user-visible CLI output strings for both `en` and `zh` locales, organized by command domain.
+
+## Structure
+
+Each `.sh` file under `lib/i18n/` is a shell associative-array fragment exporting a `MSG_*` namespace:
+
+```
+lib/i18n/
+├── agent.sh          # roll agent use / install messages
+├── alert.sh          # ALERT lifecycle messages
+├── backlog.sh        # backlog read/write output
+├── brief.sh          # roll-brief generation output
+├── changelog.sh      # changelog sync messages
+├── ci.sh             # CI self-heal messages
+├── debug.sh          # roll debug diagnostics
+├── doctor.sh         # roll-doctor check output
+├── dream.sh          # roll-.dream scan output
+├── init.sh           # roll init setup messages
+├── lang.sh           # locale detection + ROLL_LANG resolution
+├── loop.sh           # roll loop subcommand output (largest file)
+├── migrate.sh        # roll migrate messages
+├── offboard.sh       # roll offboard output
+├── onboard.sh        # roll onboard / legacy-onboard output
+├── peer.sh           # roll peer review messages
+├── peer_help.sh      # peer --help text
+├── peer_reset.sh     # peer reset confirmation messages
+├── peer_status.sh    # peer status output
+├── prices_refresh.sh # prices refresh output
+└── skills/           # per-skill i18n overrides
+```
+
+## Locale selection
+
+`ROLL_LANG` env var controls which locale is active. Resolved by `lang.sh`:
+
+1. `ROLL_LANG` explicit → use it
+2. `LC_ALL` / `LANG` contains `zh` → `zh`
+3. Default → `en`
+
+Each `.sh` file branches on `ROLL_LANG` and exports the appropriate string set.
+
+## skills/
+
+Per-skill message overrides for `roll-build`, `roll-design`, `roll-fix`, `roll-loop`, `roll-onboard`. Same structure as top-level files — sourced after the base file to allow skill-specific overrides without editing shared strings.
+
+## Adding a new string
+
+1. Add the key to both `en` and `zh` branches in the appropriate domain file.
+2. Reference via `msg <KEY>` in `bin/roll` or the relevant skill.
+3. Never hardcode user-facing strings in `bin/roll` directly — always go through i18n.

package/lib/i18n/doctor.sh

@@ -29,3 +29,16 @@ _i18n_set en doctor.pr_event_without_zh "contributors get AI feedback on PR open
 _i18n_set zh doctor.pr_event_without_zh "PR 一开即触发 AI 评审。"
 _i18n_set en doctor.pr_event_secret "Then set the API key secret for your configured agent in GitHub repo settings."
 _i18n_set zh doctor.pr_event_secret "然后在 GitHub 仓库设置中添加你配置的 agent 对应的 API key secret。"
+
+_i18n_set en doctor.agent_detection "Agent detection"
+_i18n_set zh doctor.agent_detection "Agent 检测"
+_i18n_set en doctor.agent_installed "CLI on PATH"
+_i18n_set zh doctor.agent_installed "CLI 可用"
+_i18n_set en doctor.agent_missing "CLI not found"
+_i18n_set zh doctor.agent_missing "CLI 未安装"
+_i18n_set en doctor.agent_dir_exists "config dir exists"
+_i18n_set zh doctor.agent_dir_exists "配置目录存在"
+_i18n_set en doctor.agent_dir_missing "config dir missing"
+_i18n_set zh doctor.agent_dir_missing "配置目录不存在"
+_i18n_set en doctor.agent_primary_label "primary"
+_i18n_set zh doctor.agent_primary_label "默认"

package/lib/i18n/loop.sh

@@ -3,22 +3,22 @@ _i18n_set en loop.loop_already_enabled_for_this_project "Loop already enabled fo
 _i18n_set zh loop.loop_already_enabled_for_this_project "当前项目 loop 已启用"
 _i18n_set en loop.loop_enabled "Loop enabled"
 _i18n_set zh loop.loop_enabled "已启用"
-_i18n_set en loop.roll_loop_s_active_02d_00 "  • roll-loop   %s  active %02d:00–%02d:00  %s（"
-_i18n_set zh loop.roll_loop_s_active_02d_00 "窗口 %02d:00–%02d:00）\n"
-_i18n_set en loop.roll_dream_daily_at_02d_02d "  • roll-.dream daily at %02d:%02d"
-_i18n_set zh loop.roll_dream_daily_at_02d_02d "每天 %02d:%02d\n"
-_i18n_set en loop.roll_brief_daily_at_02d_02d "  • roll-brief  daily at %02d:%02d"
-_i18n_set zh loop.roll_brief_daily_at_02d_02d "每天 %02d:%02d\n"
+_i18n_set en loop.roll_loop_s_active_02d_00 "  • roll-loop   %s  active %02d:00–%02d:00  %s（窗口 %02d:00–%02d:00）"
+_i18n_set zh loop.roll_loop_s_active_02d_00 "  • roll-loop   %s  有效窗口 %02d:00–%02d:00  %s（active %02d:00–%02d:00）"
+_i18n_set en loop.roll_dream_daily_at_02d_02d "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_dream_daily_at_02d_02d "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set en loop.roll_brief_daily_at_02d_02d "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_brief_daily_at_02d_02d "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
 _i18n_set en loop.loop_already_enabled_for_this_project_2 "Loop already enabled for this project"
 _i18n_set zh loop.loop_already_enabled_for_this_project_2 "当前项目 loop 已启用"
 _i18n_set en loop.loop_enabled_2 "Loop enabled"
 _i18n_set zh loop.loop_enabled_2 "已启用"
-_i18n_set en loop.roll_loop_s_active_02d_00_2 "  • roll-loop   %s  active %02d:00–%02d:00  %s（"
-_i18n_set zh loop.roll_loop_s_active_02d_00_2 "窗口 %02d:00–%02d:00）\n"
-_i18n_set en loop.roll_dream_daily_at_02d_02d_2 "  • roll-.dream daily at %02d:%02d"
-_i18n_set zh loop.roll_dream_daily_at_02d_02d_2 "每天 %02d:%02d\n"
-_i18n_set en loop.roll_brief_daily_at_02d_02d_2 "  • roll-brief  daily at %02d:%02d"
-_i18n_set zh loop.roll_brief_daily_at_02d_02d_2 "每天 %02d:%02d\n"
+_i18n_set en loop.roll_loop_s_active_02d_00_2 "  • roll-loop   %s  active %02d:00–%02d:00  %s（窗口 %02d:00–%02d:00）"
+_i18n_set zh loop.roll_loop_s_active_02d_00_2 "  • roll-loop   %s  有效窗口 %02d:00–%02d:00  %s（active %02d:00–%02d:00）"
+_i18n_set en loop.roll_dream_daily_at_02d_02d_2 "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_dream_daily_at_02d_02d_2 "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set en loop.roll_brief_daily_at_02d_02d_2 "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_brief_daily_at_02d_02d_2 "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
 _i18n_set en loop.loop_not_enabled_for_this_project "Loop not enabled for this project"
 _i18n_set zh loop.loop_not_enabled_for_this_project "当前项目 loop 未启用"
 _i18n_set en loop.loop_disabled "Loop disabled"

package/lib/prices/README.md

@@ -0,0 +1,35 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/prices/ — Model price snapshots
+
+Dated JSON snapshots of AI model list prices, used by `roll loop status` to compute per-cycle cost in both USD and native currency (CNY for pi/DeepSeek/Kimi).
+
+## Files
+
+| File | Contents |
+|------|---------|
+| `snapshot-2026-05-22.json` | Multi-vendor snapshot (Claude, GPT, Gemini, DeepSeek, Kimi, pi) |
+| `snapshot-2026-05-23-deepseek.json` | DeepSeek-specific refresh |
+| `snapshot-2026-05-23-kimi.json` | Kimi-specific refresh |
+
+## Format
+
+Each snapshot is a JSON object keyed by model ID:
+
+```json
+{
+  "claude-opus-4-7": {
+    "input_per_mtok": 15.0,
+    "output_per_mtok": 75.0,
+    "cache_write_per_mtok": 18.75,
+    "cache_read_per_mtok": 1.5,
+    "currency": "USD"
+  }
+}
+```
+
+CNY-priced models (pi, DeepSeek, Kimi) use `"currency": "CNY"`.
+
+## Refresh
+
+`prices_fetcher.py` fetches fresh snapshots from vendor pricing APIs and writes a new dated file here. Run via `roll prices refresh`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.528.2",
+  "version": "2026.529.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"