@seanyao/roll 2026.511.6 → 2026.511.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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 注册。
 

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.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,26 +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
 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 +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
 }
 
@@ -2118,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 ""
@@ -2143,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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.511.6",
+  "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-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
 
 ```