From c3c55439392229bb6bf25c6669f8c37b3f9ca724 Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 13:39:16 +0800
Subject: [PATCH] feat: skills - report auto-tmux swarm blockers

---
 skills/auto-tmux/AGENTS.md                    |   4 +-
 skills/auto-tmux/README.md                    |   1 +
 skills/auto-tmux/SKILL.md                     |   5 +-
 skills/auto-tmux/references/automation.md     |   3 +
 .../auto-tmux/references/iteration-roadmap.md |   3 +-
 skills/auto-tmux/scripts/AGENTS.md            |   2 +
 skills/auto-tmux/scripts/README.md            |   4 +
 .../auto-tmux/scripts/auto-tmux-smoke-test.sh |   8 +-
 skills/auto-tmux/scripts/auto-tmux.sh         |   2 +-
 skills/auto-tmux/scripts/swarm-blockers.sh    | 108 ++++++++++++++++++
 .../auto-tmux/scripts/validate-auto-tmux.sh   |   5 +
 11 files changed, 140 insertions(+), 5 deletions(-)
 create mode 100755 skills/auto-tmux/scripts/swarm-blockers.sh

diff --git a/skills/auto-tmux/AGENTS.md b/skills/auto-tmux/AGENTS.md
index 8e9717a..7f8a9a7 100644
--- a/skills/auto-tmux/AGENTS.md
+++ b/skills/auto-tmux/AGENTS.md
@@ -21,6 +21,7 @@ skills/auto-tmux/
 │   ├── swarm-deps-graph.sh
 │   ├── swarm-export.sh
 │   ├── swarm-timeline.sh
+│   ├── swarm-blockers.sh
 │   ├── swarm-assign.sh
 │   ├── swarm-health.sh
 │   ├── record-summary.sh
@@ -57,6 +58,7 @@ skills/auto-tmux/
 - `scripts/swarm-deps-graph.sh` 是依赖可视化层，将 `deps.tsv` 渲染为 Mermaid 图。
 - `scripts/swarm-export.sh` 是机器可读导出层，将任务、依赖和锁导出为 JSONL。
 - `scripts/swarm-timeline.sh` 是状态时间线层，将 `status.log` 渲染为 Markdown。
+- `scripts/swarm-blockers.sh` 是阻塞报告层，聚合 BLOCKED/FAIL、锁和异常状态。
 - `scripts/swarm-assign.sh` 是分配建议层，将 ready task 轮询映射到 worker pane。
 - `scripts/swarm-health.sh` 是健康检查层，汇总 tmux 和 swarm state 的只读报告包。
 - `scripts/record-summary.sh` 是复盘摘要层，将 pane 录制日志整理为 Markdown。
@@ -73,4 +75,4 @@ skills/auto-tmux/
 - 上游来源：`tools/external/.tmux` 与 `tools/external/tmux`。
 - 下游使用：`SKILL.md` 和 `references/` 中的命令示例。
 - 验证入口：`skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict`。
-- 脚本验证：`skills/auto-tmux/scripts/validate-auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh`、`bash -n skills/auto-tmux/scripts/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh`、`bash -n skills/auto-tmux/scripts/swarm-export.sh`、`bash -n skills/auto-tmux/scripts/swarm-timeline.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/completion.bash`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh`、`skills/auto-tmux/scripts/auto-tmux-smoke-test.sh`。
+- 脚本验证：`skills/auto-tmux/scripts/validate-auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh`、`bash -n skills/auto-tmux/scripts/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh`、`bash -n skills/auto-tmux/scripts/swarm-export.sh`、`bash -n skills/auto-tmux/scripts/swarm-timeline.sh`、`bash -n skills/auto-tmux/scripts/swarm-blockers.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/completion.bash`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh`、`skills/auto-tmux/scripts/auto-tmux-smoke-test.sh`。
diff --git a/skills/auto-tmux/README.md b/skills/auto-tmux/README.md
index 7dfc18b..80f877b 100644
--- a/skills/auto-tmux/README.md
+++ b/skills/auto-tmux/README.md
@@ -28,6 +28,7 @@ bash -n skills/auto-tmux/scripts/swarm-board.sh
 bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh
 bash -n skills/auto-tmux/scripts/swarm-export.sh
 bash -n skills/auto-tmux/scripts/swarm-timeline.sh
+bash -n skills/auto-tmux/scripts/swarm-blockers.sh
 bash -n skills/auto-tmux/scripts/swarm-assign.sh
 bash -n skills/auto-tmux/scripts/swarm-health.sh
 bash -n skills/auto-tmux/scripts/record-summary.sh
diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index 6f66a37..fb4635e 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -42,6 +42,7 @@ bash -n skills/auto-tmux/scripts/swarm-board.sh
 bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh
 bash -n skills/auto-tmux/scripts/swarm-export.sh
 bash -n skills/auto-tmux/scripts/swarm-timeline.sh
+bash -n skills/auto-tmux/scripts/swarm-blockers.sh
 bash -n skills/auto-tmux/scripts/swarm-assign.sh
 bash -n skills/auto-tmux/scripts/swarm-health.sh
 bash -n skills/auto-tmux/scripts/record-summary.sh
@@ -129,6 +130,7 @@ skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-
 skills/auto-tmux/scripts/swarm-deps-graph.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-deps.md
 skills/auto-tmux/scripts/swarm-export.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-export
 skills/auto-tmux/scripts/swarm-timeline.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-timeline.md
+skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-blockers.md
 skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md
 skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-health
 ```
@@ -279,6 +281,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `scripts/swarm-deps-graph.sh`: 渲染 `deps.tsv` 的 Mermaid 依赖图
 - `scripts/swarm-export.sh`: 导出任务、依赖和锁的 JSONL 状态包
 - `scripts/swarm-timeline.sh`: 渲染 `status.log` 的 Markdown 时间线
+- `scripts/swarm-blockers.sh`: 聚合 BLOCKED/FAIL 任务、锁和最近异常状态
 - `scripts/swarm-assign.sh`: 根据 ready tasks 和 worker pane 生成只读分配建议
 - `scripts/swarm-health.sh`: 汇总 tmux 与 swarm state 的只读健康检查报告包
 - `scripts/record-summary.sh`: 汇总 pane 录制日志并生成复盘摘要
@@ -306,6 +309,6 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 4. ≥3 个端到端示例，含输入/步骤/验收。
 5. 长文档放在 `references/` 并可导航；无文档堆砌。
 6. 不确定项给出验证路径；禁止虚构 tmux 行为。
-7. `bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh`、`bash -n skills/auto-tmux/scripts/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh`、`bash -n skills/auto-tmux/scripts/swarm-export.sh`、`bash -n skills/auto-tmux/scripts/swarm-timeline.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/completion.bash`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh` 与 `bash -n skills/auto-tmux/scripts/validate-auto-tmux.sh` 通过。
+7. `bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh`、`bash -n skills/auto-tmux/scripts/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh`、`bash -n skills/auto-tmux/scripts/swarm-export.sh`、`bash -n skills/auto-tmux/scripts/swarm-timeline.sh`、`bash -n skills/auto-tmux/scripts/swarm-blockers.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/completion.bash`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh` 与 `bash -n skills/auto-tmux/scripts/validate-auto-tmux.sh` 通过。
 8. `skills/auto-tmux/scripts/auto-tmux-smoke-test.sh` 通过或在无 tmux 环境下明确跳过。
 9. 运行 `skills/auto-tmux/scripts/validate-auto-tmux.sh` 和 `skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict` 通过。
diff --git a/skills/auto-tmux/references/automation.md b/skills/auto-tmux/references/automation.md
index 587a409..5acc273 100644
--- a/skills/auto-tmux/references/automation.md
+++ b/skills/auto-tmux/references/automation.md
@@ -37,6 +37,7 @@
 | `swarm-deps-graph.sh` | 渲染任务依赖图 | 只读生成 Mermaid |
 | `swarm-export.sh` | 导出 JSONL 状态包 | 只读读取 state，写显式输出目录 |
 | `swarm-timeline.sh` | 渲染状态日志时间线 | 只读生成 Markdown |
+| `swarm-blockers.sh` | 聚合阻塞、失败、锁和异常状态 | 只读生成 Markdown |
 | `swarm-assign.sh` | 生成 ready task 到 worker pane 的分配建议 | 只读，不 claim，不发送 |
 | `swarm-health.sh` | 汇总 tmux 与 swarm state 健康报告 | 只读，不自动修复 |
 | `record-summary.sh` | 汇总 pane 录制日志 | 只读，输出默认脱敏 |
@@ -110,6 +111,7 @@ skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-
 skills/auto-tmux/scripts/swarm-deps-graph.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-deps.md
 skills/auto-tmux/scripts/swarm-export.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-export
 skills/auto-tmux/scripts/swarm-timeline.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-timeline.md
+skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-blockers.md
 skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md
 skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-health
 ```
@@ -269,6 +271,7 @@ bash -n skills/auto-tmux/scripts/swarm-board.sh
 bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh
 bash -n skills/auto-tmux/scripts/swarm-export.sh
 bash -n skills/auto-tmux/scripts/swarm-timeline.sh
+bash -n skills/auto-tmux/scripts/swarm-blockers.sh
 bash -n skills/auto-tmux/scripts/swarm-assign.sh
 bash -n skills/auto-tmux/scripts/swarm-health.sh
 bash -n skills/auto-tmux/scripts/record-summary.sh
diff --git a/skills/auto-tmux/references/iteration-roadmap.md b/skills/auto-tmux/references/iteration-roadmap.md
index 7cf62e5..e7381ca 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -33,7 +33,8 @@
 | 25 | `38ccefe` | shell completion | `completion.bash` |
 | 26 | `9e33018` | 依赖可视化 | `swarm-deps-graph.sh` |
 | 27 | `f98841d` | 机器可读导出 | `swarm-export.sh` |
-| 28 | `本轮` | 状态时间线 | `swarm-timeline.sh` |
+| 28 | `c6eeb1f` | 状态时间线 | `swarm-timeline.sh` |
+| 29 | `本轮` | 阻塞报告 | `swarm-blockers.sh` |
 
 ## 后续候选方向
 
diff --git a/skills/auto-tmux/scripts/AGENTS.md b/skills/auto-tmux/scripts/AGENTS.md
index 6b71b83..0cf3e53 100644
--- a/skills/auto-tmux/scripts/AGENTS.md
+++ b/skills/auto-tmux/scripts/AGENTS.md
@@ -17,6 +17,7 @@ scripts/
 ├── swarm-deps-graph.sh # 从 deps.tsv 渲染 Mermaid 依赖图
 ├── swarm-export.sh # 导出 JSONL 状态包
 ├── swarm-timeline.sh # 从 status.log 渲染 Markdown 时间线
+├── swarm-blockers.sh # 聚合 BLOCKED/FAIL、锁和异常状态
 ├── swarm-assign.sh # 生成 ready task 到 worker pane 的分配建议
 ├── swarm-health.sh # 汇总只读健康检查报告包
 ├── record-summary.sh # 汇总 pipe-pane 录制日志
@@ -44,6 +45,7 @@ scripts/
 - 依赖图脚本只读 `tasks.tsv` 和 `deps.tsv`，不改写状态目录。
 - 导出脚本只读 `tasks.tsv`、`deps.tsv` 和锁目录，只写显式输出目录。
 - 时间线脚本只读 `status.log`，不改写状态目录。
+- 阻塞报告脚本只读任务、锁和状态日志，不做自动修复。
 - 分配建议脚本只读任务和 pane 拓扑，不 claim 任务、不发送 prompt。
 - 健康检查脚本只读 tmux 与 swarm state，失败项写入报告，不做自动修复。
 - 录制摘要脚本只读 record 日志，输出默认脱敏，不修改日志源文件。
diff --git a/skills/auto-tmux/scripts/README.md b/skills/auto-tmux/scripts/README.md
index cfcfe2f..90ef15f 100644
--- a/skills/auto-tmux/scripts/README.md
+++ b/skills/auto-tmux/scripts/README.md
@@ -13,6 +13,7 @@
 - [`swarm-deps-graph.sh`](./swarm-deps-graph.sh) - 将 `deps.tsv` 渲染为 Mermaid 依赖图。
 - [`swarm-export.sh`](./swarm-export.sh) - 将任务、依赖和锁导出为 JSONL 包。
 - [`swarm-timeline.sh`](./swarm-timeline.sh) - 将 `status.log` 渲染为 Markdown 时间线。
+- [`swarm-blockers.sh`](./swarm-blockers.sh) - 聚合 BLOCKED/FAIL 任务、锁和最近异常状态。
 - [`swarm-assign.sh`](./swarm-assign.sh) - 根据 ready tasks 和 worker pane 生成只读分配建议。
 - [`swarm-health.sh`](./swarm-health.sh) - 汇总 doctor、topology、scan、validate、metrics、board 和 assign。
 - [`record-summary.sh`](./record-summary.sh) - 汇总 `record start` 产生的 pane 日志，生成复盘摘要。
@@ -78,6 +79,9 @@ skills/auto-tmux/scripts/swarm-export.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm
 # 生成状态时间线
 skills/auto-tmux/scripts/swarm-timeline.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-timeline.md
 
+# 生成阻塞清单
+skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-blockers.md
+
 # 生成 worker 分配建议
 skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md
 
diff --git a/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh b/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
index 25d5628..15b183b 100755
--- a/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
+++ b/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
@@ -13,6 +13,7 @@ SWARM_BOARD="$SCRIPT_DIR/swarm-board.sh"
 SWARM_DEPS_GRAPH="$SCRIPT_DIR/swarm-deps-graph.sh"
 SWARM_EXPORT="$SCRIPT_DIR/swarm-export.sh"
 SWARM_TIMELINE="$SCRIPT_DIR/swarm-timeline.sh"
+SWARM_BLOCKERS="$SCRIPT_DIR/swarm-blockers.sh"
 SWARM_ASSIGN="$SCRIPT_DIR/swarm-assign.sh"
 SWARM_HEALTH="$SCRIPT_DIR/swarm-health.sh"
 RECORD_SUMMARY="$SCRIPT_DIR/record-summary.sh"
@@ -32,6 +33,7 @@ BOARD_FILE="/tmp/auto-tmux-smoke-board-$$.md"
 DEPS_GRAPH_FILE="/tmp/auto-tmux-smoke-deps-graph-$$.md"
 EXPORT_DIR="/tmp/auto-tmux-smoke-export-$$"
 TIMELINE_FILE="/tmp/auto-tmux-smoke-timeline-$$.md"
+BLOCKERS_FILE="/tmp/auto-tmux-smoke-blockers-$$.md"
 ASSIGN_FILE="/tmp/auto-tmux-smoke-assign-$$.md"
 HEALTH_DIR="/tmp/auto-tmux-smoke-health-$$"
 DISPATCH_PROMPT="/tmp/auto-tmux-smoke-dispatch-$$.md"
@@ -40,7 +42,7 @@ PASTE_FILE="/tmp/auto-tmux-smoke-paste-$$.txt"
 
 cleanup() {
   tmux kill-session -t "$SESSION" 2>/dev/null || true
-  rm -rf "$SWARM_DIR" "$DEP_SWARM_DIR" "$SNAPSHOT_DIR" "$RECORD_DIR" "$RECORD_SUMMARY_FILE" "$BRIEF_DIR" "$WATCH_DIR" "$ARCHIVE_FILE" "$BOARD_FILE" "$DEPS_GRAPH_FILE" "$EXPORT_DIR" "$TIMELINE_FILE" "$ASSIGN_FILE" "$HEALTH_DIR" "$DISPATCH_PROMPT" "$TASK_IMPORT_FILE" "$PASTE_FILE"
+  rm -rf "$SWARM_DIR" "$DEP_SWARM_DIR" "$SNAPSHOT_DIR" "$RECORD_DIR" "$RECORD_SUMMARY_FILE" "$BRIEF_DIR" "$WATCH_DIR" "$ARCHIVE_FILE" "$BOARD_FILE" "$DEPS_GRAPH_FILE" "$EXPORT_DIR" "$TIMELINE_FILE" "$BLOCKERS_FILE" "$ASSIGN_FILE" "$HEALTH_DIR" "$DISPATCH_PROMPT" "$TASK_IMPORT_FILE" "$PASTE_FILE"
 }
 trap cleanup EXIT
 
@@ -59,6 +61,7 @@ bash -n "$SWARM_BOARD"
 bash -n "$SWARM_DEPS_GRAPH"
 bash -n "$SWARM_EXPORT"
 bash -n "$SWARM_TIMELINE"
+bash -n "$SWARM_BLOCKERS"
 bash -n "$SWARM_ASSIGN"
 bash -n "$SWARM_HEALTH"
 bash -n "$RECORD_SUMMARY"
@@ -167,6 +170,9 @@ grep -q '"task_id":"dep-b"' "$EXPORT_DIR/deps.jsonl"
 "$SWARM_TIMELINE" --dir "$SWARM_DIR" --out "$TIMELINE_FILE" -n 50 >/tmp/auto-tmux-smoke-timeline.txt
 grep -q 'auto-tmux Swarm Timeline' "$TIMELINE_FILE"
 grep -q 'DONE' "$TIMELINE_FILE"
+"$SWARM_BLOCKERS" --dir "$SWARM_DIR" --out "$BLOCKERS_FILE" -n 50 >/tmp/auto-tmux-smoke-blockers.txt
+grep -q 'auto-tmux Swarm Blockers' "$BLOCKERS_FILE"
+grep -q 'smoke-fail' "$BLOCKERS_FILE"
 "$SWARM_ASSIGN" --swarm-dir "$SWARM_DIR" --session "$SESSION" --out "$ASSIGN_FILE" --limit 20 >/tmp/auto-tmux-smoke-assign.txt
 grep -q 'auto-tmux Swarm Assignment Suggestions' "$ASSIGN_FILE"
 grep -q 'swarm-dispatch.sh' "$ASSIGN_FILE"
diff --git a/skills/auto-tmux/scripts/auto-tmux.sh b/skills/auto-tmux/scripts/auto-tmux.sh
index eeb2702..ca13db9 100755
--- a/skills/auto-tmux/scripts/auto-tmux.sh
+++ b/skills/auto-tmux/scripts/auto-tmux.sh
@@ -153,7 +153,7 @@ cmd_doctor() {
     status_line "WARN" "tmux server has no reachable session yet"
   fi
 
-  for script in auto-tmux.sh swarm-state.sh swarm-brief.sh swarm-watch.sh swarm-archive.sh swarm-board.sh swarm-deps-graph.sh swarm-export.sh swarm-timeline.sh swarm-assign.sh swarm-health.sh record-summary.sh safety-check.sh render-swarm-prompt.sh swarm-dispatch.sh auto-tmux-smoke-test.sh validate-auto-tmux.sh; do
+  for script in auto-tmux.sh swarm-state.sh swarm-brief.sh swarm-watch.sh swarm-archive.sh swarm-board.sh swarm-deps-graph.sh swarm-export.sh swarm-timeline.sh swarm-blockers.sh swarm-assign.sh swarm-health.sh record-summary.sh safety-check.sh render-swarm-prompt.sh swarm-dispatch.sh auto-tmux-smoke-test.sh validate-auto-tmux.sh; do
     if [[ -x "$script_dir/$script" ]]; then
       status_line "OK" "script executable: $script"
     else
diff --git a/skills/auto-tmux/scripts/swarm-blockers.sh b/skills/auto-tmux/scripts/swarm-blockers.sh
new file mode 100755
index 0000000..0b2d408
--- /dev/null
+++ b/skills/auto-tmux/scripts/swarm-blockers.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# swarm-blockers: render blocked/failed tasks and active locks as Markdown.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+swarm-blockers: summarize auto-tmux blockers
+
+Usage:
+  swarm-blockers.sh [--dir DIR] [--out FILE] [-n LINES]
+
+Defaults:
+  --dir AUTO_TMUX_SWARM_DIR or /tmp/ai_swarm
+  --out stdout
+  -n    50 recent status lines
+
+This script is read-only. It does not mutate swarm state.
+EOF
+}
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+swarm_dir="${AUTO_TMUX_SWARM_DIR:-/tmp/ai_swarm}"
+out_file=""
+lines=50
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir|--swarm-dir)
+      swarm_dir="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out_file="${2:-}"
+      shift 2
+      ;;
+    -n|--lines)
+      lines="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unknown option: $1"
+      ;;
+  esac
+done
+
+[[ "$lines" =~ ^[0-9]+$ ]] || die "--lines must be a number"
+tasks_tsv="$swarm_dir/tasks.tsv"
+locks_dir="$swarm_dir/locks"
+status_log="$swarm_dir/status.log"
+[[ -f "$tasks_tsv" ]] || die "tasks file not found: $tasks_tsv"
+
+render_blockers() {
+  printf '# auto-tmux Swarm Blockers\n\n'
+  printf -- '- dir: `%s`\n' "$swarm_dir"
+  printf -- '- created_at: `%s`\n\n' "$(date -Is)"
+
+  printf '## BLOCKED / FAIL Tasks\n\n'
+  printf '| status | id | owner | text | result |\n'
+  printf '|:---|:---|:---|:---|:---|\n'
+  awk -F '\t' '
+    function esc(value) {
+      gsub(/\|/, "\\|", value)
+      return value
+    }
+    NR > 1 && ($2 == "BLOCKED" || $2 == "FAIL") {
+      print "| `" esc($2) "` | `" esc($1) "` | `" esc($3) "` | " esc($4) " | " esc($5) " |"
+      found = 1
+    }
+    END {if (!found) print "| - | - | - | - | - |"}
+  ' "$tasks_tsv"
+
+  printf '\n## Active Locks\n\n'
+  printf '| lock | owner | created_at |\n'
+  printf '|:---|:---|:---|\n'
+  if [[ -d "$locks_dir" ]] && find "$locks_dir" -mindepth 1 -maxdepth 1 -type d -name '*.lock.d' -print -quit | grep -q .; then
+    find "$locks_dir" -mindepth 1 -maxdepth 1 -type d -name '*.lock.d' -print | sort | while read -r path; do
+      printf '| `%s` | `%s` | %s |\n' \
+        "$(basename "$path" .lock.d)" \
+        "$(cat "$path/owner" 2>/dev/null || printf unknown)" \
+        "$(cat "$path/created_at" 2>/dev/null || printf unknown)"
+    done
+  else
+    printf '| - | - | - |\n'
+  fi
+
+  printf '\n## Recent Risk Status\n\n'
+  if [[ -s "$status_log" ]]; then
+    tail -n "$lines" "$status_log" | grep -E '\[(BLOCKED|FAIL|ERROR|HELP)\]' | sed 's/^/- /' || printf -- '- no recent risk status\n'
+  else
+    printf -- '- no status log\n'
+  fi
+}
+
+if [[ -n "$out_file" ]]; then
+  mkdir -p "$(dirname "$out_file")"
+  render_blockers > "$out_file"
+  printf 'swarm blockers written: %s\n' "$out_file"
+else
+  render_blockers
+fi
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index 2d63a53..94319ee 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -86,6 +86,7 @@ scripts=(
   "$script_dir/swarm-deps-graph.sh"
   "$script_dir/swarm-export.sh"
   "$script_dir/swarm-timeline.sh"
+  "$script_dir/swarm-blockers.sh"
   "$script_dir/swarm-assign.sh"
   "$script_dir/swarm-health.sh"
   "$script_dir/record-summary.sh"
@@ -112,6 +113,7 @@ run_gate "swarm-board help" "$script_dir/swarm-board.sh" --help
 run_gate "swarm-deps-graph help" "$script_dir/swarm-deps-graph.sh" --help
 run_gate "swarm-export help" "$script_dir/swarm-export.sh" --help
 run_gate "swarm-timeline help" "$script_dir/swarm-timeline.sh" --help
+run_gate "swarm-blockers help" "$script_dir/swarm-blockers.sh" --help
 run_gate "swarm-assign help" "$script_dir/swarm-assign.sh" --help
 run_gate "swarm-health help" "$script_dir/swarm-health.sh" --help
 run_gate "record-summary help" "$script_dir/record-summary.sh" --help
@@ -133,6 +135,7 @@ require_contains "$skill_dir/SKILL.md" "scripts/swarm-board.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-deps-graph.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-export.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-timeline.sh"
+require_contains "$skill_dir/SKILL.md" "scripts/swarm-blockers.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-assign.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-health.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/record-summary.sh"
@@ -151,6 +154,7 @@ require_contains "$script_dir/README.md" "swarm-board.sh"
 require_contains "$script_dir/README.md" "swarm-deps-graph.sh"
 require_contains "$script_dir/README.md" "swarm-export.sh"
 require_contains "$script_dir/README.md" "swarm-timeline.sh"
+require_contains "$script_dir/README.md" "swarm-blockers.sh"
 require_contains "$script_dir/README.md" "swarm-assign.sh"
 require_contains "$script_dir/README.md" "swarm-health.sh"
 require_contains "$script_dir/README.md" "record-summary.sh"
@@ -164,6 +168,7 @@ require_contains "$script_dir/AGENTS.md" "swarm-board.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-deps-graph.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-export.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-timeline.sh"
+require_contains "$script_dir/AGENTS.md" "swarm-blockers.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-assign.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-health.sh"
 require_contains "$script_dir/AGENTS.md" "record-summary.sh"