settle-session

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Settle Session

收尾 Session

A settled session saves its work and everything another agent needs in the issue tracker or the project's files. Leave the calling session available and its occupied worktree leased, even when its branch has merged.

Do every step yourself. Leave all terminal workspaces, tabs and panes open. An explicit request to close named topology can authorize that separate cleanup; settlement never implies closing linked or grouped topology.

完成收尾的 session 会保存其工作成果，以及另一个 agent 在 issue tracker 或项目文件中需要的全部信息。即使其分支已经合并，也要保持调用方 session 可用，并保留其已占用 worktree 的 lease。

所有步骤都要自行完成。保持所有终端 workspace、tab 和 pane 打开。明确要求关闭指定 topology，可以授权单独执行该清理；session 收尾绝不意味着关闭关联或分组后的 topology。

Parameters

参数

```
<worktree-tool>
```
: the tool that makes and frees worktrees, e.g.
```
treehouse
```
, or plain git worktrees.
```
<session-host>
```
: where agent sessions run, e.g.
```
herdr
```
, Claude Code Desktop, Codex Desktop.

```
<worktree-tool>
```
：用于创建和释放 worktree 的工具，例如
```
treehouse
```
，或原生 git worktree。
```
<session-host>
```
：agent session 的运行位置，例如
```
herdr
```
、Claude Code Desktop、Codex Desktop。

Flow

流程

Run each commit, push and deletion as its own call, so a refused one stops only itself.

Take stock of what this session touched: the checkouts and worktrees it worked in and their branches, the pull requests and issues it opened, the processes and agents it started, and the threads still open. Add any branches and worktrees the calling skill or the user names. Through
```
<session-host>
```
, resolve the live caller and its current hierarchy before identifying cleanup targets; report any mismatch with the handoff or inherited context. Use actual pane and process locations, since workspace checkout metadata alone does not establish them.
Nothing running. Stop the task processes this session started, such as dev servers, watchers, background commands and preview or browser tabs, unless the user wants one kept; name each one kept in the report. Immediately before stopping or interrupting work, verify the live caller, target identity, actual location, hierarchy and task ownership; keep and report an uncertain target. Wait for or interrupt unfinished work by agents this session started, leaving their sessions and terminal topology open. Preserve unrelated agents, shells and services.
Nothing unsaid. Write down what this session learned that lives only in its context: decisions and their reasons, surprises, checks it skipped, what comes next. Put each where an agent that never saw this session will look for it: the issue it belongs to, the pull request's description, or a handoff written with
```
/handoff
```
.
Nothing undecided. Give each leftover thread an outcome: finish it, file it as a ticket, or raise it with the user and record what they decide. Ask while the user is here, and settle only once each question has its answer.
- When the user can't be reached, such as when a handoff says to decide alone: decide it yourself, and record the decision and its reason where step 3 puts what the session knows.
Nothing unsaved. In each checkout this session worked in, commit and push everything, including the files steps 3 and 4 wrote, until
```
git status
```
is clean and the branch matches its remote. Set aside on purpose anything that doesn't belong in a commit, and name it in the report.
- In each worktree considered for release: list the ignored and untracked files with
```
git status --ignored
```
  and copy out what's worth keeping, where
```
/orchestrating
```
  's
```
folder-standard.md
```
  puts each kind, since removing a worktree deletes them. Copy editor settings like
```
.vscode/
```
  to the main checkout, keeping the main checkout's own copy of any file already there.
- After an interrupted or rejected commit or push: check the log before retrying, because it may have landed anyway.
- When the changes sit on the default branch or in the user's main checkout: commit only this session's own changes, on a new branch, and open its pull request with
```
/to-pr
```
  . Leave the user's other changes where they are, and push nothing to the default branch.
- When the work's branch has already merged, and settling changes tracked files, such as status changes or files copied out of a worktree: put the changes on a small follow-up branch and open its pull request with
```
/to-pr
```
  . Leave the user's main checkout on its branch, since they may be working there, and pull in it only when it is clean and already on the default branch. Make the follow-up worktree with
```
<worktree-tool>
```
  from the remote default branch, and keep it until it qualifies for release below.
Nothing in the way. Free only clean, proven-merged, unoccupied worktrees and their branches, and name each one kept with its reason and occupants. Keep the calling session's worktree and its local and remote branch, the main checkout and the default branch. Run
```
git fetch --prune
```
first, so the remote default branch is current. Three proofs count:
- Reachable:
```
git merge-base --is-ancestor
```
  with the branch and the remote default branch succeeds, as after a merge commit or a fast-forward. It is the cheapest, so try it first.
- Matched by patch:
```
git cherry
```
  with the remote default branch and the branch prints no
```
+
```
  line, as after a rebase or an unchanged cherry-pick. A
```
+
```
  proves nothing either way.
- In the merged pull request's head: the hosting service shows the pull request merged, and the branch's tip is its head commit or an ancestor of it. A branch whose commit was integrated into the pull request's branch counts when the head contains that commit, or a commit carrying the same change as
```
git range-diff
```
  or the diff shows, and the branch holds nothing else; when unsure, keep the branch. A squash merge, or a commit changed while it was integrated, fails the first two proofs; only this one proves it.
Immediately before each release, refresh the live caller and target identities, repository, actual locations, hierarchy, branch tip and occupants through
```
<session-host>
```
and
```
<worktree-tool>
```
. Bind the merge proof to that tip; when it differs from the tip previously proven, prove the new tip or preserve the target. Check idle agents, shells and services as well as working agents; a tool's ability to terminate them does not make the worktree unoccupied. Preserve and report a target whose identity or occupancy is uncertain. For pooled worktrees, use the worktree tool's lease identity guards to prevent returning a reassigned lease.
- When
  <worktree-tool>
  is
  treehouse
  : use
```
/treehouse
```
  for its live occupancy checks, lease guards and release confirmation.
Free worktrees with
```
<worktree-tool>
```
, without
```
--force
```
. Confirm that the intended worktree was released successfully before deleting either its local or remote branch; a failed, interrupted or uncertain release preserves both. Inspect current state before any retry, and never schedule delayed destructive cleanup. Immediately before branch deletion, compare its current tip with the recorded proven tip and re-prove any change; preserve it when the proof or exclusive ownership is uncertain. Delete a local branch with
```
git branch -d
```
after the reachable proof, and with
```
git branch -D
```
when only the other two prove it. Use
```
git branch -D
```
too when
```
-d
```
refuses a branch the reachable proof passed, since
```
-d
```
checks against the branch's upstream or
```
HEAD
```
, not the remote default branch. For a branch with no worktree, verify that it is not checked out or in use before applying the same merge proofs.
- When a freed branch has a remote branch: delete it too once
```
git ls-remote --heads origin <branch>
```
  shows it still exists and its tip is the local branch's tip or passes one of the proofs above; the repository may have deleted it on merge. Otherwise keep the remote branch and name it in the report.
Report what was done, what was filed and where, what was kept and why, and what waits on the user. Include identity mismatches, preserved occupants and the caller's retained worktree and branch.
End the report with a resume prompt: one line the user pastes into a new session when they come back, so picking the work up needs no question to an agent. Name the worktree by its path, its branch, where the next session reads what remains (the handoff's path, or the issue or pull request that holds it), and the first thing to do; everything else stays there. Keep it to one line, because a pasted prompt of several lines arrives as pasted text and its skill never starts, and name skills in words rather than slash commands, so it works in every harness:
text
```
Continue in the worktree <path> on branch <branch>, from the handoff at <path>: <the first thing to do, in one sentence>.
```
- When nothing remains, such as when every branch merged and nothing carried over: leave the prompt out, and say so in the report.
Mark the session settled through
```
<session-host>
```
, where the host labels sessions, after refreshing the current caller's live identity and hierarchy. The report, its resume prompt and the settled mark finish settlement; keep this session, its worktree and all terminal topology open.

每次 commit、push 和删除操作都应单独调用，使某项操作被拒绝时只中止该操作本身。

盘点本 session 触及的所有内容：其中使用过的 checkout 和 worktree 及其分支、创建的 pull request 和 issue、启动的进程和 agent，以及仍未关闭的 thread。将调用方 skill 或用户点名的任何分支和 worktree 也纳入盘点。通过
```
<session-host>
```
解析当前存活的调用方及其当前 hierarchy，然后识别清理目标；如果与 handoff 或继承的 context 不一致，应予以报告。使用实际的 pane 和进程位置，因为仅有 workspace checkout metadata 不足以证明这些位置。
没有运行残留。 停止本 session 启动的任务进程，例如 dev server、watcher、后台命令，以及预览或浏览器 tab；但用户希望保留的除外，并在报告中逐一列出保留项。在停止或中断工作之前，立即核实当前存活的调用方、目标身份、实际位置、hierarchy 和任务归属；如果目标存在不确定性，则保留并报告。等待本 session 启动的 agent 完成尚未完成的工作，或中断这些工作，同时保持其 session 和终端 topology 打开。保留无关的 agent、shell 和 service。
没有未记录的信息。 记录本 session 获得且仅存在于其 context 中的信息：决策及其原因、意外发现、跳过的检查以及后续事项。将每项信息放在从未见过本 session 的 agent 会查找的位置：所属 issue、pull request 的 description，或使用
```
/handoff
```
撰写的 handoff 中。
没有未决事项。 为每个遗留 thread 给出结果：完成它、将其创建为 ticket，或向用户提出并记录用户的决定。趁用户当前在线时进行询问，只有每个问题都有答案后才完成收尾。
- 无法联系到用户时，例如 handoff 要求自行决定：自行作出决定，并按照步骤 3 规定的位置记录该决定及其原因。
没有未保存内容。 在本 session 工作过的每个 checkout 中，commit 并 push 所有内容，包括步骤 3 和 4 写入的文件，直到
```
git status
```
干净且分支与其 remote 一致。对于有意不纳入 commit 的内容，将其单独搁置，并在报告中说明。
- 对每个考虑释放的 worktree： 使用
```
git status --ignored
```
  列出 ignored 和 untracked 文件，并按照
```
/orchestrating
```
  的
```
folder-standard.md
```
  对各类文件的存放位置要求，将值得保留的内容复制出来，因为移除 worktree 会删除这些文件。将
```
.vscode/
```
  等编辑器设置复制到 main checkout；如果 main checkout 中已有相应文件，则保留其自身副本。
- commit 或 push 被中断或拒绝后： 重试前检查 log，因为该操作实际上可能已经生效。
- 当变更位于 default branch 或用户的 main checkout 中时： 仅将本 session 自身的变更 commit 到新分支，并通过
```
/to-pr
```
  创建其 pull request。将用户的其他变更留在原处，并且不向 default branch push 任何内容。
- 当工作所在分支已经合并，而收尾过程改动了 tracked 文件时，例如 status 变更或从 worktree 复制出的文件：在一个小型 follow-up branch 上提交这些变更，并通过
```
/to-pr
```
  创建其 pull request。让用户的 main checkout 保持在其当前分支上，因为用户可能正在该处工作；仅当它干净且已经位于 default branch 时，才将变更 pull 到其中。使用
```
<worktree-tool>
```
  从 remote default branch 创建 follow-up worktree，并保留它，直到它满足下方的释放条件。
没有阻碍。 仅释放干净、经证明已合并且无人占用的 worktree 及其分支；对于每个保留的 worktree，都要说明原因和占用者。保留调用方 session 的 worktree 及其 local 和 remote 分支、main checkout 和 default branch。首先运行
```
git fetch --prune
```
，使 remote default branch 保持最新。以下三种证明均有效：
- Reachable（可达）： 对 branch 和 remote default branch 执行
```
git merge-base --is-ancestor
```
  成功，例如在 merge commit 或 fast-forward 之后。此证明成本最低，因此优先尝试。
- Matched by patch（Patch 匹配）： 针对 remote default branch 和 branch 执行
```
git cherry
```
  时没有输出带
```
+
```
  的行，例如在 rebase 或未改动的 cherry-pick 之后。出现
```
+
```
  既不能证明已合并，也不能证明未合并。
- 位于已合并 pull request 的 head 中： 托管服务显示该 pull request 已合并，并且该分支的 tip 等于其 head commit，或为其祖先。如果某个分支的 commit 已被集成到 pull request 的分支中，则在以下情况下可视为满足证明：head 包含该 commit，或 head 包含一个通过
```
git range-diff
```
  或 diff 可证明携带相同变更的 commit，并且该分支不含其他内容；如有不确定，保留该分支。若使用 squash merge，或该 commit 在集成期间发生变更，则前两种证明不成立；只有本证明可以确认合并。
每次释放之前，立即通过
```
<session-host>
```
和
```
<worktree-tool>
```
刷新当前存活调用方与目标的身份、repository、实际位置、hierarchy、分支 tip 和占用者。将合并证明与该 tip 绑定；如果它不同于此前已证明的 tip，则证明新 tip，否则保留目标。既要检查闲置 agent、shell 和 service，也要检查正在工作的 agent；工具能够终止它们，并不代表 worktree 无人占用。对于身份或占用情况不确定的目标，予以保留并报告。对于 pooled worktree，使用 worktree 工具的 lease identity guard，防止归还未被重新分配的 lease。
- 当
  <worktree-tool>
  为
  treehouse
  时：使用
```
/treehouse
```
  进行实时占用检查、lease guard 和释放确认。
使用
```
<worktree-tool>
```
释放 worktree，不使用
```
--force
```
。在删除 local 或 remote 分支中的任何一个之前，确认目标 worktree 已成功释放；释放失败、被中断或结果不确定时，两者都应保留。重试前检查当前状态，绝不安排延迟执行的破坏性清理。删除分支前，立即将其当前 tip 与记录的已证明 tip 进行比较，并重新证明任何变化；当证明不充分或独占所有权不确定时予以保留。在通过 Reachable 证明后，使用
```
git branch -d
```
删除 local 分支；仅由另外两种证明确认时，使用
```
git branch -D
```
。当 Reachable 证明已通过但
```
-d
```
拒绝删除分支时，也使用
```
git branch -D
```
，因为
```
-d
```
是根据该分支的 upstream 或
```
HEAD
```
检查，而不是根据 remote default branch。对于没有 worktree 的分支，在应用相同的合并证明之前，验证它未被 checkout 或使用。
- 当已释放的分支还有 remote 分支时： 只有当
```
git ls-remote --heads origin <branch>
```
  显示 remote 分支仍然存在，且其 tip 与 local 分支的 tip 相同，或通过上述某种证明时，才将其一并删除；repository 也可能在合并时已经删除了它。否则保留 remote 分支，并在报告中说明。
报告已完成的事项、已登记的内容及其位置、保留的内容及原因，以及等待用户处理的事项。包括身份不匹配、保留的占用者，以及调用方保留的 worktree 和分支。
在报告末尾附上 resume prompt： 当用户回来时，可将这一行粘贴到新 session 中，从而无需向 agent 提问即可继续工作。注明 worktree 的 path、branch、下一 session 读取剩余信息的位置（handoff 的 path，或承载该信息的 issue 或 pull request），以及第一项要执行的事情；其他所有内容都保留在那里。保持为一行，因为多行提示粘贴后会作为普通文本传入，导致相应 skill 无法启动；同时应以文字而非斜杠命令提及 skill，使其能在每种 harness 中工作：
text
```
Continue in the worktree <path> on branch <branch>, from the handoff at <path>: <the first thing to do, in one sentence>.
```
- 当没有剩余事项时，例如所有分支均已合并且没有遗留内容：不要添加该提示，并在报告中说明这一点。
通过
<session-host>
将 session 标记为 settled（host 在其中为 session 添加标签），操作前先刷新当前调用方的存活身份和 hierarchy。报告、resume prompt 和 settled 标记共同完成本次 session 收尾；保持本 session、其 worktree 及所有终端 topology 打开。