From e60785b6ef5fbfc714782cc6548a6f1e9bb93319 Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 03:34:14 +0800
Subject: [PATCH] feat: skills - safely cleanup auto-tmux sessions

---
 skills/auto-tmux/SKILL.md                     |  1 +
 skills/auto-tmux/references/automation.md     |  2 +
 skills/auto-tmux/scripts/README.md            |  1 +
 .../auto-tmux/scripts/auto-tmux-smoke-test.sh |  1 +
 skills/auto-tmux/scripts/auto-tmux.sh         | 38 +++++++++++++++++++
 5 files changed, 43 insertions(+)

diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index 416196f..261a882 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -125,6 +125,7 @@ skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --re
 ```bash
 skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex"
 skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+skills/auto-tmux/scripts/auto-tmux.sh cleanup --session ai-hub --dry-run
 ```
 
 **启用 oh-my-tmux 配置（仓库内版本）**
diff --git a/skills/auto-tmux/references/automation.md b/skills/auto-tmux/references/automation.md
index 4c97ab7..b90c77f 100644
--- a/skills/auto-tmux/references/automation.md
+++ b/skills/auto-tmux/references/automation.md
@@ -27,6 +27,7 @@
 | `record` | 开启/停止 pane 输出审计日志 | 文件写入到显式目录 |
 | `snapshot` | 导出拓扑和 pane 输出证据包 | 默认脱敏，写入显式目录 |
 | `hub` | 初始化 AI 多终端工作台 | 已存在 session 不覆盖 |
+| `cleanup` | 清理指定 tmux session | 真实 kill 必须显式 `--force` |
 | `wait` | 等待 pane 输出出现某个 pattern | 超时失败 |
 | `swarm-brief.sh` | 生成只读交接报告 | 不发送按键，只汇总证据 |
 | `swarm-watch.sh` | 有限轮次巡检 pane 输出和状态 | 不默认无限循环 |
@@ -51,6 +52,7 @@ skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "co
 
 ```bash
 skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+skills/auto-tmux/scripts/auto-tmux.sh cleanup --session ai-hub --dry-run
 ```
 
 ### 2. 巡检全部 worker
diff --git a/skills/auto-tmux/scripts/README.md b/skills/auto-tmux/scripts/README.md
index ef5df03..148c89d 100644
--- a/skills/auto-tmux/scripts/README.md
+++ b/skills/auto-tmux/scripts/README.md
@@ -21,6 +21,7 @@ skills/auto-tmux/scripts/auto-tmux.sh help
 
 # 查看 tmux 拓扑
 skills/auto-tmux/scripts/auto-tmux.sh topology
+skills/auto-tmux/scripts/auto-tmux.sh cleanup --session ai-hub --dry-run
 
 # 诊断环境
 skills/auto-tmux/scripts/auto-tmux.sh doctor --session ai-hub
diff --git a/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh b/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
index 6ecaf08..34ddf46 100755
--- a/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
+++ b/skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
@@ -40,6 +40,7 @@ bash -n "$SWARM_DISPATCH"
 "$AUTO_TMUX" hub --session "$SESSION" --workers 1 --cmd bash
 "$AUTO_TMUX" doctor --session "$SESSION" >/tmp/auto-tmux-smoke-doctor.txt
 "$AUTO_TMUX" topology --session "$SESSION" >/tmp/auto-tmux-smoke-topology.txt
+"$AUTO_TMUX" cleanup --session "$SESSION" --dry-run >/tmp/auto-tmux-smoke-cleanup-dry-run.txt
 
 commander_target="$(tmux list-panes -t "$SESSION:commander" -F '#S:#I.#P' | head -n 1)"
 worker_target="$(tmux list-panes -t "$SESSION:worker1" -F '#S:#I.#P' | head -n 1)"
diff --git a/skills/auto-tmux/scripts/auto-tmux.sh b/skills/auto-tmux/scripts/auto-tmux.sh
index 118f17b..6216904 100755
--- a/skills/auto-tmux/scripts/auto-tmux.sh
+++ b/skills/auto-tmux/scripts/auto-tmux.sh
@@ -26,6 +26,7 @@ Usage:
   auto-tmux.sh record stop -t TARGET
   auto-tmux.sh snapshot [--session NAME] [--dir DIR] [-n LINES]
   auto-tmux.sh hub [--session NAME] [--workers N] [--cmd CMD] [--commander-cmd CMD] [--attach]
+  auto-tmux.sh cleanup --session NAME [--dry-run] [--force]
   auto-tmux.sh wait -t TARGET --pattern REGEX [--timeout SEC] [--interval SEC] [-n LINES]
 
 Target format:
@@ -43,6 +44,7 @@ Examples:
   auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback"
   auto-tmux.sh snapshot --session ai-hub --dir /tmp/auto-tmux-snapshot
   auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex"
+  auto-tmux.sh cleanup --session ai-hub --dry-run
 EOF
 }
 
@@ -621,6 +623,41 @@ cmd_hub() {
   fi
 }
 
+cmd_cleanup() {
+  local session=""
+  local dry_run="0"
+  local force="0"
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --session) session="${2:-}"; shift 2 ;;
+      --dry-run) dry_run="1"; shift ;;
+      --force) force="1"; shift ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown cleanup option: $1" ;;
+    esac
+  done
+
+  command -v tmux >/dev/null 2>&1 || die "tmux is not installed or not in PATH"
+  [[ -n "$session" ]] || die "cleanup requires --session NAME"
+  tmux has-session -t "$session" 2>/dev/null || die "session not found: $session"
+
+  local attached windows
+  attached="$(tmux display-message -pt "$session" '#{session_attached}' 2>/dev/null || printf '0')"
+  windows="$(tmux display-message -pt "$session" '#{session_windows}' 2>/dev/null || printf '?')"
+  printf 'cleanup target: session=%s windows=%s attached=%s\n' "$session" "$windows" "$attached"
+
+  if [[ "$dry_run" == "1" ]]; then
+    printf '[dry-run] would kill session: %s\n' "$session"
+    return 0
+  fi
+  [[ "$force" == "1" ]] || die "cleanup requires --force without --dry-run"
+  if [[ "$attached" != "0" ]]; then
+    warn "session is attached; killing anyway because --force was provided"
+  fi
+  tmux kill-session -t "$session"
+  printf 'session killed: %s\n' "$session"
+}
+
 cmd_wait() {
   local target=""
   local pattern=""
@@ -678,6 +715,7 @@ main() {
     record) cmd_record "$@" ;;
     snapshot) cmd_snapshot "$@" ;;
     hub) cmd_hub "$@" ;;
+    cleanup) cmd_cleanup "$@" ;;
     wait) cmd_wait "$@" ;;
     *) die "unknown command: $cmd" ;;
   esac