feat: skills - report auto-tmux swarm health

skills/auto-tmux/AGENTS.md

@@ -19,6 +19,7 @@ skills/auto-tmux/
 │   ├── swarm-archive.sh
 │   ├── swarm-board.sh
 │   ├── swarm-assign.sh
+│   ├── swarm-health.sh
 │   ├── record-summary.sh
 │   ├── safety-check.sh
 │   ├── render-swarm-prompt.sh
@@ -50,6 +51,7 @@ skills/auto-tmux/
 - `scripts/swarm-archive.sh` 是归档层，打包 brief、snapshot 和 swarm state 供复盘交接。
 - `scripts/swarm-board.sh` 是看板层，将任务、依赖、锁和状态日志渲染为 Markdown。
 - `scripts/swarm-assign.sh` 是分配建议层，将 ready task 轮询映射到 worker pane。
+- `scripts/swarm-health.sh` 是健康检查层，汇总 tmux 和 swarm state 的只读报告包。
 - `scripts/record-summary.sh` 是复盘摘要层，将 pane 录制日志整理为 Markdown。
 - `scripts/safety-check.sh` 是安全预检层，检查待发送 payload 的危险命令、敏感信息和大小。
 - `scripts/render-swarm-prompt.sh` 是提示词渲染层，生成 commander/worker/reviewer 协议文本。
@@ -63,4 +65,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-assign.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`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-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/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/README.md

@@ -26,6 +26,7 @@ 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-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/safety-check.sh
 bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh

skills/auto-tmux/SKILL.md

@@ -40,6 +40,7 @@ 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-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/safety-check.sh
 bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
@@ -122,6 +123,7 @@ skills/auto-tmux/scripts/swarm-watch.sh --session ai-hub --swarm-dir /tmp/ai_swa
 skills/auto-tmux/scripts/swarm-archive.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/ai-hub-handoff.tar.gz
 skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-board.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
 ```
 
 **远程救援：发现等待输入即发送 y**
@@ -267,6 +269,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `scripts/swarm-archive.sh`: 打包 brief、snapshot 和 swarm state 的交接归档
 - `scripts/swarm-board.sh`: 渲染任务、依赖、锁和状态日志的 Markdown 看板
 - `scripts/swarm-assign.sh`: 根据 ready tasks 和 worker pane 生成只读分配建议
+- `scripts/swarm-health.sh`: 汇总 tmux 与 swarm state 的只读健康检查报告包
 - `scripts/record-summary.sh`: 汇总 pane 录制日志并生成复盘摘要
 - `scripts/safety-check.sh`: 发送/粘贴/分发前检查危险命令、敏感信息和过大 payload
 - `scripts/render-swarm-prompt.sh`: commander/worker/reviewer 提示词渲染脚本
@@ -291,6 +294,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-assign.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`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-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/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` 通过。

skills/auto-tmux/references/automation.md

@@ -35,6 +35,7 @@
 | `swarm-archive.sh` | 打包 brief、snapshot 和 state | 生成可交接 `.tar.gz` |
 | `swarm-board.sh` | 渲染任务、依赖、锁和状态日志 | 只读生成 Markdown 看板 |
 | `swarm-assign.sh` | 生成 ready task 到 worker pane 的分配建议 | 只读，不 claim，不发送 |
+| `swarm-health.sh` | 汇总 tmux 与 swarm state 健康报告 | 只读，不自动修复 |
 | `record-summary.sh` | 汇总 pane 录制日志 | 只读，输出默认脱敏 |
 | `swarm-dispatch.sh` | 渲染并可选下发提示词 | 默认只写文件，发送需 `--send` |
 | `validate-auto-tmux.sh` | 执行技能专属质量门禁 | 覆盖脚本、文档索引、strict 和 smoke |
@@ -103,6 +104,7 @@ skills/auto-tmux/scripts/swarm-watch.sh --session ai-hub --swarm-dir /tmp/ai_swa
 skills/auto-tmux/scripts/swarm-archive.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/ai-hub-handoff.tar.gz
 skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-board.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
 ```
 
 发送前对 payload 做安全预检：
@@ -258,6 +260,7 @@ 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-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/safety-check.sh
 bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh

skills/auto-tmux/references/iteration-roadmap.md

@@ -28,7 +28,8 @@
 | 20 | `6d46748` | 状态可视化 | `swarm-board.sh` |
 | 21 | `d8e7d31` | 依赖领取一致性 | `task-next` 尊重 `blocked-by` |
 | 22 | `cc69865` | worker 分配 | `swarm-assign.sh` |
-| 23 | `本轮` | replay 审计 | `record-summary.sh` |
+| 23 | `004d942` | replay 审计 | `record-summary.sh` |
+| 24 | `本轮` | 健康检查 | `swarm-health.sh` |
 
 ## 后续候选方向
 

skills/auto-tmux/scripts/AGENTS.md

@@ -15,6 +15,7 @@ scripts/
 ├── swarm-archive.sh # 打包 brief、snapshot 和 swarm state
 ├── swarm-board.sh # 从 swarm state 渲染 Markdown 看板
 ├── swarm-assign.sh # 生成 ready task 到 worker pane 的分配建议
+├── swarm-health.sh # 汇总只读健康检查报告包
 ├── record-summary.sh # 汇总 pipe-pane 录制日志
 ├── safety-check.sh # 发送/粘贴/分发前的 payload 安全预检
 ├── render-swarm-prompt.sh # commander/worker/reviewer 提示词渲染
@@ -37,6 +38,7 @@ scripts/
 - 归档脚本只复制状态和只读证据，不修改 tmux pane 或 swarm state。
 - 看板脚本只读 `tasks.tsv`、`deps.tsv`、锁和状态日志，不改写状态目录。
 - 分配建议脚本只读任务和 pane 拓扑，不 claim 任务、不发送 prompt。
+- 健康检查脚本只读 tmux 与 swarm state，失败项写入报告，不做自动修复。
 - 录制摘要脚本只读 record 日志，输出默认脱敏，不修改日志源文件。
 - 安全预检脚本只能读取文本或文件，不控制 tmux，不写状态目录。
 - 状态脚本只能写入显式状态目录，不保存密钥、Token、密码或私密项目内容。

skills/auto-tmux/scripts/README.md

@@ -11,6 +11,7 @@
 - [`swarm-archive.sh`](./swarm-archive.sh) - 打包 brief、snapshot 和 swarm state，生成可交接归档。
 - [`swarm-board.sh`](./swarm-board.sh) - 将 `tasks.tsv`、依赖、锁和状态日志渲染为 Markdown 看板。
 - [`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 日志，生成复盘摘要。
 - [`safety-check.sh`](./safety-check.sh) - 发送、粘贴或分发前检查危险命令、敏感信息和过大 payload。
 - [`render-swarm-prompt.sh`](./render-swarm-prompt.sh) - commander、worker、reviewer 提示词渲染。
@@ -67,6 +68,9 @@ skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-
 # 生成 worker 分配建议
 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
+
 # 汇总 pane 录制日志
 skills/auto-tmux/scripts/record-summary.sh --dir /tmp/auto-tmux-records --out /tmp/auto-tmux-record-summary.md
 

skills/auto-tmux/scripts/auto-tmux-smoke-test.sh

@@ -11,6 +11,7 @@ SWARM_WATCH="$SCRIPT_DIR/swarm-watch.sh"
 SWARM_ARCHIVE="$SCRIPT_DIR/swarm-archive.sh"
 SWARM_BOARD="$SCRIPT_DIR/swarm-board.sh"
 SWARM_ASSIGN="$SCRIPT_DIR/swarm-assign.sh"
+SWARM_HEALTH="$SCRIPT_DIR/swarm-health.sh"
 RECORD_SUMMARY="$SCRIPT_DIR/record-summary.sh"
 SAFETY_CHECK="$SCRIPT_DIR/safety-check.sh"
 SWARM_DISPATCH="$SCRIPT_DIR/swarm-dispatch.sh"
@@ -25,13 +26,14 @@ WATCH_DIR="/tmp/auto-tmux-smoke-watch-$$"
 ARCHIVE_FILE="/tmp/auto-tmux-smoke-archive-$$.tar.gz"
 BOARD_FILE="/tmp/auto-tmux-smoke-board-$$.md"
 ASSIGN_FILE="/tmp/auto-tmux-smoke-assign-$$.md"
+HEALTH_DIR="/tmp/auto-tmux-smoke-health-$$"
 DISPATCH_PROMPT="/tmp/auto-tmux-smoke-dispatch-$$.md"
 TASK_IMPORT_FILE="/tmp/auto-tmux-smoke-tasks-$$.txt"
 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" "$ASSIGN_FILE" "$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" "$ASSIGN_FILE" "$HEALTH_DIR" "$DISPATCH_PROMPT" "$TASK_IMPORT_FILE" "$PASTE_FILE"
 }
 trap cleanup EXIT
 
@@ -48,6 +50,7 @@ bash -n "$SWARM_WATCH"
 bash -n "$SWARM_ARCHIVE"
 bash -n "$SWARM_BOARD"
 bash -n "$SWARM_ASSIGN"
+bash -n "$SWARM_HEALTH"
 bash -n "$RECORD_SUMMARY"
 bash -n "$SAFETY_CHECK"
 bash -n "$SWARM_DISPATCH"
@@ -146,6 +149,10 @@ grep -q 'smoke-fail' "$BOARD_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"
+"$SWARM_HEALTH" --session "$SESSION" --swarm-dir "$SWARM_DIR" --out "$HEALTH_DIR" -n 10 >/tmp/auto-tmux-smoke-health.txt
+grep -q 'auto-tmux Swarm Health' "$HEALTH_DIR/index.md"
+test -s "$HEALTH_DIR/state-validate.txt"
+test -s "$HEALTH_DIR/board.md"
 "$RENDER_PROMPT" commander --session "$SESSION" --swarm-dir "$SWARM_DIR" --task "smoke" >/tmp/auto-tmux-smoke-commander-prompt.md
 "$RENDER_PROMPT" worker --session "$SESSION" --target "$worker_target" --swarm-dir "$SWARM_DIR" --task "smoke" >/tmp/auto-tmux-smoke-worker-prompt.md
 "$SWARM_DISPATCH" --role worker --target "$worker_target" --session "$SESSION" --swarm-dir "$SWARM_DIR" --task "smoke" --out "$DISPATCH_PROMPT" >/tmp/auto-tmux-smoke-dispatch-render.txt

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-assign.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-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

skills/auto-tmux/scripts/swarm-health.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# swarm-health: build a read-only health report for an auto-tmux swarm.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+swarm-health: build an auto-tmux swarm health report
+
+Usage:
+  swarm-health.sh [--session NAME] [--swarm-dir DIR] [--out DIR] [-n LINES]
+
+Defaults:
+  --swarm-dir AUTO_TMUX_SWARM_DIR or /tmp/ai_swarm
+  --out       /tmp/auto-tmux-health-YYYYmmdd-HHMMSS
+  -n          80 pane output lines
+
+This script is read-only. It does not send keys, claim tasks or mutate state.
+EOF
+}
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+auto_tmux="$script_dir/auto-tmux.sh"
+swarm_state="$script_dir/swarm-state.sh"
+swarm_board="$script_dir/swarm-board.sh"
+swarm_assign="$script_dir/swarm-assign.sh"
+
+session=""
+swarm_dir="${AUTO_TMUX_SWARM_DIR:-/tmp/ai_swarm}"
+out_dir="/tmp/auto-tmux-health-$(date +%Y%m%d-%H%M%S)"
+lines=80
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session)
+      session="${2:-}"
+      shift 2
+      ;;
+    --swarm-dir|--dir)
+      swarm_dir="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out_dir="${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"
+mkdir -p "$out_dir"
+
+run_optional() {
+  local label="$1"
+  local file="$2"
+  shift 2
+  if "$@" > "$out_dir/$file" 2>&1; then
+    printf '[OK] %s\n' "$label"
+  else
+    printf '[WARN] %s failed; see %s\n' "$label" "$file"
+  fi
+}
+
+{
+  printf '# auto-tmux Swarm Health\n\n'
+  printf -- '- created_at: `%s`\n' "$(date -Is)"
+  printf -- '- session: `%s`\n' "${session:-<not provided>}"
+  printf -- '- swarm_dir: `%s`\n' "$swarm_dir"
+  printf -- '- output_dir: `%s`\n\n' "$out_dir"
+  printf '## Files\n\n'
+  printf -- '- `doctor.txt`\n'
+  printf -- '- `topology.txt`\n'
+  printf -- '- `scan.txt`\n'
+  printf -- '- `state-validate.txt`\n'
+  printf -- '- `metrics.md`\n'
+  printf -- '- `board.md`\n'
+  printf -- '- `assign.md`\n'
+} > "$out_dir/index.md"
+
+if [[ -n "$session" ]]; then
+  run_optional "doctor" "doctor.txt" "$auto_tmux" doctor --session "$session"
+  run_optional "topology" "topology.txt" "$auto_tmux" topology --session "$session"
+  run_optional "scan" "scan.txt" "$auto_tmux" scan --session "$session" -n "$lines"
+else
+  printf 'session not provided; skipped tmux doctor/topology/scan\n' > "$out_dir/doctor.txt"
+  : > "$out_dir/topology.txt"
+  : > "$out_dir/scan.txt"
+fi
+
+if [[ -f "$swarm_dir/tasks.tsv" && -f "$swarm_dir/deps.tsv" ]]; then
+  run_optional "state validate" "state-validate.txt" "$swarm_state" validate --dir "$swarm_dir"
+  run_optional "metrics" "metrics.md" "$swarm_state" metrics --dir "$swarm_dir"
+  run_optional "board" "board.md" "$swarm_board" --dir "$swarm_dir"
+  if [[ -n "$session" ]]; then
+    run_optional "assign" "assign.md" "$swarm_assign" --swarm-dir "$swarm_dir" --session "$session"
+  else
+    run_optional "assign" "assign.md" "$swarm_assign" --swarm-dir "$swarm_dir"
+  fi
+else
+  printf 'swarm state files not found: %s\n' "$swarm_dir" > "$out_dir/state-validate.txt"
+  printf '# swarm metrics\n\nstate files not found: `%s`\n' "$swarm_dir" > "$out_dir/metrics.md"
+  printf '# auto-tmux Swarm Board\n\nstate files not found: `%s`\n' "$swarm_dir" > "$out_dir/board.md"
+  printf '# auto-tmux Swarm Assignment Suggestions\n\nstate files not found: `%s`\n' "$swarm_dir" > "$out_dir/assign.md"
+  printf '[WARN] swarm state files not found; skipped state checks\n'
+fi
+
+printf 'swarm health written: %s\n' "$out_dir"

skills/auto-tmux/scripts/validate-auto-tmux.sh

@@ -84,6 +84,7 @@ scripts=(
   "$script_dir/swarm-archive.sh"
   "$script_dir/swarm-board.sh"
   "$script_dir/swarm-assign.sh"
+  "$script_dir/swarm-health.sh"
   "$script_dir/record-summary.sh"
   "$script_dir/safety-check.sh"
   "$script_dir/render-swarm-prompt.sh"
@@ -103,6 +104,7 @@ run_gate "swarm-watch help" "$script_dir/swarm-watch.sh" --help
 run_gate "swarm-archive help" "$script_dir/swarm-archive.sh" --help
 run_gate "swarm-board help" "$script_dir/swarm-board.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
 run_gate "safety-check help" "$script_dir/safety-check.sh" --help
 run_gate "safety-check clean text" "$script_dir/safety-check.sh" --text "make test"
@@ -120,6 +122,7 @@ require_contains "$skill_dir/SKILL.md" "scripts/swarm-watch.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-archive.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-board.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"
 require_contains "$skill_dir/SKILL.md" "scripts/safety-check.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-dispatch.sh"
@@ -133,6 +136,7 @@ require_contains "$script_dir/README.md" "swarm-watch.sh"
 require_contains "$script_dir/README.md" "swarm-archive.sh"
 require_contains "$script_dir/README.md" "swarm-board.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"
 require_contains "$script_dir/README.md" "safety-check.sh"
 require_contains "$script_dir/AGENTS.md" "validate-auto-tmux.sh"
@@ -141,6 +145,7 @@ require_contains "$script_dir/AGENTS.md" "swarm-watch.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-archive.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-board.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"
 require_contains "$script_dir/AGENTS.md" "safety-check.sh"