配置: 初始化 ISOS Agent Teams 软件研发模板

memory/agent-pane-cleanup.md

@@ -0,0 +1,60 @@
+---
+name: Agent Team pane 未关闭修复
+description: tmux agent pane 收到关闭要求后未被关闭的根因分析和修复方案
+type: feedback
+originSessionId: 786eafcb-68a7-48e9-838a-174584e5d9e8
+---
+# Agent Team tmux Pane 未关闭 — 根因分析与修复
+
+## 问题现象
+
+Agent Team 的 teammate（如 arch-writer-3）收到 `shutdown_request` 后，其 tmux pane 未被关闭，成为孤立 pane。
+
+## 根因分析（3 个）
+
+### 根因 1: 快照文件被覆盖（最关键）
+
+`agent-pane-track.sh` 的 `PreToolUse` 分支每次都会覆盖快照文件。当多个 Agent 同时 spawn 时：
+
+```
+Pre(Agent-A) → 写快照 S1 (3 panes)
+Pre(Agent-B) → 覆盖为 S2 (3 panes，但时间点不同)
+Post(Agent-A) → 用 S2 比较 → 可能遗漏 Agent-A 创建的 pane
+```
+
+**修复**: 仅在快照文件不存在时才创建（`if [ ! -f "${SNAPSHOT_FILE}" ]`），防止后续 Agent 调用覆盖初始快照。同时快照文件名加入 `team_name` 确保同一 team 共享。
+
+### 根因 2: 清理终止策略不够强
+
+Claude Code 是交互式 Node.js 进程，单次 Ctrl+C 触发确认提示而非退出：
+- `sleep 1` 太短（Claude 需要更长时间处理中断）
+- `exit` + Enter 在 Claude 仍在运行时被 Claude 拦截
+- `kill-pane` 有条件检查，可能跳过
+
+**修复**: 双次 Ctrl+C → 等 3 秒 → exit → 无条件 kill-pane → 验证关闭 → 失败重试。
+
+### 根因 3: 无持久化日志
+
+hook 脚本只写 stderr，Claude Code 不持久化 stderr。出问题后无任何痕迹可查。
+
+**修复**: 添加 `.claude/team-panes.log` 持久化日志，记录每次追踪和清理操作。
+
+## Why: 为什么这些根因会导致问题
+
+Agent Team 通常同时 spawn 多个 teammate（parallel Agent 调用），这触发了快照覆盖的竞态条件。被遗漏的 pane 不会被记录到 `team-panes.json`，因此 `TeamDelete` 清理时根本不知道这些 pane 的存在。
+
+## How to apply: 后续开发注意事项
+
+1. **tmux hook 脚本必须考虑并发**: 多个 Agent 可能同时触发 hook，共享资源（文件、状态）需要原子操作
+2. **kill-pane 应作为最终手段无条件执行**: 不要假设 graceful shutdown 一定成功
+3. **持久化日志是必须的**: hook 的 stderr 不会持久化，必须写日志文件
+4. **排查孤立 pane 时检查 `team-panes.log`**: 路径 `.claude/team-panes.log`
+
+## 关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `.claude/hooks/agent-pane-track.sh` | pane 追踪 hook（已修复快照覆盖） |
+| `.claude/hooks/team-pane-cleanup.sh` | pane 清理 hook（已增强终止策略） |
+| `.claude/team-panes.json` | 运行时状态文件 |
+| `.claude/team-panes.log` | 持久化日志（新增） |