tmux Worktree Session 用于一次性搭起一个自包含的工作区：隔离的 git worktree、驱动它的 tmux 会话、正在运行的开发栈，以及一个已经拿到简报并开始工作的智能体。人 attach 上去时，工作已经动起来了。
它组合了两个技能：tmux-orchestration（安全地驱动 pane）和 handoff（撰写简报）。
标准布局
会话名：<Project>-<work>（用连字符，不含空格） ├── 窗口 1 "agent" → 编码智能体（Claude/Codex），cwd = worktree，给定一个指向简报的启动提示 ├── 窗口 2 "cli" → 裸 shell，用于测试和临时命令 └── 窗口 3 "dev" → 开发栈
三个窗口，每个只做一件事，不做分屏。这是常见形态；可据情况调整（比如不要开发栈、两个智能体、加一个日志窗口）。非显而易见时先确认。除非用户要求，否则不要加 git/lazygit 窗口。
输入
从上下文中获取，不要去盘问：
- 工作名 → 分支名 + 会话名。如果有 PR/issue 编号优先用它。
- 智能体 + 模式 → Claude 或 Codex，fast/plan。不确定时问一次。
- 基础分支 → 通常是默认分支；worktree 工具常基于 origin/<default>，这对第 1 步很关键。
流程
- 先写简报并提交到基础分支
用 handoff 写智能体要读的内容：任务目标、限定的任务范围、文件/模式、约定、护栏。是简报，不是历史记录。
如果 worktree 工具把新工作树基于 origin/<default>，那么在创建工作树之前，先把简报提交并推送到基础分支，否则智能体看不到它。
- 发现并运行 worktree 工具
先查看（见速查表），不要臆断。常见形式：bin/worktree create <name>、bin/worktree create --pr 42。兜底方案：git worktree add ../<repo>-<branch> -b <branch> origin/<default>。
创建工作树常常会触发完整的引导流程（依赖、数据库、密钥），可能要花几分钟——不要以为它卡住了。它可能会提示输入密钥（1Password、主密钥、环境令牌）：这需要用户批准——把提示暴露出来并等待，绝不要自己输入凭据。在可见的 pane 中运行，并等待真正的完成信号（追加 ; echo DONE_$? 再轮询）后，再启动开发栈。
- 发现开发栈和测试命令
先查看（见速查表）。优先用无头/分离模式（例如 process-compose -D 加 status/logs），便于自己控制；前台 TUI 也适合让人类观看。记下测试运行器——cli 窗口和智能体都需要它。
- 构建会话
机制部分由 tmux-orchestration 负责。容易踩坑的细节：
- 分离式创建，以免影响用户当前会话。
- 会话名用连字符，不含空格。
- 窗口 1 agent：cd 到 worktree，启动智能体；当其界面就绪后，用 buffer-paste 粘贴启动提示，然后单独一步发送 Enter。保持简短——指向简报即可。可选地把同级 pane id（cli、dev）交给它，让它能自己通过 tmux CLI 轮询。
- 窗口 2 cli：cd 到 worktree，裸 shell，用于测试和临时命令。
- 窗口 3 dev：cd 到 worktree，运行开发栈。
每个窗口都要 cd 到 worktree，并使用正确的工具链（见版本管理器陷阱）。
- 验证并汇报
- 开发栈确实健康（轮询状态/健康检查），而不是仅仅“已启动”；若失败读取进程日志。
- 智能体确实已启动（抓取其 pane 内容，不要假设粘贴已生效）。
- 汇报：tmux attach -t <session>。
陷阱
版本管理器在派生出的 shell 中不会自动激活（最大的一个坑）。你以程序方式派生的 shell（tmux new-session，非登录 shell）往往缺少用户的版本管理器（mise/asdf/rbenv/nvm），于是 ruby/node/python 会悄悄回退到系统版本，引导失败（例如“Could not find bundler”）。
- 检测：对比你所在 pane 与用户 pane 中 ruby -v 等的输出。不一致就是征兆。
- 修复交互式 pane：把 shims 加到 PATH，例如 mise export PATH="$HOME/.local/share/mise/shims:$PATH"。
- 同样修复开发栈的子进程：每个需要 mise 管理工具的命令都运行 eval "$(mise activate bash)" && …（或 mise exec --）。
pane 机制与安全 → tmux-orchestration。按 pane id 定位、绝不写入自己的 pane、先读后写、用 buffer-paste 处理多行提示、Enter 作为单独一步——这些都在那里。不要复述，遵循即可。这里值得重复两点：会话名不含空格（session:window 目标会解析错误），以及用真实按键退出开发 TUI（process-compose 是 F10），而不是猜的 Ctrl-C。
发现速查表
需要 → 查找
- Worktree 工具：bin/worktree、script/worktree、DEVSTACK.md、just/make，否则 git worktree add
- 开发栈：bin/dev、npm/pnpm dev、foreman/overmind、process-compose、docker compose、mise run dev、项目动词
- 测试运行器：bin/rspec、pnpm test、pytest、go test、Makefile
- 工具链：.mise.toml/.tool-versions/.ruby-version/.nvmrc——确认派生的 shell 使用了它