@seanyao/roll 2026.511.5 → 2026.511.7

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## v2026.511.11
+- **Added**: loop 默认 auto-attach 弹窗 — 每次 loop 触发时，runner script 自动通过 osascript 开一个背景 Terminal 窗口 `tmux attach -t roll-loop-<slug>`，看 claude 实时打字干活；弹窗用 `delay 0.3` + 还原前一个 frontmost app 做到不抢焦点，tmux session 结束窗口保留供回看，关掉窗口 loop 仍在 tmux 里继续跑。
+- **Added**: `roll loop mute` / `roll loop unmute` 一键开关 — 不想看弹窗时 `roll loop mute` 创建 `~/.shared/roll/mute` 标记文件即刻静音，`unmute` 删掉它恢复；mute 状态对所有项目生效（一个开关治整机），`roll loop status` 新增 `Auto-attach  live | muted` 一行实时显示。
+- **Added**: tmux 升级为 `roll setup` 必装依赖 — 新增 `_ensure_tmux` helper：macOS 自动 `brew install tmux`（无 brew 给手动命令），Linux/其他系统打印对应包管理器安装指引；任何失败路径都返回 0，不阻塞 setup 主流程。
+- **Fixed**: launchd runner 缺 brew PATH 导致 hook 子进程报 `node: command not found` — launchd 默认 PATH 不含 `/opt/homebrew/bin`，claude 通过 `sh -c` 调 SessionEnd hook 时找不到 node；inner runner 模板显式 `export PATH="/opt/homebrew/bin:$PATH"` 让整条 fork 链都能拿到 brew 工具。
+- **Fixed**: runs.jsonl schema 漂移 — 早期 claude 在 status/ts/alerts/project 字段自由发挥（`built` vs `success` vs `noop`、UTC vs `+08:00`、number vs array、全路径 vs slug）。SKILL Step 5 改为"严格契约"：ts 强制 UTC Z 后缀、project 用 slug、alerts/built/skipped 永远是数组、status 限定 `built/idle/failed` 三个 enum 无同义词；contract test 锁死关键不变量留在 prompt 里。
+
+## v2026.511.9
+- **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），不必等次日早报就能查到中间 13 次 loop 各干了啥。
+- **Added**: loop 跑在 tmux session + `roll loop attach` 实时观看 — runner script 自动把 claude 包进 detached tmux session `roll-loop-<slug>`，输出同时 pipe 到 `cron.log`；执行 `roll loop attach` 可随时 attach 上去看它打字、写文件、commit，Ctrl-B D 分离后 loop 继续跑；未装 tmux 时自动 fallback 到原 headless 模式，零依赖回退。
+- **Improved**: roll-.dream 日志改为中文输出 — Dream Log 输出模板（概要 / 死代码 / 架构漂移 / 裁剪候选 / 新兴模式 / 创建的 REFACTOR 条目）和"未发现 / 部分完成"等固定文案全部中文化，与 roll-brief 风格对齐，晨间扫一眼不再需要在中英文之间切换语境。
+
+## v2026.511.8
+- **Fixed**: 集成测试 launchd ghost 泄漏 — `integration_teardown` 在删除 TEST_TMP 之前，先 `launchctl bootout` 该沙箱里被 `roll loop on` 注册到 user gui domain 的所有 `com.roll.*` 服务，避免删 plist 后 launchd 仍保留指向不存在路径的 ghost 注册。
+
+## 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 触发链路状态过渡更稳健。
+
+## 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 的新结构。
+
 ## v2026.511.5
 - **Fixed**: launchd plist 自动 reload — plist 内容变更且服务已加载时自动 unload + reload，升级 roll 后 loop 服务立即生效，无需手动重启
 - **Improved**: roll loop status/monitor 三态展示 — 区分 ● 运行中 / ⚠ 已安装未加载 / ○ 未安装，并给出对应的自愈操作提示

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.5"
+VERSION="2026.511.7"
 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,15 +1882,60 @@ _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"
+  cat > "$inner_path" << INNER
+#!/bin/bash -l
+export PATH="/opt/homebrew/bin:\$PATH"
+cd "${project_path}" && ${cmd}
+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
-cd "${project_path}" && ${cmd} >> "${log_path}" 2>&1
+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"
+    exit 0
+  fi
+  rm -f "\$LOCK"
+fi
+echo "\$\$" > "\$LOCK"
+trap 'rm -f "\$LOCK"' EXIT
+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"
 }
@@ -1967,9 +2047,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
 }
 
@@ -2107,6 +2191,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 ""
@@ -2132,6 +2222,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"
@@ -2454,13 +2676,28 @@ _dashboard() {
   if $_dash_loop_enabled; then
     echo -e "  Loop  ${GREEN}● on${NC}   Agent: ${CYAN}${agent}${NC}"
     if [[ "$(uname)" == "Darwin" ]]; then
-      for svc_info in "loop:hourly" "dream:03:00" "brief:09:00"; do
-        local svc="${svc_info%%:*}" schedule="${svc_info#*:}"
-        if _launchd_is_loaded "$(_launchd_label "$svc" "$project_path")"; then
-          printf "    ${GREEN}%-8s ● enabled${NC}  (%s)\n" "$svc" "$schedule"
-        else
-          printf "    ${YELLOW}%-8s ○ disabled${NC} (%s)\n" "$svc" "$schedule"
-        fi
+      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")
+      loop_minute=$(_config_read_int "loop_minute" "$(_loop_derive_minute "$project_path" 0)")
+      dream_hour=$(_config_read_int "loop_dream_hour" "3")
+      dream_minute=$(_config_read_int "loop_dream_minute" "$(_loop_derive_minute "$project_path" 2)")
+      brief_hour=$(_config_read_int "loop_brief_hour" "9")
+      brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
+      local loop_sched dream_sched brief_sched
+      loop_sched=$(printf "every hour :%02d  active %02d:00–%02d:00" "$loop_minute" "$active_start" "$active_end")
+      dream_sched=$(printf "%02d:%02d" "$dream_hour" "$dream_minute")
+      brief_sched=$(printf "%02d:%02d" "$brief_hour" "$brief_minute")
+      local svcs=("loop" "dream" "brief")
+      local scheds=("$loop_sched" "$dream_sched" "$brief_sched")
+      for i in "${!svcs[@]}"; do
+        local svc="${svcs[$i]}" schedule="${scheds[$i]}"
+        local state; state=$(_launchd_svc_state "$svc" "$project_path")
+        case "$state" in
+          enabled)       printf "    ${GREEN}%-8s ● enabled${NC}  (%s)\n" "$svc" "$schedule" ;;
+          installed-off) printf "    ${YELLOW}%-8s ⚠ off${NC}       (%s)  run: roll loop on\n" "$svc" "$schedule" ;;
+          not-installed) printf "    ${RED}%-8s ○ missing${NC}  (%s)  run: roll setup\n" "$svc" "$schedule" ;;
+        esac
       done
     fi
   else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.511.5",
+  "version": "2026.511.7",
   "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-.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-build/SKILL.md

@@ -483,7 +483,7 @@ Both locations must be updated — neither can be skipped:
 | [US-{ID}](docs/features/<feature>.md#us-{id}) | {Title} | ✅ Done |
 ```
 
-Change the Status from `📋 Todo` to `✅ Done`.
+Change the Status from `📋 Todo` or `🔨 In Progress` (whichever the row currently shows) to `✅ Done`. When invoked by `roll-loop`, the row will already be `🔨 In Progress` — that is the expected starting state, and the transition is the same Edit operation.
 For Fly mode: first append an index row under the appropriate Epic > Feature group, then mark it done.
 
 **② Update `docs/features/<feature>.md` US section:**

package/skills/roll-fix/SKILL.md

@@ -296,7 +296,7 @@ Both locations must be updated — neither can be skipped:
 | [FIX-{ID}](docs/features/<feature>.md#fix-{id}) | {Title} | ✅ Done |
 ```
 
-Change the Status of the corresponding row from `📋 Todo` to `✅ Done`.
+Change the Status of the corresponding row from `📋 Todo` or `🔨 In Progress` (whichever the row currently shows) to `✅ Done`. When invoked by `roll-loop`, the row will already be `🔨 In Progress` — that is the expected starting state.
 
 **② Update `docs/features/<feature>.md` FIX section:**
 

package/skills/roll-loop/SKILL.md

@@ -57,17 +57,56 @@ if [ -f "$STATE_FILE" ] && grep -q "status: interrupted" "$STATE_FILE"; then
 fi
 ```
 
+**Orphan 🔨 recovery** — clean up stories left in `🔨 In Progress` by a crashed previous run:
+
+1. Scan BACKLOG.md for all rows whose Status column contains `🔨 In Progress`.
+2. For each such story, check `state.yaml`:
+   - If `current_item` matches the story id AND `status: running` → this is the resume case (handled above), leave it.
+   - Otherwise → this is an **orphan 🔨** (the loop that marked it crashed before finishing). Revert the status back to `📋 Todo`, commit `chore: revert orphan 🔨 US-XXX to 📋`, and append a line to `~/.shared/roll/loop/ALERT.md` recording the orphan id and time so the next brief surfaces it.
+3. After orphan sweep, proceed to Step 2 (Scan BACKLOG) — the reverted stories will be picked up normally if they're top of the queue.
+
 ### Step 2 — Scan BACKLOG
 
 Read `BACKLOG.md`. Collect all rows where Status = `📋 Todo`, in order:
 
 Priority: FIX-XXX first (bugs block progress), then US-XXX, then REFACTOR-XXX.
 
+**Skip rows with Status = `🔨 In Progress`**. These are currently being executed by:
+- Another concurrent executor (human via `$roll-build`, peer agent)
+- An earlier loop iteration that hasn't finished yet (rare; should be guarded by LOCK)
+- A previous interrupted run (the resume logic in Step 1 will pick these up)
+
 Cap at `max_items_per_run` to limit blast radius per cycle.
 
+### Concurrency Safety
+
+Loop has two layers of concurrency protection:
+
+1. **Per-project LOCK** (enforced by runner script, see `bin/roll:_write_loop_runner_script`):
+   - LOCK file path: `~/.shared/roll/loop/.LOCK-<project-slug>`
+   - On launch: if LOCK exists and the PID inside is alive → exit 0 (previous loop still running)
+   - On launch: if LOCK exists but PID is dead → clean up stale LOCK and continue
+   - On exit (normal or via trap): LOCK is removed
+   - One LOCK per project — different projects' loops run independently
+
+2. **🔨 In Progress story status** (enforced here):
+   - Before picking a story, check its status is `📋 Todo`
+   - Skip any `🔨 In Progress` row (someone else is on it)
+   - Mark each story `🔨 In Progress` BEFORE invoking the executor skill (see Step 3)
+   - On completion: update to `✅ Done`; on TCR failure: revert to `📋 Todo`
+
+Together these mean: only one loop runs at a time per project (LOCK), and within a loop, stories already claimed by humans or peer agents are skipped (status check).
+
 ### Step 3 — Route and Execute
 
-For each item:
+For each item, **before invoking the executor skill**, mark the story 🔨 In Progress in BACKLOG.md so brief and peer agents can see it's being worked on:
+
+1. Edit BACKLOG.md: change the row's Status column from `📋 Todo` to `🔨 In Progress`.
+2. Commit: `git commit -am "chore: mark US-XXX in progress"` (use the actual story id).
+
+This commit is what makes the work visible — without it, tcr micro-commits during execution are invisible to `roll-brief`.
+
+Then invoke the executor:
 
 ```
 Item type         → Skill invoked
@@ -77,7 +116,9 @@ FIX-XXX           → Skill("roll-fix", "FIX-XXX")
 REFACTOR-XXX      → Skill("roll-build", "REFACTOR-XXX")
 ```
 
-Before invoking, write current item to state file:
+The executor will update the row to `✅ Done` on success (it transitions from `🔨 In Progress` → `✅ Done`, same Edit logic as from `📋 Todo`).
+
+Before invoking, also write current item to state file:
 
 ```yaml
 # ~/.shared/roll/loop/state.yaml
@@ -112,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&lt;string&gt; | Story ids completed this cycle. `[]` when none. **Always array, never null/number.** |
+| `skipped` | array&lt;string&gt; | Story ids skipped because they were `🔨 In Progress`. `[]` when none. **Always array.** |
+| `alerts` | array&lt;string&gt; | 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)
@@ -194,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
 
 ```