@seanyao/roll 2026.511.5 → 2026.511.6

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v2026.511.8
+- **Fixed**: 集成测试 launchd ghost 泄漏 — `integration_teardown` 在删除 TEST_TMP 之前，先 `launchctl bootout` 该沙箱里被 `roll loop on` 注册到 user gui domain 的所有 `com.roll.*` 服务，避免删 plist 后 launchd 仍保留指向不存在路径的 ghost 注册。
+
+## v2026.511.7
+- **Added**: loop 执行 story 前显式标记 🔨 In Progress — roll-loop SKILL 在调用 executor 之前先把 BACKLOG 中的故事状态从 📋 Todo 改为 🔨 In Progress 并提交 `chore: mark US-XXX in progress`，brief 简报和 peer agent 都能即时感知正在进行的工作，tcr 微提交不再"对 brief 不可见"。
+- **Added**: loop 启动时孤儿 🔨 自愈 — 扫描 BACKLOG 中无对应 state.yaml running item 的 🔨 条目，视为上次崩溃残留，自动 revert 回 📋 Todo 并写 ALERT，避免被"卡"在错误的中间状态里。
+- **Improved**: roll-build / roll-fix SKILL 状态转换段更新 — 显式接受 📋 Todo 或 🔨 In Progress 作为 ✅ Done 前置状态，loop 触发链路状态过渡更稳健。
+
+## v2026.511.6
+- **Added**: Loop 并发安全 — runner script 启动时写入 per-project LOCK 文件并检测重入；活跃 PID 已存在则跳过本次，残留死 LOCK 自动清理；正常/异常退出均通过 trap 清掉 LOCK。彻底防止两个 loop 实例同时启动造成的 BACKLOG/git 冲突。
+- **Added**: roll-loop SKILL 显式声明 skip-🔨 In Progress 语义 — claude 扫 BACKLOG 时跳过已被人工或 peer agent 标记的执行中条目，为人机协同和多 agent 协作奠定基础。
+- **Fixed**: 5 个 pre-existing 测试失败 — `run_roll` helper 切换到 TEST_TMP 作为 cwd 避免 slug 冲突；loop status 测试匹配三态显示新文案；dashboard 测试匹配 `_launchd_svc_state` + array 派生 schedule 的新结构。
+
 ## v2026.511.5
 - **Fixed**: launchd plist 自动 reload — plist 内容变更且服务已加载时自动 unload + reload，升级 roll 后 loop 服务立即生效，无需手动重启
 - **Improved**: roll loop status/monitor 三态展示 — 区分 ● 运行中 / ⚠ 已安装未加载 / ○ 未安装，并给出对应的自愈操作提示

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.511.5"
+VERSION="2026.511.6"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1855,6 +1855,17 @@ _write_loop_runner_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-//')"
+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}"
+    exit 0
+  fi
+  rm -f "\$LOCK"
+fi
+echo "\$\$" > "\$LOCK"
+trap 'rm -f "\$LOCK"' EXIT
 cd "${project_path}" && ${cmd} >> "${log_path}" 2>&1
 SCRIPT
   chmod +x "$script_path"
@@ -2454,13 +2465,28 @@ _dashboard() {
   if $_dash_loop_enabled; then
     echo -e "  Loop  ${GREEN}● on${NC}   Agent: ${CYAN}${agent}${NC}"
     if [[ "$(uname)" == "Darwin" ]]; then
-      for svc_info in "loop:hourly" "dream:03:00" "brief:09:00"; do
-        local svc="${svc_info%%:*}" schedule="${svc_info#*:}"
-        if _launchd_is_loaded "$(_launchd_label "$svc" "$project_path")"; then
-          printf "    ${GREEN}%-8s ● enabled${NC}  (%s)\n" "$svc" "$schedule"
-        else
-          printf "    ${YELLOW}%-8s ○ disabled${NC} (%s)\n" "$svc" "$schedule"
-        fi
+      local active_start active_end loop_minute dream_hour dream_minute brief_hour brief_minute
+      active_start=$(_config_read_int "loop_active_start" "10")
+      active_end=$(_config_read_int "loop_active_end" "18")
+      loop_minute=$(_config_read_int "loop_minute" "$(_loop_derive_minute "$project_path" 0)")
+      dream_hour=$(_config_read_int "loop_dream_hour" "3")
+      dream_minute=$(_config_read_int "loop_dream_minute" "$(_loop_derive_minute "$project_path" 2)")
+      brief_hour=$(_config_read_int "loop_brief_hour" "9")
+      brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
+      local loop_sched dream_sched brief_sched
+      loop_sched=$(printf "every hour :%02d  active %02d:00–%02d:00" "$loop_minute" "$active_start" "$active_end")
+      dream_sched=$(printf "%02d:%02d" "$dream_hour" "$dream_minute")
+      brief_sched=$(printf "%02d:%02d" "$brief_hour" "$brief_minute")
+      local svcs=("loop" "dream" "brief")
+      local scheds=("$loop_sched" "$dream_sched" "$brief_sched")
+      for i in "${!svcs[@]}"; do
+        local svc="${svcs[$i]}" schedule="${scheds[$i]}"
+        local state; state=$(_launchd_svc_state "$svc" "$project_path")
+        case "$state" in
+          enabled)       printf "    ${GREEN}%-8s ● enabled${NC}  (%s)\n" "$svc" "$schedule" ;;
+          installed-off) printf "    ${YELLOW}%-8s ⚠ off${NC}       (%s)  run: roll loop on\n" "$svc" "$schedule" ;;
+          not-installed) printf "    ${RED}%-8s ○ missing${NC}  (%s)  run: roll setup\n" "$svc" "$schedule" ;;
+        esac
       done
     fi
   else

package/package.json

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

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

package/skills/roll-fix/SKILL.md

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

package/skills/roll-loop/SKILL.md

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