settle-session

结算会话

结算后的会话会在问题跟踪器或项目文件中保存其工作，以及其他 Agent 所需的一切。让调用方会话保持可用，并继续租用其占用的工作树，即使其分支已经合并。

所有步骤都由你亲自完成。保持所有终端工作区、标签页和窗格打开。明确要求关闭指定拓扑结构，才可单独执行清理；结算并不意味着关闭已链接或分组的拓扑结构。

参数

• <worktree-tool>：创建和释放工作树的工具，例如 treehouse 或普通的 git worktree。
• <session-host>：运行 Agent 会话的位置，例如 herdr、Claude Code Desktop、Codex Desktop。

步骤

将每次提交、推送和删除分别作为独立调用执行，这样某项操作被拒绝时，只会停止该操作。

1. 盘点本次会话涉及的内容：它操作过的检出目录和工作树及其分支、创建的拉取请求和议题、启动的进程和 Agent，以及仍未关闭的讨论串。加入调用技能或用户提及的任何分支和工作树。通过 <session-host>，先解析当前调用方及其当前层级，再确定清理目标；报告任何与交接内容或继承上下文不一致之处。使用实际的窗格和进程位置，因为仅凭工作区检出元数据无法确定它们的位置。

2. 不留运行中的任务。 停止本次会话启动的任务进程，例如开发服务器、监听程序、后台命令以及预览或浏览器标签页，除非用户希望保留某项；在报告中逐一列出保留的项目。在停止或中断工作前，立即核实当前调用方、目标身份、实际位置、层级和任务归属；目标情况不明确时应保留并报告。等待或中断本次会话启动的 Agent 尚未完成的工作，但保留其会话和终端拓扑。不要动无关的 Agent、Shell 和服务。

3. 不遗漏信息。 记录本次会话只存在于其上下文中的所得信息：决定及其原因、意外情况、跳过的检查，以及后续步骤。将每项信息写在未参与本次会话的 Agent 会查找的地方：相关议题、拉取请求描述，或通过 /handoff 编写的交接内容。

4. 不留下未决事项。 为每个遗留讨论串给出结果：完成它、将它登记为任务单，或向用户提出并记录用户的决定。趁用户还在时询问，并且只有在每个问题都有答案后才作出最终处理。

   • **联系不上用户时，**例如交接内容要求自行决定时：自行决定，并按照步骤 3 的要求，在记录会话所知信息的位置记录决定及其原因。
   • **如果会话有 session-status 工具：**调用它的 list 操作，并传入 filter: { kind: ["decision"], state: "open" }，然后在此处提出每项开放的 before_settling 和 blocked 决策。只能通过该工具读取决策，因为该 mod 管理其存储文件，且可能更改其格式。

5. 不留下未保存的内容。 对本次会话操作过的每个检出目录，提交并推送所有内容，包括步骤 3 和 4 写入的文件，直到 git status 干净且分支与其远程分支一致。明确将有意不纳入提交的内容另行保存，并在报告中注明。

   • **对每个考虑用于发布的工作树：**使用 git status --ignored 列出被忽略和未跟踪的文件，并按照 /orchestrating 中 folder-standard.md 的规定，将值得保留的内容复制到相应位置，因为移除工作树会删除这些内容。将 .vscode/ 等编辑器设置复制到主检出目录；如目标文件已存在，则保留主检出目录中的版本。
   • **提交或推送被中断或拒绝后：**重试前先检查日志，因为操作可能已经成功。
   • **更改位于默认分支或用户的主检出目录时：**只提交本次会话自己的更改，并在新分支上进行；使用 /to-pr 创建拉取请求。保留用户的其他更改，不要向默认分支推送任何内容。
   • **工作分支已合并，且收尾工作会更改受跟踪的文件（例如状态变更或从工作树复制出的文件）时：**将更改放入一个小型后续分支，并使用 /to-pr 创建拉取请求。让用户的主检出目录留在其当前分支，因为用户可能正在那里工作；只有在该目录干净且已处于默认分支时，才在其中拉取。使用 <worktree-tool> 从远程默认分支创建后续工作树，并保留它，直到满足下面的发布条件。

6. 不妨碍他人。 只释放干净、已证实合并且无人占用的工作树及其分支，并逐一说明保留项、保留原因和占用者。保留调用会话的工作树及其本地和远程分支、主检出目录和默认分支。先运行 git fetch --prune，以更新远程默认分支。以下三种证明方式均可：

   • **可达：**使用分支和远程默认分支运行 git merge-base --is-ancestor，命令成功即证明已合并，例如通过合并提交或快进合并。此方式成本最低，应优先尝试。
   • **补丁匹配：**使用远程默认分支和该分支运行 git cherry，结果不含 + 行即证明已合并，例如通过变基或未更改的拣选提交。出现 + 并不能证明任何结论。
   • **拉取请求头已合并：**托管服务显示拉取请求已合并，且该分支的最新提交是其头提交，或是该头提交的祖先。若分支中的提交已集成到拉取请求分支，则只要头提交包含该提交，或包含经 git range-diff 或差异比对确认携带相同更改的提交，且该分支没有其他内容，就算已合并；不确定时应保留分支。Squash 合并，或集成时被修改的提交，不满足前两种证明；只有此方式可以证明已合并。 每次发布前，立即通过 <session-host> 和 <worktree-tool>：
   • **刷新：**实时调用者和目标身份、仓库、实际位置、层级、分支最新提交和占用者。
   • **绑定最新提交：**将合并证明绑定到该最新提交；如果它与此前已证明的最新提交不同，就证明新的最新提交或保留目标。
   • **占用者：**检查空闲 Agent、shell 和服务，以及正在工作的 Agent；工具能够终止它们，并不意味着工作树未被占用。
   • **目标不确定：**保留身份或占用情况不确定的目标，并报告。
   • **池化工作树：**使用 <worktree-tool> 的租约身份保护机制，确保重新分配的租约绝不会被归还。
   • **当 <worktree-tool> 是 treehouse 时：**使用 /treehouse 检查实时占用情况、租约保护机制并确认释放。

   使用 <worktree-tool> 释放工作树，不要使用 --force：

   • **释放检查：**在删除本地或远程分支之前，确认预期工作树已成功释放；释放失败、中断或状态不确定时，保留两者。任何重试前都要检查当前状态，绝不安排延迟的破坏性清理。
   • **最新提交检查：**在删除分支前立即将分支当前最新提交与记录的已证明最新提交进行比较；如有变化，重新证明；如果证明或独占所有权不确定，则保留分支。
   • **删除本地分支：**通过可达性证明后，使用 git branch -d；只有另外两项证明能证明时，使用 git branch -D。如果 -d 拒绝删除一个已通过可达性证明的分支，也使用 git branch -D，因为 -d 是根据分支的上游或 HEAD 检查，而不是远程默认分支。
   • **不带工作树的分支：**在应用相同的合并证明之前，确认该分支未被检出或使用。
   • **已释放分支有远程分支时：**一旦 git ls-remote --heads origin <branch> 显示远程分支仍存在，且其最新提交与本地分支的最新提交相同或通过上述某项证明，也删除远程分支；仓库可能已在合并时将其删除。否则保留远程分支并在报告中注明。删除前，在托管服务上将每个以该分支为目标分支的未关闭拉取请求改为默认分支，因为删除目标分支会关闭基于它堆叠的拉取请求，而已关闭的拉取请求无法改为针对其他目标分支重新打开。改目标分支失败时，保留远程分支并在报告中注明。

7. 报告已完成的操作、已提交的内容及提交位置、保留的内容及原因，以及哪些事项仍需用户处理。包括身份不匹配、保留的占用者，以及调用者保留的工作树和分支。

   • **如果会话有 session-status 工具：**将步骤 4 后仍未解决的决定（例如 after_settling 中的决定）作为一个编号列表放入报告，每项包含其 id、问题、默认选项和可选项。然后调用该工具的 post_decide_list 操作。

8. **在报告末尾提供恢复提示：**用一行文字说明用户回来时应粘贴到新会话中的内容，确保无需向 Agent 提问即可继续工作。写明工作树路径、分支、下一会话应从何处读取剩余事项（即交接文件的路径，或包含相关内容的问题或拉取请求），以及要做的第一件事；其他内容都留在那里。必须保持为一行，因为多行粘贴提示会作为粘贴文本送达，且其中的技能不会启动；技能名称要用文字写出，不要写成斜杠命令，这样才能在所有 harness 中生效：

   Continue in the worktree <path> on branch <branch>, from the handoff at <path>: <the first thing to do, in one sentence>.
   

   • **没有剩余事项时，**例如所有分支均已合并且没有遗留内容：省略提示，并在报告中说明。

9. 通过 <session-host> 标记会话已结清，该主机负责标记会话；操作前刷新当前调用者的实时身份和层级。报告、恢复提示和结清标记即完成结清；保持本会话、其工作树和所有终端拓扑处于打开状态。