team/memory/agent-pane-cleanup.md

name, description, type, originSessionId

name	description	type	originSessionId
Agent Team pane 未关闭修复	tmux agent pane 收到关闭要求后未被关闭的根因分析和修复方案	feedback	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	持久化日志（新增）