@maxiaochao/pi-toolkit 0.10.11 → 0.10.13

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-10-09 - v0.10.13
+
+- bundle worktree v0.3.1: show a persistent in-conversation confirmation after switching worktrees
+
+## 2026-10-09 - v0.10.12
+
+- bundle worktree v0.3.0: automatically move Agent conversations into prepared worktrees without external Harness support
+
 ## 2026-10-09 - v0.10.11
 
 - bundle herdr-subagents v0.4.4: return failed foreground batches early while surviving subagents continue in background

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.11",
+  "version": "0.10.13",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/worktree/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-10-09 - v0.3.1
+
+- show a persistent in-conversation confirmation after switching worktrees
+
+## 2026-10-09 - v0.3.0
+
+- automatically move Agent conversations into prepared worktrees without external Harness support
+- 修复 `enter_worktree` 只创建目录却不切换的问题；现在 Extension 会在 `agent_settled` 后自动 fork 并切换当前会话，不再依赖外部 Harness 消费协议。
+- 移除 v0.2.0 的 `pi-worktree/switch-request` 常量及 `kind/version/action/sessionFile` 输出字段；自定义 Harness 若曾消费该协议，需要改用 Extension 内置自动切换。
+
 ## 2026-10-09 - v0.2.0
 
 - add current-session worktree switching for users, Agents, and SDK Harnesses

package/packages/worktree/README.md

@@ -1,6 +1,6 @@
 # @maxiaochao/pi-worktree
 
-`pi-worktree` CLI、Pi Extension 与配套 skill。它既能启动独立 Pi，也能让用户在当前界面切换 worktree，或让 Agent 向 SDK Harness 发出结构化切换请求。
+`pi-worktree` CLI、Pi Extension 与配套 skill。它既能启动独立 Pi，也能让用户或 Agent 在当前 Pi 界面中切换 worktree，并保留完整对话。
 
 ![Worktree 在真实临时 Git 仓库中的运行截图](docs/screenshot.png)
 
@@ -14,7 +14,7 @@
 
 ```bash
 pi-worktree start feature -p "implement the feature"
-pi-worktree prepare feature --json
+pi-worktree prepare --json feature
 pi-worktree info feature
 pi-worktree out
 pi-worktree remove feature
@@ -31,7 +31,7 @@ pi-worktree remove feature
 
 命令会把当前持久会话 fork 到目标 worktree，再通过 Pi 的公开 session replacement API 切换。临时的 `--no-session` 会话无法使用此入口。
 
-Agent 使用 Extension 注册的 `enter_worktree` tool。它创建或复用目标后返回 `pi-worktree/switch-request` 结构化结果，并终止当前工具轮；兼容 Harness 应在 `agent_settled` 后读取 `sessionFile` 和 `path`，执行 `SessionManager.forkFrom(sessionFile, path)`，再把返回的新 session 文件交给 `runtime.switchSession()`，最后重新绑定 `runtime.session`。这样目标 cwd 会写入新 session header，重启后仍然有效。普通 Pi 没有宿主切换钩子时，Tool 只会生成请求；用户仍可使用 `/worktree start` 完成切换。
+Agent 使用 Extension 注册的 `enter_worktree` tool。它创建或复用目标、终止当前工具轮，并在 `agent_settled` 后自动触发内部 `/worktree` 命令。Extension 随后执行 `SessionManager.forkFrom()` 和 `switchSession()`；目标 cwd 会写入新 session header，当前界面继续显示完整对话，重启后也仍然有效。整个流程由 Extension 完成，不需要外部 Harness 适配。
 
 ## 安装
 

package/packages/worktree/TESTING.md

@@ -2,7 +2,7 @@
 
 ## 流程
 
-1. `npm --prefix packages/worktree test`：在临时 Git 仓库中运行 CLI，并验证 Extension 注册和 session 切换协议。
+1. `npm --prefix packages/worktree test`：在临时 Git 仓库中运行 CLI，并验证 Extension 注册、延迟命令桥接和 session 切换生命周期。
 2. `npm pack ./packages/worktree --dry-run`：确认 CLI、completion、skill 和安装脚本进入 tarball。
 3. 手工验收发布包的 `pi-worktree start` 交互流程。
 4. 确认 README 示例、真实临时 Git 仓库输出 `docs/screenshot.png` 和 `docs/demo.gif` 进入 tarball。
@@ -13,7 +13,9 @@
 - `start` 从当前分支创建 `.worktrees/<name>` 并记录 base。
 - `prepare --json` 覆盖 created、reused、already-active、dirty 和非法名称安全失败。
 - `/worktree start` 把历史 fork 到 cwd 正确的新 session，再调用 `switchSession`。
-- `enter_worktree` 返回带 `pi-worktree/switch-request`、源 session、目标路径和 dirty 状态的 structured content，并请求终止当前工具轮。
+- `enter_worktree` 串行准备目标，在 `agent_settled` 后触发内部命令，并 fork 当前 session 后调用 `switchSession`。
+- Agent 轮被中止时不触发切换；用户取消 session replacement 时删除派生 session。
+- 自定义 session 目录在 fork 后保持不变。
 - 假 Pi 收到正确工作目录和参数。
 - `list` 标记主 checkout 和子 worktree。
 - `info` 报告 clean、branch、base 和 ahead。

package/packages/worktree/extensions/worktree.ts

@@ -5,8 +5,7 @@ import { SessionManager, type ExtensionAPI } from "@earendil-works/pi-coding-age
 import { Type } from "typebox";
 
 const CLI_PATH = fileURLToPath(new URL("../bin/pi-worktree", import.meta.url));
-
-export const WORKTREE_SWITCH_REQUEST = "pi-worktree/switch-request";
+const PENDING_SWITCH_ARGUMENT = "__enter_worktree_pending__";
 
 export interface WorktreePrepareResult {
   status: "created" | "attached" | "reused" | "already-active";
@@ -15,18 +14,12 @@ export interface WorktreePrepareResult {
   dirty: boolean;
 }
 
-export interface WorktreeSwitchRequest extends WorktreePrepareResult {
-  kind: typeof WORKTREE_SWITCH_REQUEST;
-  version: 1;
-  action: "fork-and-switch";
-  sessionFile: string;
+export interface EnterWorktreeResult extends WorktreePrepareResult {
+  switch: "scheduled" | "already-active";
 }
 
-const SwitchRequestSchema = Type.Object({
-  kind: Type.Literal(WORKTREE_SWITCH_REQUEST),
-  version: Type.Literal(1),
-  action: Type.Literal("fork-and-switch"),
-  sessionFile: Type.String(),
+const EnterWorktreeResultSchema = Type.Object({
+  switch: Type.Union([Type.Literal("scheduled"), Type.Literal("already-active")]),
   status: Type.Union([
     Type.Literal("created"),
     Type.Literal("attached"),
@@ -76,53 +69,117 @@ async function prepareWorktree(
   cwd: string,
   name: string,
   base?: string,
+  signal?: AbortSignal,
 ): Promise<WorktreePrepareResult> {
   const args = ["prepare", "--json"];
   if (base) args.push("--base", base);
   args.push(name);
-  const result = await pi.exec(CLI_PATH, args, { cwd });
+  const result = await pi.exec(CLI_PATH, args, { cwd, signal });
   if (result.code !== 0) {
     throw new Error(result.stderr.trim() || result.stdout.trim() || `pi-worktree prepare 失败（退出码 ${result.code}）`);
   }
+  if (signal?.aborted) throw new Error("worktree 创建已取消");
   return parsePrepareOutput(result.stdout);
 }
 
 export default function worktreeExtension(pi: ExtensionAPI) {
+  let pendingSwitch: WorktreePrepareResult | undefined;
+  let pendingDispatchScheduled = false;
+  let transitionReserved = false;
+
+  pi.on("agent_settled", event => {
+    if (!pendingSwitch || pendingDispatchScheduled) return;
+    if (event.aborted) {
+      pendingSwitch = undefined;
+      pendingDispatchScheduled = false;
+      transitionReserved = false;
+      return;
+    }
+    pendingDispatchScheduled = true;
+    // AgentSession defers prompts submitted from agent_settled until the event
+    // finishes. Command expansion then supplies a safe command context with
+    // switchSession(), after the tool result is persisted and the run is idle.
+    pi.sendUserMessage(`/worktree ${PENDING_SWITCH_ARGUMENT}`, {
+      expandPromptTemplates: true,
+    });
+  });
+
   pi.registerCommand("worktree", {
     description: "创建或复用 worktree，并在当前界面切换过去",
     handler: async (input, ctx) => {
+      const isPendingSwitch = input.trim() === PENDING_SWITCH_ARGUMENT;
       let prepared: WorktreePrepareResult;
       let targetSessionFile: string;
       try {
-        const { name, base } = parseCommandArgs(input);
+        if (!isPendingSwitch && transitionReserved) {
+          ctx.ui.notify("Agent 正在切换 worktree，请等待切换完成后再执行 /worktree。", "warning");
+          return;
+        }
+        if (!isPendingSwitch) transitionReserved = true;
+        const requestedSwitch = isPendingSwitch ? pendingSwitch : undefined;
+        if (isPendingSwitch && !requestedSwitch) {
+          throw new Error("没有待处理的 Agent worktree 切换");
+        }
         const sourceSessionFile = ctx.sessionManager.getSessionFile();
         if (!sourceSessionFile) {
           throw new Error("当前是临时会话；请启用 session 持久化后再切换 worktree");
         }
 
         await ctx.waitForIdle();
-        prepared = await prepareWorktree(pi, ctx.cwd, name, base);
+        if (requestedSwitch) {
+          prepared = requestedSwitch;
+        } else {
+          const { name, base } = parseCommandArgs(input);
+          prepared = await prepareWorktree(pi, ctx.cwd, name, base);
+        }
         if (resolve(ctx.cwd) === resolve(prepared.path)) {
+          if (isPendingSwitch) {
+            pendingSwitch = undefined;
+            pendingDispatchScheduled = false;
+          }
+          transitionReserved = false;
           ctx.ui.notify(`已经位于 worktree：${prepared.path}`, "info");
           return;
         }
 
-        const target = SessionManager.forkFrom(sourceSessionFile, prepared.path);
+        const sessionDir = ctx.sessionManager.usesDefaultSessionDir()
+          ? undefined
+          : ctx.sessionManager.getSessionDir();
+        const target = SessionManager.forkFrom(sourceSessionFile, prepared.path, sessionDir);
         targetSessionFile = target.getSessionFile() ?? "";
         if (!targetSessionFile) throw new Error("无法为 worktree 创建持久会话");
       } catch (error) {
+        if (isPendingSwitch) pendingSwitch = undefined;
+        pendingDispatchScheduled = false;
+        transitionReserved = false;
         ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
         return;
       }
 
       // Do not catch replacement errors here: switchSession may already have
       // invalidated this command context, so Pi must report such failures.
-      const switched = await ctx.switchSession(targetSessionFile, {
-        withSession: async (next) => {
-          const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
-          next.ui.notify(`已切换到 ${prepared.branch}：${prepared.path}${dirtyNote}`, "success");
-        },
-      });
+      let switched: { cancelled: boolean };
+      try {
+        switched = await ctx.switchSession(targetSessionFile, {
+          withSession: async (next) => {
+            const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
+            await next.sendMessage({
+              customType: "worktree-switch",
+              content: `✓ 已进入 worktree：${prepared.path}\nBranch: ${prepared.branch}${dirtyNote}`,
+              display: true,
+              details: prepared,
+            }, { triggerTurn: false });
+          },
+        });
+      } catch (error) {
+        pendingSwitch = undefined;
+        pendingDispatchScheduled = false;
+        transitionReserved = false;
+        throw error;
+      }
+      pendingSwitch = undefined;
+      pendingDispatchScheduled = false;
+      transitionReserved = false;
       if (switched.cancelled) {
         try {
           unlinkSync(targetSessionFile);
@@ -139,33 +196,49 @@ export default function worktreeExtension(pi: ExtensionAPI) {
     name: "enter_worktree",
     label: "Enter Worktree",
     exposure: "model-only",
+    executionMode: "sequential",
     description:
-      "Create or reuse an isolated git worktree and request that the host Harness move this current conversation into it. Call this tool alone, then stop; the Harness performs the session switch after the tool completes.",
+      "Create or reuse an isolated git worktree, then automatically move this current conversation into it after the current Agent run settles. Call this tool alone and do not call repository tools afterward.",
     parameters: Type.Object({
       name: Type.String({ description: "Single-segment worktree and branch name" }),
       base: Type.Optional(Type.String({ description: "Optional git ref used only when creating a new branch" })),
     }),
-    outputSchema: SwitchRequestSchema,
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const sourceSessionFile = ctx.sessionManager.getSessionFile();
-      if (!sourceSessionFile) throw new Error("当前是临时会话，Harness 无法续接到 worktree");
-
-      const prepared = await prepareWorktree(pi, ctx.cwd, params.name, params.base);
-      const request: WorktreeSwitchRequest = {
-        kind: WORKTREE_SWITCH_REQUEST,
-        version: 1,
-        action: "fork-and-switch",
-        sessionFile: sourceSessionFile,
+    outputSchema: EnterWorktreeResultSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (!ctx.sessionManager.getSessionFile()) {
+        throw new Error("当前是临时会话，无法续接到 worktree");
+      }
+      if (transitionReserved) {
+        const target = pendingSwitch ? `：${pendingSwitch.path}` : "";
+        throw new Error(`已有 worktree 切换正在处理${target}`);
+      }
+      transitionReserved = true;
+
+      let prepared: WorktreePrepareResult;
+      try {
+        prepared = await prepareWorktree(pi, ctx.cwd, params.name, params.base, signal);
+        if (signal.aborted) throw new Error("worktree 创建已取消");
+      } catch (error) {
+        transitionReserved = false;
+        throw error;
+      }
+      const alreadyActive = resolve(ctx.cwd) === resolve(prepared.path);
+      const result: EnterWorktreeResult = {
+        switch: alreadyActive ? "already-active" : "scheduled",
         ...prepared,
       };
+      if (alreadyActive) transitionReserved = false;
+      else pendingSwitch = prepared;
       const dirtyNote = prepared.dirty ? " 目标 worktree 已有未提交改动。" : "";
       return {
         content: [{
           type: "text",
-          text: `Worktree ${prepared.status}: ${prepared.path}.${dirtyNote} 已请求 Harness 将当前会话切换到该目录；不要继续调用仓库工具。`,
+          text: alreadyActive
+            ? `已经位于 worktree：${prepared.path}.${dirtyNote}`
+            : `Worktree ${prepared.status}: ${prepared.path}.${dirtyNote} 当前 Agent run 结束后会自动切换到该目录；不要继续调用仓库工具。`,
         }],
-        details: request,
-        structuredContent: request,
+        details: result,
+        structuredContent: result,
         terminate: true,
       };
     },

package/packages/worktree/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-worktree",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Git worktree CLI, Pi extension, and skill for isolated coding tasks.",
   "type": "module",
   "keywords": [

package/packages/worktree/skills/pi-worktree/SKILL.md

@@ -13,7 +13,7 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 
 | Command | Effect |
 |---|---|
-| `enter_worktree({ name, base? })` | Agent entrypoint: create/reuse a worktree and ask a compatible Harness to move this conversation there. Call it alone and stop after it returns. |
+| `enter_worktree({ name, base? })` | Agent entrypoint: create/reuse a worktree and automatically move this conversation there after the run settles. Call it alone and stop after it returns. |
 | `/worktree start <name> [--base <ref>]` | User entrypoint: fork the current persistent session into the worktree and switch the current Pi UI. |
 | `pi-worktree prepare [--base <ref>] [--json] <name>` | Create/reuse without launching Pi; `--json` is the machine interface. |
 | `pi-worktree start <name> [pi args...]` | Create or reuse `.worktrees/<name>`, then launch Pi inside it. Already inside a linked worktree, it just launches Pi there. |
@@ -27,14 +27,14 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 ## Isolating a task
 
 1. **Survey** — `pi-worktree list`, plus `pi-worktree info <name>` when the name you want is already taken. Reuse is free; a removed worktree is gone for good, because `remove` deletes its branch.
-2. **Enter** — as an Agent, call `enter_worktree` once and stop so the Harness can switch after settlement. A user can instead run `/worktree start <name>`. Use the CLI `start` only when a separate Pi process is wanted.
+2. **Enter** — as an Agent, call `enter_worktree` once and stop; the Extension switches automatically after settlement. A user can instead run `/worktree start <name>`. Use the CLI `start` only when a separate Pi process is wanted.
 3. **Work** — inside the worktree: commit there, and check `pi-worktree info <name>` before claiming progress. `ahead: N commits since base` is the evidence.
 4. **Land** — `pi-worktree out`, then `git merge <name>` in the main checkout. Done when the worktree's unique commits are in the target branch.
 5. **Clean up** — `pi-worktree remove <name>`. A merged branch goes without prompting; anything unmerged asks once.
 
 ## Entry-point rules
 
-- Prefer `enter_worktree` when it is available. Its `fork-and-switch` request requires Harness support: after `agent_settled`, the host forks the source session into the target cwd and switches to that persisted session. After the tool returns, do not read or modify repository files until the host has switched cwd.
+- Prefer `enter_worktree` when it is available. After the tool returns, do not read or modify repository files; the Extension waits for `agent_settled`, then forks the session into the target cwd and switches automatically.
 - `/worktree` is user-facing and cannot be invoked by the model. It requires a persisted session because it forks history into a session whose header owns the worktree cwd.
 - `pi-worktree start` **execs a new `pi`** in the worktree, and `out` execs a shell. Use this only for an intentionally separate process/session.
 - `prepare` is idempotent. It reports whether the target was created, attached, reused, or already active, and reports dirty reuse rather than discarding anything.

package/packages/worktree/tests/extension.test.mjs

@@ -1,114 +1,213 @@
+import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import test from "node:test";
+import { pathToFileURL } from "node:url";
 
-const root = await mkdtemp(join(tmpdir(), "pi-worktree-extension-"));
-process.env.PI_CODING_AGENT_DIR = join(root, "agent");
-const { default: register, WORKTREE_SWITCH_REQUEST } = await import("../extensions/worktree.ts");
+const extensionUrl = pathToFileURL(
+  join(import.meta.dirname, "..", "extensions", "worktree.ts"),
+).href;
 
-test.after(async () => {
-  await rm(root, { recursive: true, force: true });
-});
+function sourceSession(path, cwd) {
+  const timestamp = new Date().toISOString();
+  writeFileSync(path, [
+    JSON.stringify({ type: "session", version: 3, id: "source", timestamp, cwd }),
+    JSON.stringify({ type: "message", id: "history-1", parentId: null, timestamp, message: { role: "user", content: "preserve me", timestamp: Date.now() } }),
+    "",
+  ].join("\n"));
+}
+
+async function fixture({ cancelled = false, switchError, customSessionDir = true, deferExec = false } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "pi-worktree-extension-"));
+  const cwd = join(root, "repo");
+  const worktree = join(root, "feature");
+  const sessions = join(root, "sessions");
+  mkdirSync(cwd);
+  mkdirSync(worktree);
+  mkdirSync(sessions);
+  const source = join(sessions, "source.jsonl");
+  sourceSession(source, cwd);
 
-function setup(prepared) {
-  const commands = new Map();
-  const tools = new Map();
+  const handlers = {};
+  const sent = [];
+  const sessionMessages = [];
+  const notifications = [];
+  const execCalls = [];
+  let releaseExec;
+  let markExecStarted;
+  const execStarted = new Promise(resolve => { markExecStarted = resolve; });
   const pi = {
-    registerCommand(name, definition) { commands.set(name, definition); },
-    registerTool(definition) { tools.set(definition.name, definition); },
+    on(event, handler) { handlers[event] = handler; },
+    registerCommand(name, command) { handlers[`command:${name}`] = command.handler; },
+    registerTool(tool) { handlers.tool = tool; },
     async exec(command, args, options) {
-      assert.match(command, /packages\/worktree\/bin\/pi-worktree$/);
-      assert.deepEqual(args, ["prepare", "--json", "--base", "main", "feature"]);
-      assert.equal(options.cwd, prepared.cwd);
-      return { code: 0, stdout: `${JSON.stringify(prepared.result)}\n`, stderr: "" };
+      execCalls.push({ command, args, options });
+      assert.equal(options.cwd, cwd);
+      markExecStarted();
+      if (deferExec) await new Promise(resolve => { releaseExec = resolve; });
+      return {
+        code: 0,
+        stdout: JSON.stringify({ status: "created", path: worktree, branch: "feature", dirty: false }),
+        stderr: "",
+      };
     },
+    sendUserMessage(message, options) { sent.push({ message, options }); },
   };
-  register(pi);
-  return { commands, tools };
-}
 
-test("registers /worktree and switches a forked persistent session", async () => {
-  const cwd = join(root, "main");
-  const target = join(root, "main", ".worktrees", "feature");
-  await mkdir(target, { recursive: true });
-  const sourceSession = join(root, "source.jsonl");
-  await writeFile(sourceSession, `${JSON.stringify({ type: "session", version: 3, id: "source", timestamp: new Date().toISOString(), cwd })}\n`);
-  const prepared = { cwd, result: { status: "created", path: target, branch: "feature", dirty: false } };
-  const { commands } = setup(prepared);
-  const notifications = [];
-  let switchedFile;
-  await commands.get("worktree").handler("start feature --base main", {
-    cwd,
-    sessionManager: { getSessionFile: () => sourceSession },
-    waitForIdle: async () => {},
-    ui: { notify: (...args) => notifications.push(args) },
-    async switchSession(file, options) {
-      switchedFile = file;
-      await options.withSession({ ui: { notify: (...args) => notifications.push(args) } });
-      return { cancelled: false };
-    },
-  });
-
-  const header = JSON.parse((await readFile(switchedFile, "utf8")).split("\n")[0]);
-  assert.equal(header.cwd, target);
-  assert.equal(header.parentSession, sourceSession);
-  assert.deepEqual(notifications.at(-1), [`已切换到 feature：${target}`, "success"]);
-});
+  const extension = (await import(`${extensionUrl}?test=${Math.random()}`)).default;
+  extension(pi);
 
-test("removes the forked session when /worktree switching is cancelled", async () => {
-  const cwd = join(root, "cancel-main");
-  const target = join(cwd, ".worktrees", "feature");
-  await mkdir(target, { recursive: true });
-  const sourceSession = join(root, "cancel-source.jsonl");
-  await writeFile(sourceSession, `${JSON.stringify({ type: "session", version: 3, id: "cancel-source", timestamp: new Date().toISOString(), cwd })}\n`);
-  const prepared = { cwd, result: { status: "created", path: target, branch: "feature", dirty: false } };
-  const { commands } = setup(prepared);
-  const notifications = [];
-  let forkedFile;
-  await commands.get("worktree").handler("start feature --base main", {
+  let switchedTo;
+  const ctx = {
     cwd,
-    sessionManager: { getSessionFile: () => sourceSession },
-    waitForIdle: async () => {},
-    ui: { notify: (...args) => notifications.push(args) },
-    async switchSession(file) {
-      forkedFile = file;
-      return { cancelled: true };
+    sessionManager: {
+      getSessionFile: () => source,
+      usesDefaultSessionDir: () => !customSessionDir,
+      getSessionDir: () => sessions,
+    },
+    ui: { notify: (message, type) => notifications.push({ message, type }) },
+    async waitForIdle() {},
+    async switchSession(path, options) {
+      switchedTo = path;
+      if (cancelled) return { cancelled: true };
+      if (switchError) throw switchError;
+      await options.withSession({
+        ui: ctx.ui,
+        async sendMessage(message, options) { sessionMessages.push({ message, options }); },
+      });
+      return { cancelled: false };
     },
-  });
+  };
 
-  await assert.rejects(readFile(forkedFile, "utf8"), { code: "ENOENT" });
-  assert.deepEqual(notifications.at(-1), ["worktree 会话切换已取消", "warning"]);
-});
+  return {
+    root, cwd, worktree, sessions, handlers, sent, sessionMessages, notifications, execCalls, ctx,
+    execStarted,
+    releaseExec: () => releaseExec(),
+    switchedTo: () => switchedTo,
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
 
-test("registers enter_worktree with a durable Harness switch request", async () => {
-  const cwd = join(root, "main");
-  const target = join(cwd, ".worktrees", "feature");
-  const sourceSession = join(root, "tool-source.jsonl");
-  const prepared = { cwd, result: { status: "reused", path: target, branch: "feature", dirty: true } };
-  const { tools } = setup(prepared);
-  const tool = tools.get("enter_worktree");
-  assert.equal(tool.exposure, "model-only");
-  assert.ok(tool.outputSchema);
-  const result = await tool.execute(
+async function schedule(f) {
+  const result = await f.handlers.tool.execute(
     "call-1",
-    { name: "feature", base: "main" },
+    { name: "feature" },
     new AbortController().signal,
     undefined,
-    { cwd, sessionManager: { getSessionFile: () => sourceSession } },
+    f.ctx,
   );
+  assert.equal(result.details.switch, "scheduled");
+  assert.equal(f.handlers.tool.executionMode, "sequential");
+}
+
+test("enter_worktree defers, forks the current session, and switches automatically", async () => {
+  const f = await fixture();
+  try {
+    await schedule(f);
+    await f.handlers.agent_settled({ aborted: false });
+    assert.deepEqual(f.sent, [{
+      message: "/worktree __enter_worktree_pending__",
+      options: { expandPromptTemplates: true },
+    }]);
+
+    const internalArg = f.sent[0].message.slice("/worktree ".length);
+    await f.handlers["command:worktree"](internalArg, f.ctx);
+
+    const target = f.switchedTo();
+    assert.ok(target);
+    assert.equal(dirname(target), f.sessions, "custom session directory is preserved");
+    const header = JSON.parse(readFileSync(target, "utf8").split("\n")[0]);
+    assert.equal(header.cwd, f.worktree);
+    assert.equal(header.parentSession, join(f.sessions, "source.jsonl"));
+    assert.match(readFileSync(target, "utf8"), /"id":"history-1"/);
+    assert.deepEqual(f.sessionMessages, [{
+      message: {
+        customType: "worktree-switch",
+        content: `✓ 已进入 worktree：${f.worktree}\nBranch: feature`,
+        display: true,
+        details: { status: "created", path: f.worktree, branch: "feature", dirty: false },
+      },
+      options: { triggerTurn: false },
+    }]);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("public /worktree forwards --base to the CLI and switches", async () => {
+  const f = await fixture();
+  try {
+    await f.handlers["command:worktree"]("start feature --base main", f.ctx);
+    assert.match(f.execCalls[0].command, /packages\/worktree\/bin\/pi-worktree$/);
+    assert.deepEqual(f.execCalls[0].args, ["prepare", "--json", "--base", "main", "feature"]);
+    assert.equal(f.execCalls[0].options.cwd, f.cwd);
+    assert.ok(f.switchedTo());
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("aborted agent settlement discards the scheduled switch", async () => {
+  const f = await fixture();
+  try {
+    await schedule(f);
+    await f.handlers.agent_settled({ aborted: true });
+    assert.equal(f.sent.length, 0);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("a user command cannot race an Agent tool that is still preparing", async () => {
+  const f = await fixture({ deferExec: true });
+  try {
+    const toolResult = f.handlers.tool.execute(
+      "call-race",
+      { name: "feature" },
+      new AbortController().signal,
+      undefined,
+      f.ctx,
+    );
+    await f.execStarted;
+    await f.handlers["command:worktree"]("start other", f.ctx);
+    assert.equal(f.execCalls.length, 1);
+    assert.equal(f.switchedTo(), undefined);
+    assert.equal(f.notifications.at(-1).type, "warning");
+    f.releaseExec();
+    await toolResult;
+    await f.handlers.agent_settled({ aborted: true });
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("cancelling session replacement deletes the derived session", async () => {
+  const f = await fixture({ cancelled: true });
+  try {
+    await schedule(f);
+    await f.handlers.agent_settled({ aborted: false });
+    await f.handlers["command:worktree"]("__enter_worktree_pending__", f.ctx);
+
+    assert.equal(existsSync(f.switchedTo()), false);
+    assert.match(f.notifications.at(-1).message, /切换已取消/);
+    assert.equal(f.notifications.at(-1).type, "warning");
+  } finally {
+    f.cleanup();
+  }
+});
 
-  assert.equal(result.terminate, true);
-  assert.deepEqual(result.details, {
-    kind: WORKTREE_SWITCH_REQUEST,
-    version: 1,
-    action: "fork-and-switch",
-    sessionFile: sourceSession,
-    status: "reused",
-    path: target,
-    branch: "feature",
-    dirty: true,
-  });
-  assert.deepEqual(result.structuredContent, result.details);
+test("a replacement error does not delete a session that may already be active", async () => {
+  const f = await fixture({ switchError: new Error("host rebind failed") });
+  try {
+    await schedule(f);
+    await f.handlers.agent_settled({ aborted: false });
+    await assert.rejects(
+      f.handlers["command:worktree"]("__enter_worktree_pending__", f.ctx),
+      /host rebind failed/,
+    );
+    assert.equal(existsSync(f.switchedTo()), true);
+  } finally {
+    f.cleanup();
+  }
 });