@seanyao/roll 2026.511.8 → 2026.512.2

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
 ## Unreleased
+- **Added**: BACKLOG 支持 block / defer / unblock 状态管理 — 标记卡住的任务不再占队列
+- **Fixed**: 自动弹窗现在能识别 Ghostty 和 iTerm2，不再强制弹出 Terminal.app
+- **Fixed**: loop 检测到上一轮还在跑时自动跳过，不重复启动
+
+## v2026.512.1
+- **Added**: `roll loop pause` / `roll loop resume` — 想自己上手时一键暂停 loop，做完再恢复
+- **Added**: `roll status` 新增所有项目的 loop 状态一览 — 调度时间、待办数、是否在跑
 - **Fixed**: `roll loop attach` 不再黑屏，AI 干活过程实时可见
 
 ## v2026.511.7

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.8"
+VERSION="2026.512.2"
 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,25 +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"
-  # 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}"
+  # 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_verbose}
+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}"
@@ -1918,6 +1994,13 @@ if [ -f "\$LOCK" ]; then
   fi
   rm -f "\$LOCK"
 fi
+# Guard against stale-LOCK case: if the tmux session is already alive,
+# a previous runner's LOCK was removed (e.g. parent terminal closed) but
+# the work is still in progress — don't kill it.
+if command -v tmux >/dev/null 2>&1 && tmux has-session -t "\$SESSION" 2>/dev/null; then
+  echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] tmux session \$SESSION still active, skipping" >> "\$LOG"
+  exit 0
+fi
 echo "\$\$" > "\$LOCK"
 trap 'rm -f "\$LOCK"' EXIT
 if command -v tmux >/dev/null 2>&1; then
@@ -1927,14 +2010,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
+    # Runtime terminal detection: try preferred first, fallback through installed apps.
+    # open -na returns non-zero when app not found, so || chain works as fallback.
+    _PREF="${terminal_pref}"
+    _launched=0
+    if [ "\$_PREF" = "ghostty" ] || [ "\$_PREF" = "Ghostty" ]; then
+      open -na Ghostty.app --args -e tmux attach -t \$SESSION >/dev/null 2>&1 && _launched=1 || true
+    fi
+    if [ "\$_launched" -eq 0 ] && { [ "\$_PREF" = "iTerm2" ] || [ "\$_PREF" = "iTerm" ] || [ -d "/Applications/iTerm.app" ]; }; then
+      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 \\
+        && _launched=1 || true
+    fi
+    if [ "\$_launched" -eq 0 ] && [ -d "/Applications/Ghostty.app" ]; then
+      open -na Ghostty.app --args -e tmux attach -t \$SESSION >/dev/null 2>&1 && _launched=1 || true
+    fi
+    if [ "\$_launched" -eq 0 ] && 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 || true
+    fi
   fi
   while tmux has-session -t "\$SESSION" 2>/dev/null; do sleep 5; done
 else
@@ -1982,6 +2081,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")
@@ -2001,7 +2111,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
@@ -2049,15 +2159,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
 }
 
@@ -2162,34 +2274,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"
@@ -2206,7 +2392,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
@@ -2580,9 +2806,45 @@ cmd_release() {
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
-# BACKLOG — show pending tasks
+# BACKLOG — show pending tasks / manage status
 # ═══════════════════════════════════════════════════════════════════════════════
 
+# Update status of all BACKLOG rows whose ID field contains <pattern> (case-insensitive).
+# Uses Python for reliable emoji/Unicode handling.
+_backlog_set_status() {
+  local pattern="$1"
+  local new_status="$2"
+  local backlog="BACKLOG.md"
+  python3 -c "
+import sys, re
+pattern, new_status, filename = sys.argv[1], sys.argv[2], sys.argv[3]
+lines = open(filename, encoding='utf-8').readlines()
+count = 0
+out = []
+for line in lines:
+    if line.startswith('|') and line.count('|') >= 4:
+        parts = line.split('|')
+        if len(parts) >= 5:
+            id_field = re.sub(r'\[([^\]]+)\]\([^)]+\)', r'\1', parts[1]).strip()
+            if pattern.upper() in id_field.upper():
+                parts[-2] = ' ' + new_status + ' '
+                line = '|'.join(parts)
+                count += 1
+    out.append(line)
+open(filename, 'w', encoding='utf-8').writelines(out)
+print(count)
+" "$pattern" "$new_status" "$backlog"
+}
+
+_backlog_extract_id() {
+  local line="$1"
+  if echo "$line" | grep -q '\[US-'; then
+    echo "$line" | sed 's/.*\[\(US-[^]]*\)\].*/\1/'
+  else
+    echo "$line" | awk -F'|' '{print $2}' | tr -d ' '
+  fi
+}
+
 cmd_backlog() {
   local backlog="BACKLOG.md"
   if [[ ! -f "$backlog" ]]; then
@@ -2590,8 +2852,38 @@ cmd_backlog() {
     return 1
   fi
 
-  local us_items fix_items refactor_items idea_items total=0
+  local subcmd="${1:-}"
 
+  # ── Status management subcommands ─────────────────────────────────────────
+  case "$subcmd" in
+    block|defer|unblock|promote)
+      local pattern="${2:-}"
+      local reason="${3:-}"
+      if [[ -z "$pattern" ]]; then
+        err "Usage: roll backlog $subcmd <pattern> [reason]  用法: roll backlog $subcmd <匹配模式> [原因]"
+        return 1
+      fi
+      local new_status
+      case "$subcmd" in
+        block)           new_status="🔒 Blocked${reason:+ [${reason}]}" ;;
+        defer)           new_status="⏸ Deferred${reason:+ [${reason}]}" ;;
+        unblock|promote) new_status="📋 Todo" ;;
+      esac
+      local count
+      count=$(_backlog_set_status "$pattern" "$new_status")
+      if [[ "$count" -eq 0 ]]; then
+        echo "  No items matched: $pattern  未找到匹配项: $pattern"
+      else
+        echo "  Updated ${count} item(s) → ${new_status}  已更新 ${count} 条目"
+      fi
+      return
+      ;;
+  esac
+
+  # ── Display mode ──────────────────────────────────────────────────────────
+  local DIM='\033[2m'
+
+  local us_items fix_items refactor_items idea_items total=0
   us_items=$(grep -E '^\| \[US-' "$backlog" | grep -F '| 📋 Todo |' || true)
   fix_items=$(grep -E '^\| FIX-' "$backlog" | grep -F '| 📋 Todo |' || true)
   refactor_items=$(grep -E '^\| REFACTOR-' "$backlog" | grep -F '| 📋 Todo |' || true)
@@ -2608,6 +2900,20 @@ cmd_backlog() {
   [[ -z "$idea_items" ]] && idea_count=0
   total=$(( us_count + fix_count + refactor_count + idea_count ))
 
+  local blocked_items deferred_items unknown_items
+  blocked_items=$(grep -E '^\|' "$backlog" | grep '🔒 Blocked' || true)
+  deferred_items=$(grep -E '^\|' "$backlog" | grep '⏸ Deferred' || true)
+  unknown_items=$( { grep -E '^\| \[US-' "$backlog"; grep -E '^\| FIX-' "$backlog"; grep -E '^\| REFACTOR-' "$backlog"; grep -E '^\| IDEA-' "$backlog"; } \
+    | grep -v '📋 Todo\|🔨 In Progress\|✅ Done\|🔒 Blocked\|⏸ Deferred' || true)
+
+  local blocked_count deferred_count unknown_count
+  blocked_count=$(echo "$blocked_items" | grep -c . || true)
+  deferred_count=$(echo "$deferred_items" | grep -c . || true)
+  unknown_count=$(echo "$unknown_items" | grep -c . || true)
+  [[ -z "$blocked_items" ]] && blocked_count=0
+  [[ -z "$deferred_items" ]] && deferred_count=0
+  [[ -z "$unknown_items" ]] && unknown_count=0
+
   echo ""
   echo -e "  ${BOLD}Pending Backlog  待处理任务${NC}  (${total} items)"
   echo ""
@@ -2660,6 +2966,53 @@ cmd_backlog() {
     echo -e "  ${GREEN}✓ Nothing pending — backlog is clear  暂无待处理任务${NC}"
     echo ""
   fi
+
+  # ── Blocked ───────────────────────────────────────────────────────────────
+  if [[ $blocked_count -gt 0 ]]; then
+    echo -e "  ${DIM}Blocked  已阻塞  (${blocked_count})${NC}"
+    while IFS= read -r line; do
+      [[ -z "$line" ]] && continue
+      local id desc reason
+      id=$(_backlog_extract_id "$line")
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-52)
+      reason=$(echo "$line" | awk -F'|' '{print $4}' | grep -oE '\[.*\]' | tr -d '[]' || true)
+      printf "    ${DIM}🔒 %-14s  %s${NC}" "$id" "$desc"
+      [[ -n "$reason" ]] && printf "${DIM}  (%s)${NC}" "$reason"
+      printf "\n"
+    done <<< "$blocked_items"
+    echo ""
+  fi
+
+  # ── Deferred ──────────────────────────────────────────────────────────────
+  if [[ $deferred_count -gt 0 ]]; then
+    echo -e "  ${DIM}Deferred  已推迟  (${deferred_count})${NC}"
+    while IFS= read -r line; do
+      [[ -z "$line" ]] && continue
+      local id desc reason
+      id=$(_backlog_extract_id "$line")
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-52)
+      reason=$(echo "$line" | awk -F'|' '{print $4}' | grep -oE '\[.*\]' | tr -d '[]' || true)
+      printf "    ${DIM}⏸ %-14s  %s${NC}" "$id" "$desc"
+      [[ -n "$reason" ]] && printf "${DIM}  (%s)${NC}" "$reason"
+      printf "\n"
+    done <<< "$deferred_items"
+    echo ""
+  fi
+
+  # ── Unknown status (show for human/AI triage) ─────────────────────────────
+  if [[ $unknown_count -gt 0 ]]; then
+    echo -e "  ${YELLOW}? Unknown Status  未知状态  (${unknown_count})${NC}"
+    echo -e "  ${YELLOW}  Fix: roll backlog block/defer/unblock <pattern>  运行命令修正状态${NC}"
+    while IFS= read -r line; do
+      [[ -z "$line" ]] && continue
+      local id desc status_raw
+      id=$(_backlog_extract_id "$line")
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-52)
+      status_raw=$(echo "$line" | awk -F'|' '{print $4}' | sed 's/^ *//;s/ *$//')
+      printf "    ${YELLOW}? %-14s  %s  [%s]${NC}\n" "$id" "$desc" "$status_raw"
+    done <<< "$unknown_items"
+    echo ""
+  fi
 }
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -2671,13 +3024,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
@@ -2761,7 +3119,10 @@ usage() {
   echo "  peer                   [Peer Review] Cross-agent negotiation               跨 Agent 协商对审"
   echo "  loop <on|off|now|status|monitor|resume|reset>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"
   echo "  brief                  [Digest] Show latest owner brief (regenerate if stale)  展示最新简报"
-  echo "  backlog                [View] Show all pending tasks from BACKLOG.md           显示待处理任务清单"
+  echo "  backlog                [View] Show pending tasks (Todo/Blocked/Deferred/Unknown)  显示任务清单"
+  echo "  backlog block <pat> [reason]  Mark matching items as 🔒 Blocked  标记为已阻塞"
+  echo "  backlog defer <pat> [reason]  Mark matching items as ⏸ Deferred  标记为已推迟"
+  echo "  backlog unblock <pat>         Restore matching items to 📋 Todo   恢复为待处理"
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
   echo ""
@@ -2771,7 +3132,9 @@ usage() {
   echo "  roll init                     # New or re-merge project (run in project)   新建或重新合并（项目目录）"
   echo "  roll loop on                  # Enable autonomous loop (cron)              启用自主执行循环"
   echo "  roll brief                    # Show latest brief                          查看最新简报"
-  echo "  roll backlog                  # Show pending BACKLOG items                 查看待处理任务"
+  echo "  roll backlog                  # Show pending/blocked/deferred items        查看待处理任务"
+  echo "  roll backlog defer US-DOC '过早引入'  # Defer all US-DOC-* items          推迟一类任务"
+  echo "  roll backlog block US-HW-001 '硬件未到货'  # Block a specific item        标记阻塞"
   echo "  roll agent use kimi           # Switch this project to kimi               切换当前项目到 kimi"
 
 }

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.8",
+  "version": "2026.512.2",
   "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-.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