用途：worktree 是 suna 单仓库的本地多实例开发环境工具，通过根目录脚本 pnpm worktree 调用（CLI 位于 scripts/worktree/cli.ts）。它让每个功能、修复、重构或实验在独立 git worktree 中进行，避免端口与依赖冲突，并自动创建专属分支。规则是：超过一行编辑、需要运行/迁移/测试的工作都默认使用 worktree，不要在主编出中直接做功能开发；只读调查、单文件错别字或注释修改、操作主 pnpm dev 栈本身可不建 worktree。
主要能力：create 会做工具链预检、分配最低空闲槽位、git worktree add、安装依赖、构建运行时产物，并（除非 --no-start）启动栈。每个槽位有独立端口：web 13000+N·100、api 13008+N·100、gateway 13090+N·100。默认共享主检出的 Supabase（kortix-local，54321/54322/54323/54324）；加 --db 则使用隔离项目 kortix-wt-<n>，含独立容器、卷、网络与迁移。其他命令：start 前台启动并阻塞；stop 停止进程树（--all 停止全部）；nuke 拆除并释放槽位；pr 推送分支并创建 PR；list、status、doctor 查看状态与校验工具链。
用法：代理非交互创建用 pnpm worktree create --name <feat> --yes --no-start，--no-start 必须加，否则会前台启动并阻塞。新检出位于 ../suna-<feat>，后续编辑与 git 操作针对该路径。完成后用 pnpm worktree nuke <feat>。start 会阻塞，代理不要内联调用，应后台运行或让用户自行执行。--stripe 需 stripe CLI 登录且本地 .env 有测试 STRIPE_SECRET_KEY。
限制：仅本地开发工具，不被应用、构建、CI 或 Docker 镜像导入，不触碰云/生产基础设施。--db 要求基础分支包含当前 packages/db/migrations；worktree 运行器存在调用旧 db:migrate 脚本的已知问题（见 issue 3630）。状态存于 ~/.kortix/worktrees/，可用 KORTIX_HOME 迁移。