@seanyao/roll 2026.528.1 → 2026.529.1

package/CHANGELOG.md

@@ -1,14 +1,39 @@
 # Changelog
 
-## v2026.528.1
+## v2026.529.1
 
 ### Added
 
-- **`roll test` — 测试隔离运行，不再误伤本机 loop 服务** `[loop]`
+- **loop 运行时间可以按项目设** — 不用再全局迁就
 
 ### Fixed
 
-- **Kimi CLI 升级改名为 kimi-code 后，roll 现在能正常识别** `[loop]`
+- **`roll loop on` 不再显示全 00:00** — 时间显示正常了
+- **agent 检测不再误报** — 没装的工具不会被当成可用
+
+## v2026.528.2
+
+### Added
+
+- **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 把工具从 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.1"
+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"
@@ -747,6 +850,22 @@ _setup_snapshot() {
 # _ROLL_SETUP_STATE. Caller passes the watch dir(s) plus the command + args.
 # stdout/stderr of the inner command are suppressed (same as the previous
 # pattern in cmd_setup) to keep the v2 UI render the only user-visible output.
+# US-INFRA-008: ensure core.hooksPath is set to 'hooks' so TCR pre-commit gate
+# is never silently bypassed in new clones, worktrees, or automated environments.
+# Idempotent: already set to a non-default value → leave it (user knows better).
+# Not a git repo → silently skip.
+_ensure_hooks_path() {
+  local repo_path="${1:-$PWD}"
+  # Must be a git repo
+  git -C "$repo_path" rev-parse --git-dir >/dev/null 2>&1 || return 0
+  local current; current=$(git -C "$repo_path" config core.hooksPath 2>/dev/null || echo "")
+  # Only set when unset or pointing at the git default (.git/hooks)
+  if [[ -z "$current" || "$current" == ".git/hooks" ]]; then
+    git -C "$repo_path" config core.hooksPath hooks 2>/dev/null || true
+  fi
+  return 0
+}
+
 _run_setup_step() {
   local watch="$1"; shift
   local before after
@@ -803,6 +922,10 @@ cmd_setup() {
   _run_setup_step "$ROLL_HOME/.peer-state" _peer_ensure_state_dir
   _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Initialize peer-review state directory"
 
+  # US-INFRA-008: configure git hooks path so TCR pre-commit gate works in this repo
+  _run_setup_step "$PWD" _ensure_hooks_path
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Configure git hooks path"
+
   if command -v tmux >/dev/null 2>&1; then
     _record skip "Ensure tmux is installed (already present)"
   else
@@ -907,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
@@ -1447,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.
@@ -2719,7 +2894,7 @@ _peer_dispatch_in_tmux() {
   {
     printf '#!/bin/bash -l\n'
     # FIX-050: portable PATH assembly (was hardcoded /opt/homebrew/bin)
-    printf 'for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "$HOME/.local/bin"; do\n'
+    printf 'for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "$HOME/.local/bin" "$HOME/.kimi-code/bin"; do\n'
     printf '  case ":$PATH:" in *":$_d:"*) ;; *) [ -d "$_d" ] && PATH="$_d:$PATH" ;; esac\n'
     printf 'done; export PATH\n'
     printf '%s > %q 2> %q || true\n' "$cmd_str" "$out_file" "$err_file"
@@ -4604,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"
@@ -4660,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"
 }
@@ -4675,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
@@ -4686,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.
@@ -4790,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).
@@ -4835,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[@]}"
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -5411,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
@@ -5563,6 +5775,8 @@ _detect_path_prepend() {
   [[ -d /usr/local/bin ]] && dirs+=("/usr/local/bin")
   [[ -d /opt/local/bin ]] && dirs+=("/opt/local/bin")
   [[ -d "$HOME/.local/bin" ]] && dirs+=("$HOME/.local/bin")
+  # FIX-129: kimi-code installs to ~/.kimi-code/bin (not brew/local), launchd misses it
+  [[ -d "$HOME/.kimi-code/bin" ]] && dirs+=("$HOME/.kimi-code/bin")
   dirs+=("/usr/bin" "/bin" "/usr/sbin" "/sbin")
   for d in "${dirs[@]}"; do
     case ":$seen:" in *":$d:"*) continue ;; esac
@@ -5728,7 +5942,7 @@ set -o pipefail
 # FIX-050: portable PATH assembly — launchd/cron deliver a bare PATH that
 # misses brew-installed tools (tmux, claude, node, …). Iterate candidate
 # dirs; only prepend when present and not already in PATH. Idempotent.
-for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin"; do
+for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin" "\$HOME/.kimi-code/bin"; do
   case ":\$PATH:" in *":\$_d:"*) ;; *) [ -d "\$_d" ] && PATH="\$_d:\$PATH" ;; esac
 done
 export PATH
@@ -6061,6 +6275,10 @@ _phase_begin startup
 _phase_end startup ok
 _phase_begin preflight
 cd "${project_path}" 2>/dev/null || true
+# US-INFRA-008: ensure git hooks are wired so TCR pre-commit gate can't be bypassed
+_ensure_hooks_path "${project_path}" 2>/dev/null || true
+# US-LOOP-056: sync .roll/ meta from roll-meta remote before backlog scan
+_loop_sync_meta "${project_path}" || 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.
@@ -6372,7 +6590,7 @@ INNER
 # FIX-050: portable PATH assembly before any brew-tool lookup (tmux, caffeinate
 # on some systems, claude). Mirrors the inner script's bootstrap so even when
 # launchd's plist EnvironmentVariables is stale, the runner self-repairs.
-for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin"; do
+for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin" "\$HOME/.kimi-code/bin"; do
   case ":\$PATH:" in *":\$_d:"*) ;; *) [ -d "\$_d" ] && PATH="\$_d:\$PATH" ;; esac
 done
 export PATH
@@ -6459,10 +6677,24 @@ if command -v tmux >/dev/null 2>&1; then
   tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^roll-loop-${slug}\$" | while read _s; do
     tmux kill-session -t "\$_s" 2>/dev/null || true
   done
-  tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
-  CYCLE_LOG_RAW="${project_path}/.roll/cycle-logs/.pipe-\$\$.raw"
+  # FIX-132: syntax-check the inner script before spawning the tmux session.
+  # A heredoc quoting regression or mid-cycle regeneration can silently produce
+  # a syntactically broken script; catching it here prevents the session from
+  # starting in a corrupted state and logging a misleading "exited 0, retrying".
+  if ! bash -n "\$INNER_SCRIPT" 2>>"\$LOG"; then
+    echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] ABORT: inner script failed syntax check — cycle skipped (see log: \$LOG)" >> "\$LOG"
+    exit 1
+  fi
+  # FIX-130: export ROLL_CYCLE_LOG_RAW BEFORE spawning the tmux session so
+  # the inner script inherits it (env vars are inherited at spawn time, not
+  # retroactively — exporting after new-session means inner never sees it and
+  # _inner_cleanup skips log archiving, leaving only orphan .pipe-*.raw files).
   mkdir -p "${project_path}/.roll/cycle-logs"
+  # Clean orphan .pipe-*.raw files from previous crashed cycles
+  find "${project_path}/.roll/cycle-logs" -name '.pipe-*.raw' -delete 2>/dev/null || true
+  CYCLE_LOG_RAW="${project_path}/.roll/cycle-logs/.pipe-\$\$.raw"
   export ROLL_CYCLE_LOG_RAW="\$CYCLE_LOG_RAW"
+  tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
   tmux pipe-pane -t "\$SESSION" "tee -a \"\$LOG\" >> \"\$ROLL_CYCLE_LOG_RAW\""
   # 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.
@@ -6481,7 +6713,9 @@ if command -v tmux >/dev/null 2>&1; then
     # window closes the instant the tmux session ends (cycle_end kills
     # the session) and the entire scrollback disappears with it; the
     # cron-<slug>.log file still has the full transcript as a fallback.
-    printf '#!/bin/bash\\ntmux attach -t %s\\necho\\necho "================================================================"\\necho "  cycle ended. log: ~/.shared/roll/loop/cron-%s.log"\\necho "  press enter to close this window."\\necho "================================================================"\\nread _\\n' \\
+    # FIX-131: after tmux session ends, open the cron log with less so the
+    # user can scroll through the full cycle output instead of seeing nothing.
+    printf '#!/bin/bash\\ntmux attach -t %s 2>/dev/null\\nLOGFILE=~/.shared/roll/loop/cron-%s.log\\necho\\nif [ -f "\$LOGFILE" ]; then\\n  echo "================================================================"\\n  echo "  Cycle ended  —  showing log (arrows to scroll, q to close)"\\n  echo "================================================================"\\n  less -R +G "\$LOGFILE"\\nelse\\n  echo "================================================================"\\n  echo "  Cycle ended. Log not found: \$LOGFILE"\\n  echo "  press enter to close."\\n  echo "================================================================"\\n  read _\\nfi\\n' \\
       "\$SESSION" "${slug}" > "\$_attach_cmd" 2>/dev/null || true
     chmod +x "\$_attach_cmd" 2>/dev/null || true
     open -g -a Terminal "\$_attach_cmd" >/dev/null 2>&1 || true
@@ -6583,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%% *}"
@@ -6710,10 +6944,11 @@ cmd_loop() {
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
     gc)      shift; _loop_gc "$@" ;;
-    notify)       _notify "${1:-roll}" "${2:-}" ;;
-    enforce-tcr)  _loop_enforce_tcr "${1:-}" "${2:-}" ;;
-    precheck-ci)  _loop_precheck_ci ;;
-    branches)     _loop_branches "$(pwd -P)" ;;
+    notify)               _notify "${1:-roll}" "${2:-}" ;;
+    enforce-tcr)          _loop_enforce_tcr "${1:-}" "${2:-}" ;;
+    precheck-ci)          _loop_precheck_ci ;;
+    hotfix-head-context)  _loop_hotfix_head_context "${1:-}" ;;
+    branches)             _loop_branches "$(pwd -P)" ;;
     *)  cat <<'HELP'
 Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mute|unmute|pause|resume|reset|gc|branches>
 
@@ -6759,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")
@@ -6806,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
@@ -6837,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>)"
 }
 
@@ -6980,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" \
@@ -7741,6 +7976,66 @@ _ci_wait() {
 }
 
 # Pre-run CI health check — call before picking up new stories.
+# US-LOOP-056: sync .roll/ (roll-meta private submodule) before each cycle so
+# the cycle always runs against the latest backlog. Fail-soft: any error emits
+# a meta_sync event and returns 0 so the cycle continues with stale/existing meta.
+#
+# Statuses emitted via _loop_event meta_sync:
+#   ok      – fetch + reset --hard succeeded
+#   stale   – fetch failed; existing .roll/ used as fallback
+#   skipped – no git remote configured (not a roll-meta managed project)
+#
+# Env override: ROLL_LOOP_META_SYNC_TIMEOUT (default 15) controls fetch timeout.
+_loop_sync_meta() {
+  local project_path="$1"
+  local roll_meta="${project_path}/.roll"
+  local timeout_sec="${ROLL_LOOP_META_SYNC_TIMEOUT:-15}"
+  local cid="${CYCLE_ID:-unknown}"
+  local slug="${_LOOP_PROJ_SLUG:-$(_project_slug 2>/dev/null || echo unknown)}"
+  local shared_dir="${_SHARED_ROOT:-$HOME/.shared/roll}/loop"
+  local fail_counter="${shared_dir}/meta-sync-fail-${slug}"
+
+  # Detect remote via the canonical probe point. If .roll/ has no .git or no
+  # remote configured, treat as "not managed" and skip silently.
+  local remote_url
+  remote_url=$(git -C "$roll_meta" remote get-url origin 2>/dev/null || echo "")
+  if [ -z "$remote_url" ]; then
+    return 0
+  fi
+
+  # Attempt fetch with timeout
+  local _fetch_ok=0
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$timeout_sec" git -C "$roll_meta" fetch --quiet 2>/dev/null && _fetch_ok=1
+  else
+    git -C "$roll_meta" fetch --quiet 2>/dev/null && _fetch_ok=1
+  fi
+
+  if [ "$_fetch_ok" -eq 1 ]; then
+    if git -C "$roll_meta" reset --hard origin/main --quiet 2>/dev/null; then
+      _loop_event meta_sync "$cid" "ok" "" 2>/dev/null || true
+      # US-LOOP-057: reset consecutive failure counter on success
+      rm -f "$fail_counter" 2>/dev/null || true
+      return 0
+    fi
+  fi
+
+  # Fetch or reset failed — stale .roll/ used; cycle continues
+  _loop_event meta_sync "$cid" "stale" "fetch/reset failed" 2>/dev/null || true
+
+  # US-LOOP-057: increment failure counter; write ALERT after 3 consecutive failures
+  mkdir -p "$shared_dir" 2>/dev/null || true
+  local count=0
+  [ -f "$fail_counter" ] && count=$(cat "$fail_counter" 2>/dev/null || echo 0)
+  count=$(( count + 1 ))
+  printf '%s\n' "$count" > "$fail_counter"
+  if [ "$count" -ge 3 ]; then
+    printf '[%s] roll-meta sync consecutive failures: %d times. Check SSH key / network.\n  Last error: fetch/reset failed for %s\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$count" "$remote_url" >> "${shared_dir}/ALERT-${slug}.md" 2>/dev/null || true
+  fi
+  return 0
+}
+
 # Refuses to build on a red base (HEAD CI failed). Lenient on unknown states
 # (gh missing, repo unparseable, no runs yet) — the post-build _loop_enforce_ci
 # is the strict gate.
@@ -7773,6 +8068,38 @@ _loop_precheck_ci() {
     run_states=$(echo "$runs" \
       | jq -r '[.[] | "\(.status // "?")/\(.conclusion // "null")"] | unique | join(", ")' \
       2>/dev/null || echo "?")
+
+    # US-LOOP-046/048: check whether hot-fix path is allowed before aborting.
+    # ROLL_LOOP_NO_HEAL=1 or ROLL_LOOP_HEAL_MAX=0 → fall through to original abort.
+    local _heal_max="${ROLL_LOOP_HEAL_MAX:-2}"
+    if [[ "${ROLL_LOOP_NO_HEAL:-}" != "1" ]] && [[ "$_heal_max" -gt 0 ]]; then
+      local _state_file="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/state-${_LOOP_PROJ_SLUG:-$(basename "$PWD")}.yaml"
+      local _heal_key="heal_count_head_${commit:0:8}"
+      local _count=0
+      [[ -f "$_state_file" ]] && _count=$(grep "^${_heal_key}:" "$_state_file" 2>/dev/null | awk '{print $2}' || echo 0)
+      _count=$(( ${_count:-0} + 0 ))  # coerce to int
+      if [[ "$_count" -lt "$_heal_max" ]]; then
+        # Increment counter and signal hot-fix path to the agent
+        _count=$(( _count + 1 ))
+        mkdir -p "$(dirname "$_state_file")" 2>/dev/null || true
+        if [[ -f "$_state_file" ]]; then
+          # Update existing key or append
+          if grep -q "^${_heal_key}:" "$_state_file" 2>/dev/null; then
+            local _tmp; _tmp=$(mktemp)
+            grep -v "^${_heal_key}:" "$_state_file" > "$_tmp" 2>/dev/null || true
+            printf '%s: %d\n' "$_heal_key" "$_count" >> "$_tmp"
+            mv "$_tmp" "$_state_file"
+          else
+            printf '%s: %d\n' "$_heal_key" "$_count" >> "$_state_file"
+          fi
+        else
+          printf '%s: %d\n' "$_heal_key" "$_count" > "$_state_file"
+        fi
+        # Exit 2 signals the agent: CI is red, hot-fix path is available
+        return 2
+      fi
+    fi
+
     err "$(msg loop.pre_run_ci_check_head_ci ${short})"
     mkdir -p "$(dirname "$_LOOP_ALERT")"
     cat > "$_LOOP_ALERT" << EOF
@@ -7795,6 +8122,62 @@ EOF
   return 0
 }
 
+# US-LOOP-047: hot-fix context factory for HEAD CI failures.
+# Captures failing run logs + recent commit diff, writes to /tmp/roll-heal-head-<sha>.log
+# Returns 0 and prints the log path on success; 1 if context could not be gathered.
+_loop_hotfix_head_context() {
+  local commit="${1:-$(git rev-parse HEAD 2>/dev/null)}"
+  [[ -z "$commit" ]] && return 1
+  local short="${commit:0:8}"
+  local outfile="/tmp/roll-heal-head-${short}.log"
+  local slug; _gh_resolve slug || slug="unknown"
+
+  {
+    printf '=== CI Hot-fix Context: HEAD %s ===\n\n' "$short"
+    printf '--- Recent commits ---\n'
+    git log --oneline -5 2>/dev/null || true
+    printf '\n--- Diff of last commit ---\n'
+    git show --stat HEAD 2>/dev/null | head -40 || true
+    printf '\n--- CI failure logs (head 200 lines) ---\n'
+    local run_id
+    run_id=$(gh -R "$slug" run list --commit "$commit" \
+      --json databaseId,conclusion -L 5 2>/dev/null \
+      | jq -r '.[] | select(.conclusion=="failure") | .databaseId' 2>/dev/null | head -1)
+    if [[ -n "$run_id" ]]; then
+      gh -R "$slug" run view --log-failed "$run_id" 2>/dev/null | head -200 || true
+    else
+      printf '(no failed run found for commit %s)\n' "$short"
+    fi
+  } > "$outfile" 2>/dev/null
+  printf '%s\n' "$outfile"
+  return 0
+}
+
+# US-LOOP-050: PR hot-fix entry point.
+# Checks out the PR branch, captures CI failure logs, and prepares context
+# for a roll-fix invocation on the PR branch.
+# Usage: _loop_hot_fix_pr <pr_number>
+_loop_hot_fix_pr() {
+  local pr_num="$1"
+  [[ -z "$pr_num" ]] && return 1
+  local slug; _gh_resolve slug || return 1
+  local outfile="/tmp/roll-heal-pr-${pr_num}.log"
+  local run_id
+  run_id=$(gh -R "$slug" run list --json databaseId,conclusion,headBranch -L 20 2>/dev/null \
+    | jq -r --argjson pr "\"$pr_num\"" \
+      '.[] | select(.conclusion=="failure") | .databaseId' 2>/dev/null | head -1)
+  {
+    printf '=== PR #%s CI Hot-fix Context ===\n\n' "$pr_num"
+    if [[ -n "$run_id" ]]; then
+      gh -R "$slug" run view --log-failed "$run_id" 2>/dev/null | head -200 || true
+    else
+      printf '(no failed run found for PR #%s)\n' "$pr_num"
+    fi
+  } > "$outfile" 2>/dev/null
+  printf '%s\n' "$outfile"
+  return 0
+}
+
 # _loop_diagnose_open_prs <slug>
 #   Appended to ALERT when CI is red on HEAD.
 #   For each open PR targeting main: lists CI failing tests + changed files,
@@ -8029,7 +8412,14 @@ _loop_pr_classify() {
   local mergeable="${4:-}"
 
   case "$head_ref" in
-    loop/*) echo "loop_self"; return 0 ;;
+    loop/*)
+      # US-LOOP-049: loop/* PRs with CI failure get their own classification
+      # so _loop_pr_inbox can route them to the PR hot-fix path.
+      if [[ "$ci_state" == "failure" ]]; then
+        echo "loop_self_ci_red"; return 0
+      fi
+      echo "loop_self"; return 0
+      ;;
   esac
 
   case "$human_review" in
@@ -9109,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")
@@ -9980,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.1",
+  "version": "2026.529.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-loop/SKILL.md

@@ -125,16 +125,26 @@ readers. The rule mirrors the gate in Step 2.
 ### Step 1.5 — Pre-run CI Health Check
 
 Call `roll loop precheck-ci` before scanning BACKLOG. This is a **defensive gate**
-against building on a broken base — if the most recent commit on the branch
-has red CI, the loop must not stack new commits on top (which would create the
-exact stuck-red state FIX-026 traces to).
-
-- HEAD CI green / pending / no-run-yet → proceed to Step 2.
-- HEAD CI red → write ALERT, **do not pick up any stories this cycle**,
-  exit cleanly. The next cycle will retry; the human must fix CI manually
-  (typically by reverting or pushing a green commit) before the loop resumes.
-- `gh` missing or repo unparseable → graceful skip (`roll loop precheck-ci`
-  returns 0); the post-build `_loop_enforce_ci` remains the strict gate.
+against building on a broken base. Check the **exit code** and route accordingly:
+
+| Exit code | Meaning | Action |
+|-----------|---------|--------|
+| `0` | CI green / pending / unknown | Proceed to Step 1.6 (PR Inbox) and Step 2 (BACKLOG scan) |
+| `1` | CI red AND heal exhausted or `ROLL_LOOP_NO_HEAL=1` | ALERT already written; exit cleanly this cycle |
+| `2` | CI red AND heal attempt allowed (US-LOOP-046) | **Hot-fix path** — skip BACKLOG, fix CI instead (see below) |
+
+`gh` missing or repo unparseable → `precheck-ci` returns `0`; graceful skip.
+
+**Hot-fix path (exit code 2) — US-LOOP-046:**
+
+Do NOT pick any BACKLOG stories this cycle. Instead:
+
+1. Capture context: `roll loop hotfix-head-context` → prints path to context log
+2. Invoke `Skill("roll-fix")` with brief:
+   `"CI red on HEAD. Failing run logs at <context-log-path>. Diagnose root cause, fix via TCR, commit, push. Do NOT change BACKLOG status."`
+3. After `roll-fix` completes, re-run `roll ci --wait` to verify the fix
+4. If CI is still red: run `roll loop precheck-ci` again; if it returns `1` (heal exhausted),
+   exit cleanly — ALERT was already written by the precheck
 
 ### Step 1.6 — PR Inbox (US-AUTO-034)