@seanyao/roll 2026.511.6 → 2026.511.8

package/CHANGELOG.md

@@ -1,40 +1,42 @@
 # Changelog
 
-## v2026.511.8
-- **Fixed**: 集成测试 launchd ghost 泄漏 — `integration_teardown` 在删除 TEST_TMP 之前，先 `launchctl bootout` 该沙箱里被 `roll loop on` 注册到 user gui domain 的所有 `com.roll.*` 服务，避免删 plist 后 launchd 仍保留指向不存在路径的 ghost 注册。
+## Unreleased
+- **Fixed**: `roll loop attach` 不再黑屏，AI 干活过程实时可见
 
 ## v2026.511.7
-- **Added**: loop 执行 story 前显式标记 🔨 In Progress — roll-loop SKILL 在调用 executor 之前先把 BACKLOG 中的故事状态从 📋 Todo 改为 🔨 In Progress 并提交 `chore: mark US-XXX in progress`，brief 简报和 peer agent 都能即时感知正在进行的工作，tcr 微提交不再"对 brief 不可见"。
-- **Added**: loop 启动时孤儿 🔨 自愈 — 扫描 BACKLOG 中无对应 state.yaml running item 的 🔨 条目，视为上次崩溃残留，自动 revert 回 📋 Todo 并写 ALERT，避免被"卡"在错误的中间状态里。
-- **Improved**: roll-build / roll-fix SKILL 状态转换段更新 — 显式接受 📋 Todo 或 🔨 In Progress 作为 ✅ Done 前置状态，loop 触发链路状态过渡更稳健。
+- **Added**: loop 跑起来时自动弹出一个终端窗口，看 AI 实时干活
+- **Added**: `roll loop mute` 关掉自动弹窗，`roll loop unmute` 恢复
+- **Added**: `roll loop runs` — 查看 loop 最近几次都跑了什么
+- **Added**: `roll loop attach` — 随时接入正在跑的 loop 现场围观
+- **Added**: BACKLOG 任务执行中会实时显示 🔨 进度，不用等做完才知道
+- **Added**: `roll setup` 自动安装 tmux（macOS 通过 brew）
+- **Improved**: 代码巡检（dream）报告改为中文输出
+- **Fixed**: loop 在某些情况下完成后不正常退出
+- **Fixed**: loop 中途崩溃后下次启动会自动清理残留状态
 
 ## v2026.511.6
-- **Added**: Loop 并发安全 — runner script 启动时写入 per-project LOCK 文件并检测重入；活跃 PID 已存在则跳过本次，残留死 LOCK 自动清理；正常/异常退出均通过 trap 清掉 LOCK。彻底防止两个 loop 实例同时启动造成的 BACKLOG/git 冲突。
-- **Added**: roll-loop SKILL 显式声明 skip-🔨 In Progress 语义 — claude 扫 BACKLOG 时跳过已被人工或 peer agent 标记的执行中条目，为人机协同和多 agent 协作奠定基础。
-- **Fixed**: 5 个 pre-existing 测试失败 — `run_roll` helper 切换到 TEST_TMP 作为 cwd 避免 slug 冲突；loop status 测试匹配三态显示新文案；dashboard 测试匹配 `_launchd_svc_state` + array 派生 schedule 的新结构。
+- **Fixed**: 多个 loop 实例不会再因为定时重复触发而互相打架
 
 ## v2026.511.5
-- **Fixed**: launchd plist 自动 reload — plist 内容变更且服务已加载时自动 unload + reload，升级 roll 后 loop 服务立即生效，无需手动重启
-- **Improved**: roll loop status/monitor 三态展示 — 区分 ● 运行中 / ⚠ 已安装未加载 / ○ 未安装，并给出对应的自愈操作提示
+- **Fixed**: 升级 roll 后 loop 服务自动生效，无需手动重启
+- **Improved**: `roll loop status` 三态显示，看得清是真没装、装了没启、还是在跑
 
 ## v2026.511.4
-- **Fixed**: roll init 自动重建 launchd runner scripts — 升级 roll 后直接跑 `roll init` 即可迁移到独立 runner，无需手动执行 roll setup 或 roll loop on
+- **Fixed**: 升级 roll 后 `roll init` 自动迁移 loop 配置，少一步手动操作
 
 ## v2026.511.3
-- **Fixed**: loop/dream/brief 多项目运行隔离 — 共享 run.sh 导致所有项目的 loop 在同一目录执行，改为每个项目独立 runner 脚本（run-{slug}.sh），彻底隔离多项目并发执行环境
-- **Fixed**: roll release 自发版拦截 — 在 roll 自身项目执行 `roll release` 时自动拦截并提示改用 scripts/release.sh，防止误操作绕过 2FA
+- **Fixed**: 多个项目同时跑 loop，互不干扰
+- **Fixed**: 在 roll 项目里运行 `roll release` 会提示改用 `scripts/release.sh`
 
 ## v2026.511.2
-- **Added**: roll loop monitor 三服务状态 — 监控台新增 loop/dream/brief 三个 launchd 服务的运行状态、调度时间和实时 log tail，一屏掌握全局执行情况
-- **Fixed**: dashboard 多处展示问题 — 修复 pending_count 算术错误、brief 内联显示 release readiness、移除底部冗余命令列表
-- **Fixed**: loop 异常退出后 state 未重置 — 防止 queue 卡住导致后续任务无法执行
-- **Fixed**: CI 稳定性 — 修复 _notify_update 裸返回和时间断言，消除环境差异引起的随机失败
-- **Improved**: roll-brief 输出格式 — 序号命名、省略空 section、元信息格式精简，减少无效噪音
+- **Added**: `roll loop monitor` — 一屏看 loop/dream/brief 三个调度服务状态
+- **Fixed**: dashboard 待办数、release 状态显示问题
+- **Fixed**: loop 异常退出后队列卡住不再继续执行
+- **Improved**: 简报输出更精简，去掉空白段落和冗余信息
 
 ## v2026.511.1
-- **Changed**: roll loop 调度器切换到 launchd（macOS）— `roll setup` 自动安装 loop/dream/brief 三个 launchd 服务（默认关闭），`roll loop on/off/status` 统一走 launchctl 管理，幂等安装，Linux 保留 crontab 回退路径
-- **Added**: roll-loop TCR 硬校验 — 故事完成后自动统计 `tcr:` 微提交数量，为 0 时将故事状态回退为 📋 Todo 并写 ALERT，防止 agent 跳过 TCR 节奏
-- **Fixed**: CI 测试环境兼容 — 移除依赖本地 state.yaml 的 hello_world.bats，修复 GitHub Actions 持续失败
+- **Changed**: macOS 上 loop 调度切换到 launchd，比 crontab 更稳定
+- **Added**: agent 跳过 TCR 节奏时自动拦回 Todo，强制重做
 
 ## v2026.510.10
 - **Fixed**: release.sh changelog 同步时序修复 — 修正条件逻辑和执行顺序，确保每次发版时 changelog 正确更新

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.511.6"
+VERSION="2026.511.8"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -531,6 +531,35 @@ _sync_skills() {
 # COMMAND: setup [--force]
 # Initialize ~/.roll/ and sync everything to AI tools in one step
 # ═══════════════════════════════════════════════════════════════════════════════
+# Ensures tmux is available (US-AUTO-026 promoted it from soft to required
+# dependency for visible loop runs). On macOS attempts `brew install tmux`
+# when brew exists; elsewhere prints the install command. Never fails the
+# setup main flow — returns 0 even if install was not possible so the rest
+# of `roll setup` proceeds.
+_ensure_tmux() {
+  if command -v tmux >/dev/null 2>&1; then
+    return 0
+  fi
+
+  local os; os="$(uname)"
+  if [[ "$os" == "Darwin" ]]; then
+    if command -v brew >/dev/null 2>&1; then
+      info "tmux not found — installing via brew...  未安装 tmux，正在通过 brew 安装..."
+      if brew install tmux >/dev/null 2>&1; then
+        ok "tmux installed.  tmux 已安装。"
+        return 0
+      fi
+      warn "brew install tmux failed — install manually: brew install tmux  brew 安装失败，请手动 'brew install tmux'"
+      return 0
+    fi
+    warn "tmux required but brew not available — install manually: brew install tmux  缺少 brew，请手动 'brew install tmux'"
+    return 0
+  fi
+
+  warn "tmux required — install via your package manager (e.g. apt install tmux / pacman -S tmux)  请用系统包管理器安装 tmux"
+  return 0
+}
+
 cmd_setup() {
   local force=false
   while [[ $# -gt 0 ]]; do
@@ -555,6 +584,10 @@ cmd_setup() {
   _peer_ensure_state_dir
   ok "Peer state directory ready.  Peer 状态目录已就绪。"
 
+  echo ""
+  info "Ensuring tmux is installed (required for visible loop runs)...  正在确认 tmux 已安装..."
+  _ensure_tmux
+
   if [[ "$(uname)" == "Darwin" ]]; then
     echo ""
     info "Installing launchd plists...  正在安装 LaunchAgents..."
@@ -1751,6 +1784,8 @@ _LOOP_TAG="# roll-loop"
 _SHARED_ROOT="${HOME}/.shared/roll"
 _LOOP_STATE="${HOME}/.shared/roll/loop/state.yaml"
 _LOOP_ALERT="${HOME}/.shared/roll/loop/ALERT.md"
+_LOOP_RUNS="${HOME}/.shared/roll/loop/runs.jsonl"
+_LOOP_MUTE_FILE="${HOME}/.shared/roll/mute"
 _LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
 
 # Returns a filesystem-safe slug combining the project basename and a 6-char
@@ -1847,26 +1882,64 @@ _write_runner_script() {
 
 # Like _write_runner_script but prepends an active window guard.
 # Silently exits when current hour is outside [active_start, active_end).
+# When tmux is available, wraps the inner command in a detached tmux session
+# named `roll-loop-<slug>` so `roll loop attach` can watch in real time.
+# 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}"
   mkdir -p "$(dirname "$script_path")"
+
+  local inner_path="${script_path%.sh}-inner.sh"
+  # Inject --verbose into `claude -p` so the tmux-attach view shows live
+  # tool-use and reasoning events (loop is launchd-triggered, the user is
+  # not driving it — visibility is required, not optional).
+  local cmd_verbose="${cmd/claude -p/claude --verbose -p}"
+  cat > "$inner_path" << INNER
+#!/bin/bash -l
+export PATH="/opt/homebrew/bin:\$PATH"
+cd "${project_path}" && ${cmd_verbose}
+INNER
+  chmod +x "$inner_path"
+
   cat > "$script_path" << SCRIPT
 #!/bin/bash -l
 h=\$(printf '%d' "\$(date +%H)")
 if [ "\$h" -lt ${active_start} ] || [ "\$h" -ge ${active_end} ]; then exit 0; fi
 LOCK="\$(dirname "\$0")/.LOCK-\$(basename "\$0" .sh | sed 's/^run-//')"
+SESSION="roll-loop-\$(basename "\$0" .sh | sed 's/^run-//')"
+INNER_SCRIPT="${inner_path}"
+LOG="${log_path}"
 if [ -f "\$LOCK" ]; then
   prev_pid=\$(head -1 "\$LOCK" 2>/dev/null || echo "")
   if [ -n "\$prev_pid" ] && kill -0 "\$prev_pid" 2>/dev/null; then
-    echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] loop already running (PID \$prev_pid), skipping" >> "${log_path}"
+    echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] loop already running (PID \$prev_pid), skipping" >> "\$LOG"
     exit 0
   fi
   rm -f "\$LOCK"
 fi
 echo "\$\$" > "\$LOCK"
 trap 'rm -f "\$LOCK"' EXIT
-cd "${project_path}" && ${cmd} >> "${log_path}" 2>&1
+if command -v tmux >/dev/null 2>&1; then
+  tmux kill-session -t "\$SESSION" 2>/dev/null || true
+  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 [ ! -f "\$HOME/.shared/roll/mute" ] && [ "\$(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) &
+  fi
+  while tmux has-session -t "\$SESSION" 2>/dev/null; do sleep 5; done
+else
+  bash "\$INNER_SCRIPT" >> "\$LOG" 2>&1
+fi
 SCRIPT
   chmod +x "$script_path"
 }
@@ -1978,9 +2051,13 @@ cmd_loop() {
     now)     _loop_now ;;
     status)  _loop_status ;;
     monitor) _loop_monitor "${1:-3}" ;;
+    runs)    _loop_runs "$@" ;;
+    attach)  _loop_attach ;;
+    mute)    _loop_mute ;;
+    unmute)  _loop_unmute ;;
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
-    *) err "Usage: roll loop <on|off|now|status|monitor|resume|reset>"; exit 1 ;;
+    *) err "Usage: roll loop <on|off|now|status|monitor|runs|attach|mute|unmute|resume|reset>"; exit 1 ;;
   esac
 }
 
@@ -2118,6 +2195,12 @@ _loop_status() {
       echo -e "  Scheduler  ${YELLOW}○ disabled${NC}   run: roll loop on"
     fi
   fi
+  echo ""
+  if [[ -f "$_LOOP_MUTE_FILE" ]]; then
+    echo -e "  Auto-attach  ${YELLOW}muted${NC}   run: roll loop unmute"
+  else
+    echo -e "  Auto-attach  ${GREEN}live${NC}    run: roll loop mute"
+  fi
   [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT:${NC}"; sed 's/^/    /' "$_LOOP_ALERT"; }
   [[ -f "$_LOOP_STATE" ]] && { echo ""; echo "  State:"; sed 's/^/    /' "$_LOOP_STATE"; }
   echo ""
@@ -2143,6 +2226,138 @@ _loop_reset() {
   fi
 }
 
+# Suppress the auto-attach popup. When the marker file exists, runner scripts
+# skip the osascript Terminal-popup step on next fire. Loop output still goes
+# to tmux + log; users can run `roll loop attach` manually.
+_loop_mute() {
+  mkdir -p "$(dirname "$_LOOP_MUTE_FILE")"
+  : > "$_LOOP_MUTE_FILE"
+  ok "🔇 muted — auto-attach disabled  已静音，自动弹窗已关闭"
+}
+
+# Re-enable the auto-attach popup.
+_loop_unmute() {
+  rm -f "$_LOOP_MUTE_FILE"
+  ok "🔔 unmuted — auto-attach live  已恢复，自动弹窗已开启"
+}
+
+# Attach to the tmux session a running loop iteration writes to. Returns 1 when
+# tmux is missing or no session exists for the current project.
+_loop_attach() {
+  local project_path; project_path=$(pwd -P)
+  local slug; slug=$(_project_slug "$project_path")
+  local session="roll-loop-${slug}"
+
+  if ! command -v tmux >/dev/null 2>&1; then
+    warn "tmux not installed — install with 'brew install tmux'  请先安装 tmux"
+    return 1
+  fi
+
+  if ! tmux has-session -t "$session" 2>/dev/null; then
+    info "No running loop session for this project  当前项目无运行中的 loop"
+    info "Wait for next scheduled fire, or run: roll loop now"
+    return 1
+  fi
+
+  exec tmux attach -t "$session"
+}
+
+# Pretty-print a duration in seconds as "Xs" / "Ym" / "Yh Zm".
+_loop_runs_dur() {
+  local s="${1:-0}"
+  if [[ "$s" -lt 60 ]]; then printf "%ds" "$s"
+  elif [[ "$s" -lt 3600 ]]; then printf "%dm" "$((s / 60))"
+  else printf "%dh %dm" "$((s / 3600))" "$(((s % 3600) / 60))"
+  fi
+}
+
+# Format a single JSONL run record for display.
+_loop_runs_format_line() {
+  local line="$1" show_project="$2"
+  command -v jq >/dev/null 2>&1 || { echo "  (jq required)"; return 0; }
+
+  local ts status project tcr duration alerts run_id reason built_count built_csv skipped_count
+  ts=$(jq -r '.ts // ""' <<<"$line")
+  status=$(jq -r '.status // ""' <<<"$line")
+  project=$(jq -r '.project // ""' <<<"$line")
+  tcr=$(jq -r '.tcr_count // 0' <<<"$line")
+  duration=$(jq -r '.duration_sec // 0' <<<"$line")
+  alerts=$(jq -r '.alerts // 0' <<<"$line")
+  run_id=$(jq -r '.run_id // ""' <<<"$line")
+  reason=$(jq -r '.reason // ""' <<<"$line")
+  built_count=$(jq -r '(.built // []) | length' <<<"$line")
+  built_csv=$(jq -r '(.built // []) | join(", ")' <<<"$line")
+  skipped_count=$(jq -r '(.skipped // []) | length' <<<"$line")
+
+  local hhmm; hhmm=$(printf "%s" "$ts" | sed -E 's/.*T([0-9]{2}):([0-9]{2}).*/\1:\2/')
+  local prefix=""
+  if [[ "$show_project" == "true" ]]; then
+    prefix="[$(basename "$project")] "
+  fi
+
+  case "$status" in
+    built)
+      local skipped_note=""
+      [[ "$skipped_count" -gt 0 ]] && skipped_note=", ${skipped_count} skipped"
+      printf "  %s  %s✅ built %s  (%d items, %d tcr%s, %s)\n" \
+        "$hhmm" "$prefix" "$built_csv" "$built_count" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")"
+      ;;
+    idle)
+      printf "  %s  %s○ idle — no Todo items\n" "$hhmm" "$prefix"
+      ;;
+    failed)
+      local msg="${reason:-unknown}"
+      printf "  %s  %s✗ FAILED — %s\n" "$hhmm" "$prefix" "$msg"
+      ;;
+    *)
+      printf "  %s  %s? %s\n" "$hhmm" "$prefix" "$status"
+      ;;
+  esac
+}
+
+# `roll loop runs [N] [--all]` — show recent loop iteration summaries.
+_loop_runs() {
+  local n=10 all_flag=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --all) all_flag=true; shift ;;
+      [0-9]*) n="$1"; shift ;;
+      *) shift ;;
+    esac
+  done
+
+  if [[ ! -f "$_LOOP_RUNS" ]] || [[ ! -s "$_LOOP_RUNS" ]]; then
+    echo "No loop runs yet  尚无 loop 运行记录"
+    return 0
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    err "jq required for 'roll loop runs'  需要 jq"
+    return 1
+  fi
+
+  local project_path; project_path=$(pwd -P)
+  local filtered
+  if $all_flag; then
+    filtered=$(cat "$_LOOP_RUNS")
+  else
+    filtered=$(jq -c --arg p "$project_path" 'select(.project == $p)' "$_LOOP_RUNS")
+  fi
+
+  if [[ -z "$filtered" ]]; then
+    echo "No loop runs for current project  当前项目尚无 loop 运行记录"
+    return 0
+  fi
+
+  local reversed; reversed=$(printf "%s\n" "$filtered" | awk '{a[NR]=$0} END{for(i=NR; i>=1; i--) print a[i]}')
+  local recent; recent=$(printf "%s\n" "$reversed" | head -n "$n")
+
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    _loop_runs_format_line "$line" "$all_flag"
+  done <<<"$recent"
+}
+
 # Count `tcr:` prefixed commits in the current git repo since started_at timestamp.
 _loop_tcr_count() {
   local started_at="$1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.511.6",
+  "version": "2026.511.8",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

package/skills/roll-.changelog/SKILL.md

@@ -45,83 +45,112 @@ Create mode:
 
 ### 3. Filter for External Content
 
-**Remove internal information:**
-- Progress tables, completion percentages
-- "As a / I can / So that" format
-- Detailed AC checklists
-- Technical debt, internal file paths
-- Test case counts, architecture diagrams
+CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清"用户能做什么 / 不再被什么坑"，能不写就不写。
 
-**Keep user-facing value:**
-- New features (one-sentence description)
-- Bug fixes (user-visible impact)
-- UX improvements (layout, interaction enhancements)
-- Performance/reliability improvements
+**完全跳过（不写入 CHANGELOG）：**
+- 测试基建（teardown 清理、test isolation、bats helper、CI 时序）
+- prompt / SKILL.md 内部契约（schema 锁定、enum 强制、contract test）
+- 内部重构（提取函数、变量改名、目录调整）
+- 只有开发者会遇到的 bug（release.sh 自身逻辑、TCR 节奏调整）
+- 任何"用户体验不变"的改动
 
-**语言：中文。** 所有 changelog 条目必须用中文撰写。
+判断准则：**如果用户读了这条记录，他不会改变使用方式，就别写。**
 
-**Description format:** `功能名 — 做了什么 + 用在什么场景`，一句话，精简。
+**保留：**
+- 用户能直接调用的新功能 / 新命令
+- 用户实际遇到过的 bug 修复
+- 看得见的体验变化（布局、文案、速度、可见性）
+- 影响安装、升级、配置的改动
 
-Good:
+**写法约束：**
+
+1. **一行，30 字以内**。超了就是太啰嗦。
+2. **不写实现细节**：禁止文件路径、函数名、字段列表、命令参数、配置键名。
+3. **不写数字细节**："3 个服务"、"60+ ghost" 这种内部状态不写。
+4. **说人话**：避免 "幂等"、"trap"、"epoch" 等技术黑话；说"做两次效果一样"、"异常退出也会清理"、"启动时间"。
+5. **句式**：`功能名 — 用户能做什么 / 解决了什么麻烦`。
+
+**语言：中文。**
+
+具体对比（都是真实的 roll 改动）：
+
+❌ 全是实现细节：
 ```
-- **Added**: roll-jot — 一句话快速记录 bug 或想法到 backlog，不打断当前工作
-- **Fixed**: 同步时清理已删除文件，防止用户机器残留幽灵文件
+- **Added**: `roll loop runs` 每次 loop 运行的快速可见性 — 单次 loop 结束追加一行 JSON 到 `~/.shared/roll/loop/runs.jsonl`（含 ts/project/run_id/status/built/skipped/alerts/tcr_count/duration_sec），新命令 `roll loop runs [N] [--all]` 倒序显示最近 N 次（默认 10）。
 ```
 
-Bad:
+✅ 讲价值：
 ```
-- **Added**: Add roll-jot skill for fast backlog capture
-- **Fixed**: Sync prunes stale files to prevent ghost files
+- **Added**: `roll loop runs` — 随时查看 loop 最近几次都跑了什么
 ```
 
-### 4. Version Number Format
+❌ 内部信息扎堆：
+```
+- **Fixed**: 集成测试 launchd ghost 泄漏 — `integration_teardown` 在删除 TEST_TMP 之前，先 `launchctl bootout` 该沙箱里被 `roll loop on` 注册到 user gui domain 的所有 `com.roll.*` 服务。
+```
 
-Determine the current version being released:
+✅ **直接跳过**：测试基建修复，用户感知不到。
 
-```bash
-VERSION=$(node -e "process.stdout.write(require('./package.json').version)" 2>/dev/null \
-  || git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
+❌ 参数列表+黑话：
+```
+- **Added**: Loop 并发安全 — runner script 启动时写入 per-project LOCK 文件并检测重入；活跃 PID 已存在则跳过本次，残留死 LOCK 自动清理；正常/异常退出均通过 trap 清掉 LOCK。
 ```
 
-`package.json` is the authoritative source — it is updated before this skill runs. Fall back to git tags only if `package.json` is unavailable.
+✅ 用户视角：
+```
+- **Fixed**: 多个 loop 实例不会再互相打架（重复触发自动跳过）
+```
 
-The CHANGELOG section header uses the full version string with a `v` prefix:
+### 4. Section Header — Always `## Unreleased`
+
+**⚠️ do NOT guess version numbers.** Only `scripts/release.sh` assigns concrete
+versions, and it only does so at the moment of a real release. Until then,
+every new bullet goes under `## Unreleased` at the top of CHANGELOG.md.
 
 ```
-## v${VERSION}
+## Unreleased
+- **Added**: ...new entries here...
+- **Fixed**: ...
 ```
 
-For the human-readable date display within entries, use `YYYY.MM.DD` format.
+When `release.sh` runs, it renames `## Unreleased` to `## v{N}` (where N is
+computed from git tags) — that's the single moment a version label gets
+assigned.
+
+Do NOT read `package.json` version, do NOT call `git describe`, do NOT invent
+version numbers like `v2026.511.8`. Just write to `## Unreleased`.
 
 ### 5. Generate CHANGELOG.md
 
-**Create mode** (first time):
+**Create mode** (first time, no CHANGELOG.md yet):
 ```markdown
 # Changelog
 
+## Unreleased
+- **Added**: ...current deploy's entries...
+
 ## 2026.05.10
-- **Added**: E2E 自动沉淀 — 每个 Story 交付时自动写一个端到端测试，项目逐步积累可回放的 E2E 套件
-- **Fixed**: 同步时清理已删除文件，防止用户机器残留幽灵文件
+- **Added**: ...historical entries from completed Stories before today...
+```
 
-## 2026.05.04
-- **Added**: BB 注入模式 — 对未集成 Black Box 的页面自动注入诊断探针，统一数据采集接口
+**Append mode** (most common — CHANGELOG.md exists):
 
-## 2026.04.28
-- ...
-```
+1. Find `## Unreleased` heading at the top of CHANGELOG.md.
+2. If it exists → append new bullets under it (do NOT create a new section).
+3. If it doesn't exist → insert a fresh `## Unreleased` at the very top (right after the `# Changelog` title) with the new bullets.
 
-**Append mode** (subsequent):
 ```markdown
 # Changelog
 
-## 2026.05.10    ← 新条目插入顶部
-- **Added**: Changelog 自动生成 — 每次部署后自动更新，首次运行时回填全部历史记录
+## Unreleased
+- **Added**: ...just-deployed entry appended here...
+- **Fixed**: ...another just-deployed entry...
 
-## 2026.05.04    ← 已有条目不动
+## v2026.05.07      ← previous releases left untouched
 - ...
 ```
 
-**Ordering**: Most recent version first (reverse chronological)
+**Ordering**: Unreleased always at top. Below it, released versions in reverse chronological order.
 
 ### 6. Commit Update
 

package/skills/roll-.dream/SKILL.md

@@ -113,29 +113,31 @@ complexity or prevent future bugs. Ignore cosmetic issues.
 
 ### Dream Log (docs/dream/YYYY-MM-DD.md)
 
-Always write a log, even when no REFACTOR entries are created:
+Always write a log, even when no REFACTOR entries are created. Output uses
+Chinese to align with roll-brief style — easier for the morning reader to scan
+without context switching:
 
 ```markdown
 # Dream Log {YYYY-MM-DD}
 
-## Summary
-- Scans run: Dead Code / Architectural Drift / Pruning / Patterns
-- Findings: {N} flagged, {M} REFACTOR entries created
+## 概要
+- 扫描项：死代码 / 架构漂移 / 裁剪候选 / 新兴模式
+- 发现：{N} 项标记，{M} 个 REFACTOR 条目已创建
 
-## Dead Code
-{finding or "Nothing flagged."}
+## 死代码
+{发现内容 或 "未发现死代码。"}
 
-## Architectural Drift
-{finding or "No drift detected."}
+## 架构漂移
+{发现内容 或 "未发现架构漂移。"}
 
-## Pruning Candidates
-{finding or "Nothing flagged."}
+## 裁剪候选
+{发现内容 或 "未发现可裁剪项。"}
 
-## Emerging Patterns
-{finding or "No patterns detected."}
+## 新兴模式
+{发现内容 或 "未发现可提取的重复模式。"}
 
-## REFACTOR Entries Created
-{list or "None."}
+## 创建的 REFACTOR 条目
+{列表 或 "无。"}
 ```
 
 ## Scheduler Configuration
@@ -151,7 +153,7 @@ The cron entry is generated using the configured agent — no manual cron editin
 
 If the scan fails partway through:
 
-1. Write partial results to `docs/dream/YYYY-MM-DD.md` with a `## Status: PARTIAL` header
+1. Write partial results to `docs/dream/YYYY-MM-DD.md` with a `## 状态：部分完成` header
 2. Do not write incomplete REFACTOR entries to BACKLOG
 3. Log the error to `~/.shared/roll/dream/error.log`
 

package/skills/roll-loop/SKILL.md

@@ -153,6 +153,67 @@ last_run_items: [US-AUTH-003, FIX-007]
 last_run_outcome: success
 ```
 
+Then append a JSONL record to `~/.shared/roll/loop/runs.jsonl` for per-iteration
+visibility (one line per cycle, append-only — never delete or rewrite earlier lines).
+
+**⚠️ Strict schema contract — do NOT deviate.** Every field has exactly one
+canonical form. Synonyms like `"success"`, `"noop"`, `"completed"` are forbidden
+for `status`. Numbers and arrays cannot be interchanged. UTC `Z` suffix only,
+no timezone offsets. **No extra fields** — emit only the keys listed below (plus
+optional `reason` when `status="failed"`); do not add `note`, `comment`,
+`details`, `info`, etc. If you feel the urge to annotate, put it in the cycle's
+final report in `cron.log` instead.
+
+**Canonical record (copy this exact shape, fill in real values):**
+
+```json
+{"ts":"2026-05-11T11:46:43Z","project":"roll-d9dfa0","run_id":"loop-20260511-1911","status":"built","built":["US-AUTO-024","US-AUTO-025"],"skipped":[],"alerts":[],"tcr_count":5,"duration_sec":2080}
+```
+
+**Field contract — types are enforced**:
+
+| Field | Type | Format / Enum |
+|---|---|---|
+| `ts` | string | ISO 8601 **UTC** with `Z` suffix. Get via `date -u +%Y-%m-%dT%H:%M:%SZ`. Never use `+08:00` or other offsets. |
+| `project` | string | Project **slug** only (e.g. `roll-d9dfa0`), NOT the absolute path. Derive from `basename` of plist label or `_project_slug` output. |
+| `run_id` | string | Matches `state.yaml` `run_id` exactly. Format: `loop-YYYYMMDD-HHMM`. |
+| `status` | enum | Exactly one of: `built` (≥1 story shipped), `idle` (no Todo items found), `failed` (paused/error). **No synonyms.** |
+| `built` | array<string> | Story ids completed this cycle. `[]` when none. **Always array, never null/number.** |
+| `skipped` | array<string> | Story ids skipped because they were `🔨 In Progress`. `[]` when none. **Always array.** |
+| `alerts` | array<string> | Newly raised ALERT identifiers/tags this cycle. `[]` when none. **Always array, never number.** |
+| `tcr_count` | integer | Total `tcr:` prefix commits made this cycle. `0` when none. |
+| `duration_sec` | integer | Seconds from cycle start to completion. Integer only, no decimals. |
+
+Optional field, only when `status == "failed"`:
+- `reason` (string): short human-readable explanation.
+
+**Write recipe:**
+
+```bash
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+project=$(basename "$(pwd)" | sed 's/.*-//')  # or use _project_slug if available
+# duration_sec = cycle_end_epoch - cycle_start_epoch (track at Step 1)
+# tcr_count = git log --oneline --since="<cycle_start>" | grep -c '^[a-f0-9]* tcr:'
+
+jq -nc \
+  --arg ts "$ts" \
+  --arg project "$project" \
+  --arg run_id "$run_id" \
+  --arg status "built" \
+  --argjson built '["US-AUTO-024"]' \
+  --argjson skipped '[]' \
+  --argjson alerts '[]' \
+  --argjson tcr_count 14 \
+  --argjson duration_sec 1680 \
+  '{ts:$ts, project:$project, run_id:$run_id, status:$status,
+    built:$built, skipped:$skipped, alerts:$alerts,
+    tcr_count:$tcr_count, duration_sec:$duration_sec}' \
+  >> ~/.shared/roll/loop/runs.jsonl
+```
+
+The companion read-side is `roll loop runs [N] [--all]` — shows the most recent
+N records (default 10) for the current project, or across all projects with `--all`.
+
 ## Failure Handling
 
 ### Network Error (transient)
@@ -235,6 +296,38 @@ roll loop status  # show current state
 roll loop now     # execute one cycle immediately
 ```
 
+### Live attach (transparency)
+
+Each loop iteration runs inside a detached tmux session named
+`roll-loop-<slug>` (tmux is a required dependency — `roll setup` auto-installs
+it via Homebrew on macOS, or prints the install command elsewhere).
+
+**Default — auto-attach popup**: when the loop fires, a background Terminal
+window pops up running `tmux attach -t roll-loop-<slug>`. You can watch the
+agent work in real time without typing anything. The popup is best-effort
+focus-retaining (it captures the previously-active app and restores focus
+after the window appears) and the tmux session keeps running even if you
+close the window.
+
+**Manual attach** (any time):
+
+```bash
+roll loop attach   # exec tmux attach -t roll-loop-<slug>
+```
+
+Press `Ctrl-B D` to detach — the loop continues running uninterrupted.
+
+**Mute / unmute the popup**:
+
+```bash
+roll loop mute     # 🔇 — suppress auto-attach popup (loop still runs in tmux)
+roll loop unmute   # 🔔 — re-enable the popup
+```
+
+Mute state is a single marker file at `~/.shared/roll/mute` and is shared
+across all projects on this machine. Check the current state with
+`roll loop status` — it shows an `Auto-attach: live | muted` line.
+
 ## Integration Map
 
 ```