@seanyao/roll 2026.511.7 → 2026.512.1

package/CHANGELOG.md

@@ -1,52 +1,44 @@
 # 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.512.1
+- **Added**: `roll loop pause` / `roll loop resume` — 想自己上手时一键暂停 loop，做完再恢复
+- **Added**: `roll status` 新增所有项目的 loop 状态一览 — 调度时间、待办数、是否在跑
+- **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.7"
+VERSION="2026.512.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1254,6 +1254,63 @@ cmd_status() {
     fi
   done
 
+  _status_loop_overview
+}
+
+_status_loop_overview() {
+  [[ "$(uname)" != "Darwin" ]] && return 0
+
+  local plists=()
+  while IFS= read -r p; do
+    [[ -f "$p" ]] && plists+=("$p")
+  done < <(ls "${_LAUNCHD_DIR}"/com.roll.loop.*.plist 2>/dev/null)
+
+  [[ "${#plists[@]}" -eq 0 ]] && return 0
+
+  echo ""
+  echo -e "${BOLD}Loop Overview:  所有项目 loop 状态${NC}"
+
+  for plist in "${plists[@]}"; do
+    local label; label=$(basename "$plist" .plist)
+
+    local proj_path
+    proj_path=$(awk '/<key>WorkingDirectory<\/key>/{f=1;next} f{gsub(/^[[:space:]]*<string>|<\/string>[[:space:]]*$/,"");print;exit}' "$plist" 2>/dev/null)
+
+    local proj_name path_note=""
+    if [[ -n "$proj_path" && -d "$proj_path" ]]; then
+      proj_name=$(basename "$proj_path")
+    elif [[ -n "$proj_path" ]]; then
+      proj_name=$(basename "$proj_path")
+      path_note=" (path missing)"
+    else
+      proj_name="(unknown)"
+    fi
+
+    local state_icon
+    if _launchd_is_loaded "$label"; then
+      state_icon="${GREEN}●${NC}"
+    else
+      state_icon="${RED}○${NC}"
+    fi
+
+    local minute hour schedule
+    minute=$(awk '/<key>Minute<\/key>/{f=1;next} f{gsub(/^[[:space:]]*<integer>|<\/integer>[[:space:]]*$/,"");print;exit}' "$plist" 2>/dev/null)
+    hour=$(awk '/<key>Hour<\/key>/{f=1;next} f{gsub(/^[[:space:]]*<integer>|<\/integer>[[:space:]]*$/,"");print;exit}' "$plist" 2>/dev/null)
+    if [[ -n "$hour" && -n "$minute" ]]; then
+      schedule=$(printf "%02d:%02d" "$hour" "$minute")
+    elif [[ -n "$minute" ]]; then
+      schedule=":$(printf '%02d' "$minute")"
+    else
+      schedule="?"
+    fi
+
+    local todo_count=0
+    if [[ -z "$path_note" && -f "${proj_path}/BACKLOG.md" ]]; then
+      todo_count=$(grep -c '📋 Todo' "${proj_path}/BACKLOG.md" 2>/dev/null; true)
+    fi
+
+    echo -e "  ${state_icon} ${proj_name}${path_note}   ${schedule}   ${todo_count} pending"
+  done
 }
 
 check_sync_status() {
@@ -1726,7 +1783,7 @@ _agent_run_skill() {
   [[ -f "$skill_file" ]] || { err "Skill not found: ${skill}"; return 1; }
   local content; content=$(_skill_content "$skill_file")
   case "$agent" in
-    claude)   claude -p "$content" ;;
+    claude)   claude -p --output-format stream-json "$content" ;;
     kimi)     kimi --quiet -p "$content" ;;
     deepseek) deepseek "$content" ;;
     pi)       pi -p "$content" ;;
@@ -1810,6 +1867,13 @@ _config_read_int() {
   if [[ "$val" =~ ^[0-9]+$ ]]; then echo "$val"; else echo "$default"; fi
 }
 
+_config_read_string() {
+  local key="$1" default="$2"
+  local val
+  val=$(grep "^${key}:" "$ROLL_CONFIG" 2>/dev/null | awk '{print $2}' | tr -d '"' | head -1)
+  if [[ -n "$val" ]]; then echo "$val"; else echo "$default"; fi
+}
+
 # Derive a minute in [1,55] from project path hash + offset so different projects
 # and different services within a project don't fire at the same time.
 # Offsets used: loop=0, dream=2, brief=4 → always three distinct values (2<55).
@@ -1887,21 +1951,37 @@ _write_runner_script() {
 # 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}"
+  local active_start="${5:-10}" active_end="${6:-18}" terminal_pref="${7:-Terminal}"
   mkdir -p "$(dirname "$script_path")"
 
   local inner_path="${script_path%.sh}-inner.sh"
+  # Use stream-json + formatter: --verbose alone does nothing in -p mode;
+  # stream-json enables realtime streaming; loop-fmt.py humanizes the events.
+  local fmt_script="${ROLL_PKG_DIR}/lib/loop-fmt.py"
+  local cmd_verbose="${cmd/claude -p/claude -p --verbose --output-format stream-json}"
   cat > "$inner_path" << INNER
 #!/bin/bash -l
 export PATH="/opt/homebrew/bin:\$PATH"
-cd "${project_path}" && ${cmd}
+FMT="${fmt_script}"
+if [ -f "\$FMT" ]; then
+  ( cd "${project_path}" && ${cmd_verbose} ) | python3 "\$FMT"
+else
+  cd "${project_path}" && ${cmd_verbose}
+fi
 INNER
   chmod +x "$inner_path"
 
+  local slug; slug=$(_project_slug "$project_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
+# Active-window check — skipped when ROLL_LOOP_FORCE is set (manual 'roll loop now')
+if [ -z "\$ROLL_LOOP_FORCE" ]; then
+  h=\$(printf '%d' "\$(date +%H)")
+  if [ "\$h" -lt ${active_start} ] || [ "\$h" -ge ${active_end} ]; then exit 0; fi
+fi
+# Pause check — 'roll loop pause' creates this marker to suspend scheduling
+PAUSE="\$HOME/.shared/roll/loop/PAUSE-${slug}"
+if [ -z "\$ROLL_LOOP_FORCE" ] && [ -f "\$PAUSE" ]; 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}"
@@ -1923,14 +2003,30 @@ if command -v tmux >/dev/null 2>&1; then
   # 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) &
+  if [ ! -f "\$HOME/.shared/roll/mute" ] && [ "\$(uname)" = "Darwin" ]; then
+    case "${terminal_pref}" in
+      ghostty|Ghostty)
+        (open -na Ghostty.app --args -e tmux attach -t \$SESSION >/dev/null 2>&1) &
+        ;;
+      iTerm2|iTerm)
+        (osascript \\
+          -e 'tell application "System Events" to set _prev to name of first application process whose frontmost is true' \\
+          -e "tell application \"iTerm2\" to create window with default profile command \"tmux attach -t \$SESSION\"" \\
+          -e 'delay 0.3' \\
+          -e 'try' \\
+          -e 'tell application _prev to activate' \\
+          -e 'end try' >/dev/null 2>&1) &
+        ;;
+      *)
+        command -v osascript >/dev/null 2>&1 && (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) &
+        ;;
+    esac
   fi
   while tmux has-session -t "\$SESSION" 2>/dev/null; do sleep 5; done
 else
@@ -1978,6 +2074,17 @@ _install_launchd_plists() {
   brief_hour=$(_config_read_int "loop_brief_hour" "9")
   brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
 
+  # Terminal preference: config wins, then TERM_PROGRAM env, then "Terminal"
+  local terminal_pref
+  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  if [[ -z "$terminal_pref" ]]; then
+    case "${TERM_PROGRAM:-}" in
+      ghostty)    terminal_pref="ghostty" ;;
+      iTerm.app)  terminal_pref="iTerm2" ;;
+      *)          terminal_pref="Terminal" ;;
+    esac
+  fi
+
   local services=("loop" "dream" "brief")
   local skill_names=("roll-loop" "roll-.dream" "roll-brief")
   local minutes=("$loop_minute" "$dream_minute" "$brief_minute")
@@ -1997,7 +2104,7 @@ _install_launchd_plists() {
     local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
 
     if [[ "$svc" == "loop" ]]; then
-      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end"
+      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end" "$terminal_pref"
     else
       _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
     fi
@@ -2045,15 +2152,17 @@ cmd_loop() {
     on)      _loop_on ;;
     off)     _loop_off ;;
     now)     _loop_now ;;
+    test)    _loop_test ;;
     status)  _loop_status ;;
     monitor) _loop_monitor "${1:-3}" ;;
     runs)    _loop_runs "$@" ;;
     attach)  _loop_attach ;;
     mute)    _loop_mute ;;
     unmute)  _loop_unmute ;;
+    pause)   _loop_pause ;;
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
-    *) err "Usage: roll loop <on|off|now|status|monitor|runs|attach|mute|unmute|resume|reset>"; exit 1 ;;
+    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|attach|mute|unmute|pause|resume|reset>"; exit 1 ;;
   esac
 }
 
@@ -2158,34 +2267,108 @@ _loop_now() {
   if [[ -f "$_LOOP_STATE" ]] && grep -q "status: running" "$_LOOP_STATE" 2>/dev/null; then
     warn "Loop already running  loop 正在运行中"; return 0
   fi
-  info "Triggering loop cycle...  正在触发一个周期..."
-  local log_file="${_SHARED_ROOT}/loop/launchd.log"
-  mkdir -p "$(dirname "$log_file")"
-  _agent_run_skill "roll-loop" 2>&1 | tee -a "$log_file" || true
-  # Reset stale running state if skill exited without cleanup (e.g. API error, SIGKILL)
+  # Invoke the SAME runner script that launchd would invoke — same tmux,
+  # same --verbose, same LOCK, same auto-attach popup. ROLL_LOOP_FORCE
+  # bypasses only the active-window check (manual triggers aren't time-gated).
+  local project_path; project_path=$(pwd -P)
+  local slug; slug=$(_project_slug "$project_path")
+  local runner="${_SHARED_ROOT}/loop/run-${slug}.sh"
+  if [[ ! -f "$runner" ]]; then
+    err "Runner script not found: ${runner}"
+    err "Run 'roll setup' or 'roll loop on' first to generate it."
+    return 1
+  fi
+  info "Starting new loop cycle...  正在启动新的循环..."
+  ROLL_LOOP_FORCE=1 bash "$runner"
+  # Reset stale running state if the cycle exited without cleanup (e.g. API error, SIGKILL)
   if [[ -f "$_LOOP_STATE" ]] && grep -q "^status: running" "$_LOOP_STATE" 2>/dev/null; then
     printf "status: idle\n" > "$_LOOP_STATE"
   fi
 }
 
+_loop_test() {
+  local project_path; project_path=$(pwd -P)
+  local slug; slug=$(_project_slug "$project_path")
+  local runner="${_SHARED_ROOT}/loop/run-${slug}.sh"
+  if [[ ! -f "$runner" ]]; then
+    err "Runner not found: ${runner}"
+    err "Run 'roll loop on' first to generate it."
+    return 1
+  fi
+  local log="${_SHARED_ROOT}/loop/cron.log"
+  local test_runner="${_SHARED_ROOT}/loop/run-${slug}-test.sh"
+
+  # Detect terminal pref same way _install_launchd_plists does
+  local terminal_pref
+  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  if [[ -z "$terminal_pref" ]]; then
+    case "${TERM_PROGRAM:-}" in
+      ghostty)    terminal_pref="ghostty" ;;
+      iTerm.app)  terminal_pref="iTerm2" ;;
+      *)          terminal_pref="Terminal" ;;
+    esac
+  fi
+
+  local active_start active_end
+  active_start=$(_config_read_int "loop_active_start" "10")
+  active_end=$(_config_read_int "loop_active_end" "18")
+
+  info "Generating test runner...  正在生成测试启动脚本..."
+  _write_loop_runner_script "$test_runner" "$project_path" \
+    'claude -p "Reply with a single word: hello"; sleep 10' \
+    "$log" "$active_start" "$active_end" "$terminal_pref"
+
+  info "Starting smoke test (real claude, trivial prompt)...  正在运行 smoke 测试（真实 claude）..."
+  info "Watch for: tmux session + terminal popup + stream-json events flowing"
+  info "观察：tmux 会话 + 终端弹窗 + stream-json 事件流"
+
+  local start_time; start_time=$(date +%s)
+  ROLL_LOOP_FORCE=1 bash "$test_runner"
+  local exit_code=$?
+  local elapsed=$(( $(date +%s) - start_time ))
+
+  if [[ $exit_code -eq 0 ]]; then
+    ok "Smoke test passed (${elapsed}s)  smoke 测试通过 (${elapsed}秒)"
+  else
+    err "Smoke test failed (exit ${exit_code}, ${elapsed}s)  smoke 测试失败 (退出码 ${exit_code}, ${elapsed}秒)"
+    return 1
+  fi
+}
+
 _loop_status() {
   local project_path; project_path=$(pwd -P)
   local agent; agent=$(_project_agent)
+  local _is_paused=false
+  [[ -f "$_LOOP_STATE" ]] && grep -q "^status: paused" "$_LOOP_STATE" 2>/dev/null && _is_paused=true
   echo ""
   if [[ "$(uname)" == "Darwin" ]]; then
     echo -e "  Services   Agent: ${CYAN}${agent}${NC}"
     for svc in loop dream brief; do
       local state; state=$(_launchd_svc_state "$svc" "$project_path")
-      case "$state" in
-        enabled)       echo -e "    ${GREEN}${svc}     ● enabled${NC}" ;;
-        installed-off) echo -e "    ${YELLOW}${svc}     ⚠ installed/off${NC}   run: roll loop on" ;;
-        not-installed) echo -e "    ${RED}${svc}     ○ not installed${NC}   run: roll setup" ;;
-      esac
+      if [[ "$svc" == "loop" ]] && $_is_paused; then
+        local _paused_at; _paused_at=$(grep '^paused_at:' "$_LOOP_STATE" 2>/dev/null | awk '{print $2}' | tr -d '"')
+        local _dur=""
+        if [[ -n "$_paused_at" ]]; then
+          local _pe _ne _sec
+          _pe=$(date -d "$_paused_at" +%s 2>/dev/null || date -jf "%Y-%m-%dT%H:%M:%SZ" "$_paused_at" +%s 2>/dev/null || echo 0)
+          _ne=$(date +%s); _sec=$(( _ne - _pe ))
+          _dur="  ($(( _sec / 3600 ))h $(( (_sec % 3600) / 60 ))m ago)"
+        fi
+        echo -e "    ${YELLOW}loop     ⏸ paused${NC}${_dur}   run: roll loop resume"
+      else
+        case "$state" in
+          enabled)       echo -e "    ${GREEN}${svc}     ● enabled${NC}" ;;
+          installed-off) echo -e "    ${YELLOW}${svc}     ⚠ installed/off${NC}   run: roll loop on" ;;
+          not-installed) echo -e "    ${RED}${svc}     ○ not installed${NC}   run: roll setup" ;;
+        esac
+      fi
     done
   else
     local loop_enabled=false
     crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}" && loop_enabled=true
-    if $loop_enabled; then
+    if $_is_paused; then
+      echo -e "  Scheduler  ${YELLOW}⏸ paused${NC}   run: roll loop resume"
+    elif $loop_enabled; then
       echo -e "  Scheduler  ${GREEN}● enabled${NC}   Agent: ${CYAN}${agent}${NC}"
     else
       echo -e "  Scheduler  ${YELLOW}○ disabled${NC}   run: roll loop on"
@@ -2202,7 +2385,47 @@ _loop_status() {
   echo ""
 }
 
+_loop_pause() {
+  local project_path; project_path=$(pwd -P)
+  local paused_at; paused_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  if [[ "$(uname)" == "Darwin" ]]; then
+    local label; label=$(_launchd_label "loop" "$project_path")
+    if ! _launchd_is_loaded "$label"; then
+      warn "Loop not enabled — nothing to pause  loop 未启用，无需暂停"; return 0
+    fi
+    launchctl unload -w "$(_launchd_plist_path "loop" "$project_path")" 2>/dev/null || true
+  else
+    local slug; slug=$(_project_slug "$project_path")
+    touch "${_SHARED_ROOT}/loop/PAUSE-${slug}"
+  fi
+
+  mkdir -p "$(dirname "$_LOOP_STATE")"
+  printf 'status: paused\npaused_at: "%s"\npaused_reason: manual\n' "$paused_at" > "$_LOOP_STATE"
+  ok "Loop paused  已暂停   run: roll loop resume"
+}
+
 _loop_resume() {
+  local project_path; project_path=$(pwd -P)
+
+  # Scheduler resume: loop was manually paused via `roll loop pause`
+  if [[ -f "$_LOOP_STATE" ]] && grep -q "^status: paused" "$_LOOP_STATE" 2>/dev/null; then
+    if [[ "$(uname)" == "Darwin" ]]; then
+      local label; label=$(_launchd_label "loop" "$project_path")
+      local plist; plist=$(_launchd_plist_path "loop" "$project_path")
+      if [[ -f "$plist" ]]; then
+        launchctl load -w "$plist" 2>/dev/null || true
+      fi
+    else
+      local slug; slug=$(_project_slug "$project_path")
+      rm -f "${_SHARED_ROOT}/loop/PAUSE-${slug}"
+    fi
+    printf "status: idle\n" > "$_LOOP_STATE"
+    ok "Loop resumed  已恢复"
+    return 0
+  fi
+
+  # Interrupt resume: loop was running a Story and crashed
   if [[ ! -f "$_LOOP_STATE" ]]; then
     warn "No loop state found — nothing to resume  未找到 loop 状态，无需恢复"; return 0
   fi
@@ -2667,13 +2890,18 @@ _dashboard() {
 
   echo -e "\n  ${BOLD}${CYAN}${project_name}${NC}  ${YELLOW}v${VERSION}${NC}\n"
 
+  local _dash_loop_paused=false
+  [[ -f "$_LOOP_STATE" ]] && grep -q "^status: paused" "$_LOOP_STATE" 2>/dev/null && _dash_loop_paused=true
+
   local _dash_loop_enabled=false
   if [[ "$(uname)" == "Darwin" ]]; then
     _launchd_is_loaded "$(_launchd_label "loop" "$project_path")" && _dash_loop_enabled=true
   else
     crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}" && _dash_loop_enabled=true
   fi
-  if $_dash_loop_enabled; then
+  if $_dash_loop_paused; then
+    echo -e "  Loop  ${YELLOW}⏸ paused${NC}   run: roll loop resume"
+  elif $_dash_loop_enabled; then
     echo -e "  Loop  ${GREEN}● on${NC}   Agent: ${CYAN}${agent}${NC}"
     if [[ "$(uname)" == "Darwin" ]]; then
       local active_start active_end loop_minute dream_hour dream_minute brief_hour brief_minute

package/lib/loop-fmt.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+loop-fmt.py — stream-json → human-readable formatter for roll loop tmux output.
+
+Reads stream-json lines from stdin, emits colored, human-readable events.
+Skips noise (system/init, hook_started, rate_limit_event) and abbreviates
+tool results so the window stays readable.
+
+Color codes: no external deps, plain ANSI.
+"""
+
+import sys
+import json
+import re
+import textwrap
+
+# ANSI colors
+CYAN    = "\033[36m"
+GREEN   = "\033[32m"
+YELLOW  = "\033[33m"
+RED     = "\033[31m"
+GRAY    = "\033[90m"
+BOLD    = "\033[1m"
+RESET   = "\033[0m"
+DIM     = "\033[2m"
+
+SKIP_SUBTYPES = {"hook_started", "hook_response", "hook_stop_hook_execution",
+                 "hook_stop_hook_active_hooks_ran"}
+
+def trunc(s, n=120):
+    s = str(s).replace("\n", " ").strip()
+    return s[:n] + "…" if len(s) > n else s
+
+def fmt_tool_input(name, inp):
+    if not isinstance(inp, dict):
+        return trunc(str(inp), 80)
+    if name == "Bash":
+        cmd = inp.get("command", "")
+        # show first non-empty line
+        lines = [l.strip() for l in cmd.splitlines() if l.strip()]
+        return trunc(lines[0] if lines else cmd, 100)
+    if name in ("Read", "Write", "Edit"):
+        path = inp.get("file_path", inp.get("path", ""))
+        extra = ""
+        if name == "Edit":
+            old = inp.get("old_string", "")
+            extra = f"  ({trunc(old, 40)})"
+        return f"{path}{extra}"
+    if name in ("Glob", "Grep"):
+        return trunc(inp.get("pattern", inp.get("query", str(inp))), 80)
+    if name == "Skill":
+        return inp.get("skill", "") + (" " + inp.get("args", "") if inp.get("args") else "")
+    if name == "Agent":
+        return trunc(inp.get("description", str(inp)), 80)
+    return trunc(json.dumps(inp, ensure_ascii=False), 80)
+
+def fmt_tool_result(content):
+    if isinstance(content, list):
+        parts = []
+        for c in content:
+            if isinstance(c, dict):
+                t = c.get("type", "")
+                if t == "text":
+                    parts.append(c.get("text", ""))
+                elif t == "image":
+                    parts.append("[image]")
+            else:
+                parts.append(str(c))
+        text = " ".join(parts)
+    else:
+        text = str(content) if content is not None else ""
+    # strip ansi for length check
+    clean = re.sub(r'\033\[[0-9;]*m', '', text)
+    lines = [l for l in clean.splitlines() if l.strip()]
+    if not lines:
+        return "(empty)"
+    # show first 3 lines, trim long lines
+    out = []
+    for l in lines[:3]:
+        out.append("  " + trunc(l, 100))
+    if len(lines) > 3:
+        out.append(f"  {DIM}… ({len(lines)-3} more lines){RESET}")
+    return "\n".join(out)
+
+def process_line(line):
+    line = line.rstrip()
+    if not line:
+        return
+    try:
+        ev = json.loads(line)
+    except json.JSONDecodeError:
+        # plain text passthrough
+        print(line)
+        return
+
+    etype = ev.get("type", "")
+
+    # ── system events ──────────────────────────────────────────────
+    if etype == "system":
+        subtype = ev.get("subtype", "")
+        if subtype in SKIP_SUBTYPES:
+            return
+        if subtype == "init":
+            model = ev.get("model", "")
+            tools = ev.get("tools", [])
+            tool_list = ", ".join(tools[:6])
+            if len(tools) > 6:
+                tool_list += f" +{len(tools)-6}"
+            print(f"{DIM}[init] model={model}  tools={tool_list}{RESET}")
+            return
+        # unknown system — show raw briefly
+        print(f"{DIM}[sys/{subtype}]{RESET}")
+        return
+
+    # ── rate limit ────────────────────────────────────────────────
+    if etype == "rate_limit_event":
+        return
+
+    # ── assistant ────────────────────────────────────────────────
+    if etype == "assistant":
+        msg = ev.get("message", {})
+        for blk in msg.get("content", []):
+            btype = blk.get("type", "")
+            if btype == "tool_use":
+                name = blk.get("name", "?")
+                inp  = blk.get("input", {})
+                summary = fmt_tool_input(name, inp)
+                print(f"{CYAN}→ {BOLD}{name}{RESET}{CYAN}: {summary}{RESET}")
+            elif btype == "text":
+                text = blk.get("text", "").strip()
+                if text:
+                    # wrap long text
+                    for l in textwrap.wrap(text, 120):
+                        print(f"{GREEN}{l}{RESET}")
+            elif btype == "thinking":
+                thought = blk.get("thinking", "").strip()
+                if thought:
+                    first = trunc(thought, 80)
+                    print(f"{DIM}[thinking] {first}{RESET}")
+        return
+
+    # ── user (tool results) ───────────────────────────────────────
+    if etype == "user":
+        msg = ev.get("message", {})
+        for blk in msg.get("content", []):
+            if blk.get("type") == "tool_result":
+                is_err = blk.get("is_error", False)
+                content = blk.get("content", "")
+                result_text = fmt_tool_result(content)
+                prefix = f"{RED}  ✗{RESET}" if is_err else f"{GRAY}  ↩{RESET}"
+                print(f"{prefix} {result_text}")
+        return
+
+    # ── result (final) ───────────────────────────────────────────
+    if etype == "result":
+        dur_ms   = ev.get("duration_ms", 0)
+        cost_usd = ev.get("total_cost_usd", 0)
+        turns    = ev.get("num_turns", "?")
+        dur_s    = dur_ms / 1000
+        cost_str = f"${cost_usd:.4f}" if cost_usd else ""
+        subtype  = ev.get("subtype", "")
+        if subtype == "error_max_turns":
+            print(f"{RED}✗ max turns reached  {dur_s:.1f}s{RESET}")
+        else:
+            cost_part = f"  {YELLOW}{cost_str}{RESET}" if cost_str else ""
+            print(f"\n{GREEN}{BOLD}✓ done{RESET}  {dur_s:.1f}s  {GRAY}{turns} turns{RESET}{cost_part}")
+        return
+
+    # ── fallback ────────────────────────────────────────────────
+    print(f"{DIM}{trunc(line, 160)}{RESET}")
+
+
+def main():
+    for line in sys.stdin:
+        process_line(line)
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.511.7",
+  "version": "2026.512.1",
   "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"
@@ -25,6 +25,7 @@
   "files": [
     "bin/",
     "conventions/",
+    "lib/",
     "skills/",
     "tools/",
     "template/",

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

@@ -140,6 +140,22 @@ without context switching:
 {列表 或 "无。"}
 ```
 
+### Commit
+
+扫描完成后立即提交，把 dream 发现纳入 git 历史，便于晨报追溯：
+
+```bash
+git add BACKLOG.md docs/dream/YYYY-MM-DD.md
+# 有 REFACTOR 条目时：
+git commit -m "chore: dream scan YYYY-MM-DD — {N} REFACTOR entries"
+# 无发现时：
+git commit -m "chore: dream scan YYYY-MM-DD — no findings"
+```
+
+- BACKLOG.md 和 dream 日志必须在**同一个 commit** 里入库，避免出现"REFACTOR 已加但日志找不到"或反过来的撕裂状态
+- 写文件失败时不要执行 commit；保持工作区干净，由调度器负责重试
+- 仅 `BACKLOG.md` 和 `docs/dream/YYYY-MM-DD.md` 入 commit，不要顺带带入其他无关变更
+
 ## Scheduler Configuration
 
 roll-.dream runs **locally** — it reads the local codebase directly.

package/skills/roll-brief/SKILL.md

@@ -151,6 +151,19 @@ A simple heuristic — not a gate, just a signal for the human:
 **Epic: {Name}** — {done}/{total} ✅
 ```
 
+### Step 4.5 — Commit Brief
+
+写完文件后立即提交，让简报进入 git 历史，便于后续追溯与跨会话审计：
+
+```bash
+git add docs/briefs/YYYY-MM-DD-NN.md
+git commit -m "docs: roll-brief YYYY-MM-DD-NN — {触发原因}"
+```
+
+- 触发原因来自调用上下文（Feature 完成 / 每日 / 手动 / `--feature` / `--since`），用一句话填入
+- 写文件失败时不要执行 commit；保持工作区干净，由调用方处理重试
+- 仅 `docs/briefs/` 下新文件入 commit，不要顺带带入其他无关变更
+
 ### Step 5 — Notify
 
 写完文件后在终端或 CI 日志中打印简报路径：

package/skills/roll-design/SKILL.md

@@ -50,6 +50,12 @@ $roll-design --from-plan docs/features/auth-plan.md
 
 # Directly create a Story (auto-detected as User Story → Slice DDD)
 $roll-design "user login feature"
+
+# Non-interactive: read structured input file, skip Clarify/Discuss, write BACKLOG
+$roll-design --from-file docs/requirements/auth-req.md
+
+# Promote IDEA to Story: read BACKLOG IDEA-NNN, produce US-XXX, annotate IDEA
+$roll-design --from-idea IDEA-009
 ```
 
 ## DDD Depth Scale
@@ -118,10 +124,82 @@ docs/domain/                        # DDD domain model (greenfield / cross-featu
 3. Plan file: `docs/features/<feature>-plan.md` (create if it doesn't exist)
 4. BACKLOG.md index row goes under the corresponding Epic > Feature group
 
+## Non-Interactive Mode
+
+Activated by explicit flags or auto-detected high-confidence input. Skips Clarify and Discuss, writes stories directly to BACKLOG as `📋 Todo`, no confirm gate.
+
+### `--from-file <path>`
+
+```
+Input: structured requirement file (plain text or markdown)
+
+Expected file contents (minimum viable):
+  - Description: what to build (1–3 sentences)
+  - Expected AC: measurable outcomes (bullet list)
+  - [Optional] Domain hint, priority, dependencies
+
+Execution path:
+  [Read file] → [Analyze] → [DDD Slice] → [Solution Design] → [Split Stories]
+      → [Write BACKLOG 📋 Todo] → Done (no Clarify, no Discuss, no confirm gate)
+```
+
+Input file example (`docs/requirements/auth-req.md`):
+```markdown
+## Requirement: session timeout warning
+
+Description: Show a countdown modal 60 seconds before session expires.
+Users can click "Stay logged in" to extend, or let it expire naturally.
+
+Expected AC:
+- Modal appears at T-60s with countdown timer
+- "Stay logged in" sends a keepalive and dismisses modal
+- Expiry after countdown logs user out and redirects to /login
+- Works across all authenticated pages
+```
+
+### `--from-idea IDEA-NNN`
+
+```
+Input: IDEA-NNN identifier from BACKLOG.md
+
+Execution path:
+  [Read BACKLOG.md IDEA-NNN row] → [Analyze] → [DDD Slice] → [Split Stories]
+      → [Write BACKLOG 📋 Todo] → [Annotate IDEA row: → US-XXX] → Done
+
+IDEA annotation: append `→ US-XXX` to the IDEA row's Description column.
+Example: | IDEA-009 | ... | ✅ Done → US-AUTO-021 |
+```
+
+### High-Confidence Auto-Detection
+
+When input is not a flag-based mode but already contains all three of: **clear verb**, **explicit scope**, and **verifiable acceptance signal**, skip Clarify automatically. At most retain Discuss (only if approach has genuine divergence).
+
+High-confidence signals (all three must be present):
+- Clear verb: add / remove / fix / rename / migrate / split / extract / support ...
+- Explicit scope: named file, command, module, endpoint, or UI element
+- Acceptance signal: "so that X", "when Y then Z", measurable outcome described
+
+Examples:
+```bash
+# High confidence — skip Clarify:
+$roll-design "add --dry-run flag to roll loop on that prints plist without installing"
+$roll-design "rename cmd_status() to cmd_overview() in bin/roll and update all callers"
+
+# Low confidence — enter Clarify:
+$roll-design "improve the status command"
+$roll-design "make loop better"
+```
+
+---
+
 ## Workflow
 
 ```
 User Input
+    │
+    ├── --from-file <path>  ──→  [Read file] → Step 2 (Analyze) → Steps 3–5 → BACKLOG 📋 → Done
+    ├── --from-idea IDEA-N  ──→  [Read BACKLOG IDEA] → Step 2 → Steps 3–5 → BACKLOG 📋 → Annotate IDEA → Done
+    ├── high-confidence str ──→  Step 2 (Analyze) directly (skip Clarify, keep Discuss if divergence)
     │
     ▼
 ┌─────────────────────────────┐
@@ -240,9 +318,14 @@ User Input
                        │
                        ├── Yes ──→ $roll-build US-XXX
                        │
-                       └── No  ──→ Wait for user confirmation
+                       └── No  ──→ Story 已写入 BACKLOG 为 📋 Todo
+                                   loop 下轮将自动执行
+                                   （选 No 仅跳过立即执行）
 ```
 
+**Gate 语义澄清**：选 `No` 不是放弃，story 已经入 BACKLOG，下轮 loop 会自动 pickup
+（次日 / `roll loop now`）。若想完全搁置，请显式把状态改为 🚫 Hold。
+
 ---
 
 ## DDD Output Formats
@@ -412,7 +495,11 @@ Domain: Order Context > Order Aggregate > OrderItem Entity
 
 ## Clarify Phase
 
-**Trigger conditions** — automatically enters if any of these are met:
+**Skip conditions** — silently skip Clarify when any of these hold:
+- Input uses `--from-file` or `--from-idea` flag (non-interactive mode)
+- Input is high-confidence (clear verb + explicit scope + acceptance signal — see Non-Interactive Mode)
+
+**Trigger conditions** — automatically enters if none of the skip conditions hold AND any of these are met:
 - Input is a single vague sentence without clear scope
 - Missing clear boundaries (what / who / when / where)
 - Contains ambiguous terms like "优化一下", "改一下", "加个东西", "做个设计"

package/skills/roll-loop/SKILL.md

@@ -32,6 +32,11 @@ sole authority over `roll-release`.
 - Any Story marked 🚫 Hold or flagged for human review
 - Destructive operations outside normal skill scope
 
+**Human bypass path** — roll-loop 是默认调度器，不垄断执行权。任何时刻人可直接
+`$roll-build US-XXX` 或 `$roll-fix FIX-XXX` 绕过 loop 立即执行（紧急 bug、中断插入、
+故事评审等场景）。loop 通过 LOCK 和 `🔨 In Progress` 状态识别并跳过人正在做的故事，
+人机并行不会撞车（见 Concurrency Safety）。
+
 ## Configuration
 
 ```yaml