Finch Worktree 协调器

一个 Finch mini tool，用隔离的 Git worktree 与绑定 Space 的持久 Agent Session 协调并行开发任务。

解决什么问题

每条 lane 都有耐久、可检查的身份：

• 一个仓库与固定 base SHA；
• 一个独立 worktree 和命名分支；
• 一个绑定该 worktree 的 Finch Space；
• 一个归本工具所有并持续复用的 Agent Session；
• 明确的范围、文件所有权、测试、turn 状态与回收证据。

主协调 Agent 负责拆分、审查和合并。lane Agent 可以实现、验证、提交和汇报，但不得自行合并或清理 worktree。

何时创建 lane

主 Agent 自主判断何时值得隔离：独立、可并行且所有权边界清晰的实现任务应创建 worktree lane；会修改同一文件或路径语义重叠的任务必须串行，即使文本 glob 看起来不同。

prepare 与 recover 会在同一个 canonical repository 内保护显式 owned_paths。只有双方活跃 lane 都声明 claim，且 literal 或尾部 /** 范围存在明确重叠时才拒绝；retired lane 会忽略，不确定 glob 不作为冲突证据。单个 coordinator runtime 内会串行执行生命周期检查，确保 prepare 在创建 worktree 前发现重叠。ledger 不是跨进程分布式锁，因此调用方不能让不同 Finch runtime 同时竞争同一仓库。

Space 与 Session 的职责

Finch Space 把项目上下文、规则、记忆和 cwd 绑定到准确 worktree；owner-scoped Agent Session 是该 Space 内持续复用的实现对话。dispatch 首次创建 Session，后续 dispatch/send 复用它。删除 Space 与回收 Git worktree 是两个独立且顺序明确的动作。

已验证工作流

prepare
  → AppCall createSpace（绑定工具返回的准确 worktree 路径）
  → bind_space（写入实际返回的 Space ID）
  → dispatch（默认立即返回）
  → 后台事件通知期间继续使用主会话
  → overview / result / send 集中验收
  → 主 Agent 审查、验证并在 lane 外完成集成
  → retirement_check
  → 用户明确同意
  → retire（批准令牌）
  → AppCall removeSpace（准确的已绑定 Space ID）——最后一步：会连带删除 lane 对话记录

Finch 公开 mini tool API 暂不支持创建或删除 Space，因此工具会向调用它的主 Agent 返回结构化 AppCall 交接步骤，绝不会猜测 Space ID。

Agent Tools

worktree_coordinator_manage

• prepare：校验仓库和固定基线，创建 worktree 与 ledger；可选择加入 delivery graph 并声明已有依赖。
• recover：安全接管 prepare 中断后留下的干净孤儿 worktree。
• bind_space：记录 Finch 实际返回的 Space ID，并与真实 Space 列表校验。
• dispatch：创建或复用 lane Agent Session 并加入完整任务书，默认立即返回；相同 lane_id + request_id 重试会复用 Finch Session turn。可选 model_key + reasoning_effort 选择或切换 lane 模型（先对照已启用模型列表校验）。
• send：向同一个 Agent 加入纠偏或修复要求，默认立即返回，并遵循相同请求幂等语义。
• cancel：仅凭用户明确请求取消单个 turn（排队中的直接移出队列，运行中的发起协作式停止）。lane 会话、worktree 和分支不受影响，之后可重新 dispatch。

prepare/recover 接受 session_visibility：默认 background 将 lane 会话从 Space 会话列表隐藏、完成时静默、等待授权仍提醒；interactive 则正常显示。

worktree_coordinator_inspect

• list：返回 total/active/retired/by-status 紧凑统计和适合审查的 lane 摘要。
• overview：为主窗口生成待输入、失败、待验收、可清理、阻塞、运行中和未启动的优先队列。
• status：只读返回 Git、Space（含实时存在性）、Session、turn、等待、readiness 与 diagnostics，不签发退休令牌。
• graph_status：返回一个 delivery graph 的集成顺序及依赖门禁状态。
• base_sync_check：比较主 checkout 与 lane 动态 final base，不修改 Git。
• result：恢复超时 turn，不重复提交任务。
• open：在 Finch 窗口打开 lane Agent 会话——后台隐藏会话的唯一打开方式。
• retirement_check：只读检查回收条件，安全时签发十分钟有效令牌。

worktree_coordinator_retire

核验全部证据后移除准确的 worktree。永不使用 --force，也不会删除本地或远程分支。临时 Space 改为在 retire 之后用 AppCall removeSpace 作为最后一步单独移除——删 Space 会连带删除 lane 对话，建议先用 inspect action="open" 让用户看一眼；交付物存在 Git 和台账里。退休后未删 Space 的 lane 会由 list（retired_spaces_pending）和 overview/status 诊断标出。

安全规则

• 不使用 rm、rm -rf、glob 删除或强制 worktree 删除。
• 拒绝已有分支、已有路径和位于主 worktree 内的目标路径。
• 创建 worktree 或接管 recovery 前，拒绝明确的活跃 lane owned_paths 重叠。
• dirty、运行中、等待交互、身份不符或尚未合入/保全的 lane 不能回收。
• 回收必须经过两阶段、明确同意、短期令牌和二次核验。
• lane ledger 不存储任务正文；list/overview/status 不暴露缓存的 Agent output 或 approval token。
• 不自动删除 Space 或分支，不允许自合并；retire 只移除二次核验通过的 worktree，分支始终保留。

版本说明 · 0.11.1

• dispatch 在会话向未创建时也接受 session_visibility，可见性可以到派发时再按波次决定——例如并行批次用后台、需要完成系统通知的关键 lane 用 interactive。会话已创建后再改会报错并告知当前值；传相同值则是无害空操作。

版本说明 · 0.11.0

真实生产使用（issue7 交付图）驱动的问题加固：

• lane 任务书新增规则：后台会话无法弹出确认/提问卡片——需要用户决策的事项直接写进最终报告的 blockers 段落，不要尝试交互提问（运行时会注入令人困惑的拒绝错误）。
• 任务书同时禁止在 worktree 留存临时分析文件（暂存用仓库外的 /tmp）——未跟踪残留文件曾挡住依赖门禁的干净检查。
• dispatch/send 不再过度承诺被动通知：返回的 next_action 与 systemPrompt 明确说明 lane 完成不会唤醒主会话——下次运行时轮询 overview/result，或用 wait_seconds 短等。

版本说明 · 0.10.1

• 默认 lane 模型从静态表单改为设置菜单 + 实时模型选择器：工具箱卡片与详情页的设置菜单弹窗会列出当前启用的模型（ctx.models.list()）供下拉选择，不再需要手填 provider:model。选择持久化在小工具存储；旧 manifest 设置表单仍作兑底。

版本说明 · 0.10.0

• 小工具设置：default_model_key 与 default_reasoning_effort，在 prepare/dispatch 未指定 model_key 时应用于 lane 会话。优先级：显式指定 > 设置项默认 > Finch 默认模型链。配置了无效/未启用模型时仅警告并跳过，不阻断 dispatch；生效模型会持久化到 lane 便于观测。

版本说明 · 0.9.0

吸收自 coordinate-worktrees skill 协议：

• 放弃路径：未合入的 lane 不再永久滞留。manage action=abandon 记录经用户批准的显式放弃（原因 + 可选同仓库 superseded_by 替换 lane）；此后 retirement_check/retire 以分支保留为集成条件（不再要求并入 target），并校验分支仍存在以保持工作可恢复。
• 验收状态：inspect action=accept 记录协调者验收的 worktree HEAD；status 与 reconcile 对验收后的 HEAD 漂移给出标记（head_matches_acceptance）。
• 交付对账：inspect action=reconcile 输出逐 lane 对账表（integrated / abandoned-preserved / pending-disposition / in-flight / not-dispatched）与 delivery_complete 门——宣布交付完成前，每个完成态 lane 必须已集成或显式放弃。支持 graph_id 过滤。
• 协调者身份：台账记录当前协调的 Finch 会话（prepare 自动注册）；list/reconcile 展示——台账在 mini tool storage 里，任何会话都可接手。
• 指引更新：按风险下限选 reasoning_effort（常规 low/medium、较高 ≥high、关键 ≥xhigh），push/删分支/部署/合并仅在工具外凭显式授权执行。

版本说明 · 0.8.0

• 退休顺序变更（破坏性）：retire 不再要求 space_removed=true，Space 改为在 worktree 退休之后最后一步才删——lane 对话在删除前始终可回看。retirement_check 交接中明确提供 inspect action="open" 最后预览机会，并提示删 Space 会连带删对话。
• retire 返回 space_still_present 和最后一步 removeSpace 交接；list 新增 retired_spaces_pending，overview/status 会标出退休后未删 Space 的 lane。
• status 新增悬空 lane 会话诊断（Space 先于退休被删）：会话入口可能打开为空，交付物在 Git 和台账。
• retirement_check 返回 space_present。

版本说明 · 0.7.0

• 新增 manage action=cancel：显式取消单个 lane turn——排队中的直接移出 Session 队列，运行中的发起与 UI 按 Esc 等同的协作式停止。取消仅作用于单个 turn 且永不静默：lane 会话、worktree、分支不受影响，取消后到达的事件被忽略，lane 可随时重新 dispatch。
• lane 级模型选择：prepare/recover/dispatch 接受 model_key + reasoning_effort，先经 ctx.models.list() 校验并在不匹配时报告可用键；模型持久化在 lane 上，创建 Session 时生效，对已存在的 Session 通过 Finch 按消息切换能力在线生效。
• lane 会话默认 background 后台隐藏（prepare/recover 的 session_visibility 可改回 interactive）：从 Space 会话列表消失、完成时静默，等待授权/提问/表单时仍正常提醒。新增 inspect action=open 经 ctx.navigation.openSession 打开。
• bind_space 会用 ctx.spaces.list() 校验精确 Space ID 并给出近似候选提示，回填 Space 规范名称；status 返回 Space 实时存在性（present: false 可发现 Space 被误删）。
• manifest 声明 minVersion: 1.6.4，移除从未被代码使用的 sessionContainers 贡献；开发依赖升级到 @finchtoys/minitool-api ^0.3.13。

版本说明 · 0.6.0

• dispatch 与 send 默认立即返回，隔离 lane Session 在各自 Space 中运行时，主会话仍可继续追问；传入正数 wait_seconds 仍可短暂同步等待。
• 持久 Session 事件会更新 lane 状态，并对完成、失败、等待和恢复发出本地化 Toast；重复终态事件不会重复通知。
• 新增只读 overview，为主窗口生成统一验收队列并识别 review/cleanup 候选，不暴露 Agent output 或 approval token。
• 自动监听不会自动合并或清理；Space 移除与 worktree 退休仍需显式两阶段检查和用户批准。

版本说明 · 0.5.0

• 相关 lane 可组成 delivery graph，记录同仓库依赖边、确定性的集成顺序提示和统一动态 final base。
• 初次 dispatch 会等待所有依赖完成，并验证其 clean、精确映射且已集成；经安全保全后退休的依赖也视为满足。
• 新增只读 graph_status 与 base_sync_check，展示依赖门禁并分类 final-base 同步状态，不执行 fetch、switch、merge 或其他 Git 修改。
• ledger schema v3 将 v1/v2 安装迁移为空依赖和 finalBaseRef=targetRef，同时对异常 graph 元数据 fail-closed。

版本说明 · 0.4.0

• 每个 lane 记录 placementOwner=coordinator-manual 和明确的 retirement policy，安全默认值为 report-only。
• retire-clean-manual-after-merge 可建议既有手工清理流程，但不会绕过用户批准、Space 移除、二次核验或分支保留。
• ledger schema v2 原地迁移现有 v1 lane，并对未知 ownership/policy 值 fail-closed。

版本说明 · 0.3.1

• 后续消息默认追加：不得静默取消、暂停或重定向活跃 lane；所有权重叠的工作保持单一负责人，独立工作使用新 lane 或排队。
• status 与 retirement_check 返回唯一清理分类，并明确精确 worktree、保留分支及下一项安全动作。
• 清理分类采用 fail-closed 优先级，区分活跃、dirty、未集成、身份不符和可清理 lane。

版本说明 · 0.3.0

• lane 首次 dispatch brief 跟随 Finch 当前语言，同时完整保留用户原始任务文本。
• send 改用精简 steering brief，不再重复首次派发的完整 lane 契约。
• 新增中英文 brief 模板、默认值及 locale-aware 测试。
• 此次向后兼容的能力版本继续使用 CURRENT_LEDGER_VERSION=1，无需迁移 ledger。

版本说明 · 0.2.0

• dispatch/send 请求幂等：Finch duplicate receipt 只对应一个 ledger turn，终态不会退化，timeout 重试可继续恢复同一 turn。
• 显式 ledger 规范化，保持 CURRENT_LEDGER_VERSION=1：保留现有 v1 安装，补齐可默认字段，下一次 mutate 写回规范化数据，并拒绝未知未来版本或损坏 schema。
• 安全可观测性：list 增加聚合统计及 ownership/retirement 元数据；status 增加只读 readiness/diagnostics，不暴露任务正文、Agent output 或 approval token。
• 包含 0.2.0 加固周期加入的 active owned-path 防护和验证过的两阶段退休流程。

从 0.1.0 升级无需手工迁移 ledger。

开发与安装

要求 Node.js 20+ 与 Git。

npm install
npm run check
npx @finchtoys/minitools add .

安装后在 Finch Toolcase 启用 Worktree 协调器，并授权文件系统、Shell 与 owner-scoped Sessions 权限。

License

MIT