@maxiaochao/pi-toolkit 0.10.24 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-12 - v0.11.0
+
+- bundle worktree v0.4.0: Replace CLI start and prepare with the create-only command
+- Replace `pi-worktree start` and `pi-worktree prepare` with the create-only `pi-worktree create` CLI; `/worktree start` and `enter_worktree` continue to switch the current Pi session.
+
 ## 2026-10-12 - v0.10.24
 
 - bundle herdr-subagents v0.4.10: Stabilize concurrency checks and cancellation synchronization on slower CI runners.
@@ -5,6 +10,7 @@
 ## 2026-10-12 - v0.10.23
 
 - bundle herdr-subagents v0.4.9: Stabilize concurrency checks on slower CI runners.
+
 ## 2026-10-12 - v0.10.22
 
 - bundle herdr-subagents v0.4.8: make blocking behave identically in serial and parallel runs and let respond continue a named failed task from its saved session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.24",
+  "version": "0.11.0",
   "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,10 @@
 # Changelog
 
+## 2026-10-12 - v0.4.0
+
+- Replace CLI start and prepare with the create-only command
+- replace the CLI `start` and `prepare` commands with one idempotent `create` command that never launches Pi
+
 ## 2026-10-09 - v0.3.2
 
 - continue Agent tasks automatically after switching into a worktree

package/packages/worktree/README.md

@@ -1,6 +1,6 @@
 # @maxiaochao/pi-worktree
 
-`pi-worktree` CLI、Pi Extension 与配套 skill。它既能启动独立 Pi，也能让用户或 Agent 在当前 Pi 界面中切换 worktree，并保留完整对话。
+`pi-worktree` CLI、Pi Extension 与配套 skill。CLI 负责管理 worktree；Extension 让用户或 Agent 在当前 Pi 界面中切换，并保留完整对话。
 
 ![Worktree 在真实临时 Git 仓库中的运行截图](docs/screenshot.png)
 
@@ -13,14 +13,14 @@
 ![Worktree 隔离流程演示](docs/demo.gif)
 
 ```bash
-pi-worktree start feature -p "implement the feature"
-pi-worktree prepare --json feature
+pi-worktree create feature
+pi-worktree create --base main --json feature
 pi-worktree info feature
 pi-worktree out
 pi-worktree remove feature
 ```
 
-`start` 从当前分支创建或复用 `.worktrees/feature`，记录 base，并在该目录启动 Pi。`prepare` 复用同一创建逻辑，但只返回目标，不启动嵌套 Pi。
+`create` 从当前分支（或显式 `--base`）创建或复用 `.worktrees/feature` 并记录 base，不启动 Pi。`--json` 提供相同操作的机器可读结果。
 
 在交互式 Pi 中，用户可以保留当前界面和完整对话：
 
@@ -61,8 +61,7 @@ pi update npm:@maxiaochao/pi-worktree # 更新独立子包
 ## 命令
 
 ```bash
-pi-worktree start <name> [pi args...]
-pi-worktree prepare [--base <ref>] [--json] <name>
+pi-worktree create [--base <ref>] [--json] <name>
 pi-worktree list
 pi-worktree info <name>
 pi-worktree out
@@ -70,6 +69,6 @@ pi-worktree remove <name>
 pi-worktree prune
 ```
 
-`prepare --json` 是 Extension 和其他宿主使用的幂等机器接口，返回 `created`、`attached`、`reused` 或 `already-active`，以及绝对路径、分支和 dirty 状态。已有 worktree 会复用；已存在但未挂载的同名分支会挂载；stale 注册、非法名称和路径冲突会显式失败。
+`create` 是幂等接口；`create --json` 供 Extension 和其他宿主使用，返回 `created`、`attached`、`reused` 或 `already-active`，以及绝对路径、分支和 dirty 状态。已有 worktree 会复用；已存在但未挂载的同名分支会挂载；stale 注册、非法名称和路径冲突会显式失败。
 
 Agent 用法见 `skills/pi-worktree/SKILL.md`。测试流程、夹具和结果见 [TESTING.md](TESTING.md)。

package/packages/worktree/TESTING.md

@@ -4,19 +4,19 @@
 
 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` 交互流程。
+3. 手工验收发布包的 `pi-worktree create` 创建与复用流程。
 4. 确认 README 示例、真实临时 Git 仓库输出 `docs/screenshot.png` 和 `docs/demo.gif` 进入 tarball。
 
 ## 用例数据
 
 - `--help` 输出命令说明。
-- `start` 从当前分支创建 `.worktrees/<name>` 并记录 base。
-- `prepare --json` 覆盖 created、reused、already-active、dirty 和非法名称安全失败。
+- `create` 从当前分支创建 `.worktrees/<name>` 并记录 base。
+- `create --json` 覆盖 created、reused、already-active、dirty 和非法名称安全失败。
 - `/worktree start` 把历史 fork 到 cwd 正确的新 session，再调用 `switchSession`。
-- `enter_worktree` 串行准备目标，在 `agent_settled` 后触发内部命令，并 fork 当前 session 后调用 `switchSession`。
+- `enter_worktree` 串行创建或复用目标，在 `agent_settled` 后触发内部命令，并 fork 当前 session 后调用 `switchSession`。
 - Agent 轮被中止时不触发切换；用户取消 session replacement 时删除派生 session。
 - 自定义 session 目录在 fork 后保持不变。
-- 假 Pi 收到正确工作目录和参数。
+- 已删除的 CLI `start` 和 `prepare` 会显式失败。
 - `list` 标记主 checkout 和子 worktree。
 - `info` 报告 clean、branch、base 和 ahead。
 - postinstall 把可执行 CLI 与 completion 复制到隔离 HOME，并保持执行权限。

package/packages/worktree/bin/pi-worktree

@@ -1,10 +1,8 @@
 #!/usr/bin/env bash
-# pi-worktree: create/reuse a git worktree, then launch pi inside it.
+# pi-worktree: create, inspect, and clean up git worktrees.
 #
 # Usage:
-#   pi-worktree start <name> [pi args...]  # enter worktree <name> and start pi
-#   pi-worktree start --base <ref> <name> [pi args...]  # branch from <ref> instead of current branch
-#   pi-worktree prepare [--base <ref>] [--json] <name>  # create/reuse without launching pi
+#   pi-worktree create [--base <ref>] [--json] <name>  # create/reuse without launching pi
 #   pi-worktree -l | --list                # list worktrees (main checkout marked "main checkout")
 #   pi-worktree -i <name>                  # show base commit, ahead/behind, unique commits
 #   pi-worktree -o | --out                 # cd back to the main checkout
@@ -229,13 +227,13 @@ cmd_remove() {
       if [[ "$ans" =~ ^[Yy]$ ]]; then
         git branch -D "$branch" && ok "deleted branch: $branch"
       else
-        warn "branch '$branch' kept; 'pi-worktree start $branch' will reuse it as-is"
+        warn "branch '$branch' kept; 'pi-worktree create $branch' will reuse it as-is"
       fi
     fi
   fi
 }
 
-prepare_wt() {
+create_wt() {
   local name="$1"
   require_repo
   validate_name "$name"
@@ -247,11 +245,11 @@ prepare_wt() {
     current_branch=$(git branch --show-current)
     [[ "$current_branch" == "$name" ]] \
       || die "already inside linked worktree '$current_branch'; return to the main checkout first"
-    PREPARE_STATUS="already-active"
-    PREPARE_DIR=$(pwd -P)
-    PREPARE_BRANCH="$current_branch"
-    PREPARE_DIRTY=false
-    if [[ -n "$(git status --porcelain)" ]]; then PREPARE_DIRTY=true; fi
+    CREATE_STATUS="already-active"
+    CREATE_DIR=$(pwd -P)
+    CREATE_BRANCH="$current_branch"
+    CREATE_DIRTY=false
+    if [[ -n "$(git status --porcelain)" ]]; then CREATE_DIRTY=true; fi
     return 0
   fi
 
@@ -275,7 +273,7 @@ prepare_wt() {
       || die "$dir is not checked out on expected branch '$name'"
     ensure_gitignore
     ok "reusing existing worktree $dir"
-    PREPARE_STATUS="reused"
+    CREATE_STATUS="reused"
   else
     local target_abs registered_path
     target_abs="$dir"
@@ -292,7 +290,7 @@ prepare_wt() {
         git worktree add "$dir" "$name"
       fi
       ok "checked out existing branch '$name'"
-      PREPARE_STATUS="attached"
+      CREATE_STATUS="attached"
       # record a best-effort base for -i display
       local mb; mb=$(git merge-base main "$name" 2>/dev/null || true)
       [[ -n "$mb" ]] && git config "branch.$name.base" "$(git rev-parse --short "$mb")" \
@@ -307,71 +305,46 @@ prepare_wt() {
       git config "branch.$name.base" "$(git rev-parse --short "$base")"
       git config "branch.$name.baseRef" "$base"
       ok "created branch '$name' from $base @ $(git rev-parse --short "$base")"
-      PREPARE_STATUS="created"
+      CREATE_STATUS="created"
     fi
   fi
 
-  PREPARE_DIR=$(cd "$dir" && pwd -P)
-  PREPARE_BRANCH=$(git -C "$dir" branch --show-current)
-  PREPARE_DIRTY=false
-  if [[ -n "$(git -C "$dir" status --porcelain)" ]]; then PREPARE_DIRTY=true; fi
+  CREATE_DIR=$(cd "$dir" && pwd -P)
+  CREATE_BRANCH=$(git -C "$dir" branch --show-current)
+  CREATE_DIRTY=false
+  if [[ -n "$(git -C "$dir" status --porcelain)" ]]; then CREATE_DIRTY=true; fi
 }
 
-print_prepare_json() {
-  PI_WORKTREE_STATUS="$PREPARE_STATUS" \
-  PI_WORKTREE_PATH="$PREPARE_DIR" \
-  PI_WORKTREE_BRANCH="$PREPARE_BRANCH" \
-  PI_WORKTREE_DIRTY="$PREPARE_DIRTY" \
+print_create_json() {
+  PI_WORKTREE_STATUS="$CREATE_STATUS" \
+  PI_WORKTREE_PATH="$CREATE_DIR" \
+  PI_WORKTREE_BRANCH="$CREATE_BRANCH" \
+  PI_WORKTREE_DIRTY="$CREATE_DIRTY" \
     node -e 'process.stdout.write(JSON.stringify({status:process.env.PI_WORKTREE_STATUS,path:process.env.PI_WORKTREE_PATH,branch:process.env.PI_WORKTREE_BRANCH,dirty:process.env.PI_WORKTREE_DIRTY==="true"})+"\n")'
 }
 
-cmd_prepare() {
+cmd_create() {
   BASE_OVERRIDE=""
   local json=0
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --base)
-        shift; [[ $# -ge 1 ]] || die "usage: pi-worktree prepare [--base <ref>] [--json] <name>"
+        shift; [[ $# -ge 1 ]] || die "usage: pi-worktree create [--base <ref>] [--json] <name>"
         BASE_OVERRIDE="$1"; shift ;;
       --json) json=1; QUIET=1; shift ;;
-      --*) die "unknown prepare option: $1" ;;
+      --*) die "unknown create option: $1" ;;
       *) break ;;
     esac
   done
-  [[ $# -eq 1 ]] || die "usage: pi-worktree prepare [--base <ref>] [--json] <name>"
-  prepare_wt "$1"
+  [[ $# -eq 1 ]] || die "usage: pi-worktree create [--base <ref>] [--json] <name>"
+  create_wt "$1"
   if [[ "$json" == 1 ]]; then
-    print_prepare_json
+    print_create_json
   else
-    ok "$PREPARE_STATUS worktree: $PREPARE_DIR ($PREPARE_BRANCH)"
+    ok "$CREATE_STATUS worktree: $CREATE_DIR ($CREATE_BRANCH)"
   fi
 }
 
-cd_wt() {
-  local name="$1"; shift
-  require_repo
-
-  # Already isolated? Preserve the original start behavior and launch Pi here.
-  if in_linked_worktree; then
-    ok "already in an isolated worktree ($(pwd)), launching pi here"
-    exec pi "$@"
-  fi
-
-  # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
-  local dir; dir="$(main_checkout)/.worktrees/$name"
-  if [[ ! -d "$dir" ]] && { ! git diff --quiet || ! git diff --cached --quiet || [[ -n "$(git ls-files --others --exclude-standard)" ]]; }; then
-    warn "Uncommitted changes stay in THIS directory; they will NOT appear in the worktree:"
-    git status --short | head -20
-    read -rp "Continue? [y/N] " ans
-    [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
-  fi
-
-  prepare_wt "$name"
-
-  cd "$PREPARE_DIR"
-  exec pi "$@"
-}
-
 case "${1:-}" in
   -l|--list|list|ls) shift; cmd_list "$@" ;;
   -i|--info|info) shift; cmd_info "$@" ;;
@@ -379,15 +352,7 @@ case "${1:-}" in
   -r|--remove|rm|remove) shift; cmd_remove "$@" ;;
   -p|--prune|prune) shift; subcmd_prune ;;
   -h|--help|help) sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//' ;;
-  prepare) shift; cmd_prepare "$@" ;;
-  start) shift
-    BASE_OVERRIDE=""
-    if [[ "${1:-}" == "--base" ]]; then
-      shift; [[ $# -ge 2 ]] || die "usage: pi-worktree start --base <ref> <name> [pi args...]"
-      BASE_OVERRIDE="$1"; shift
-    fi
-    [[ $# -ge 1 ]] || die "usage: pi-worktree start <name> [pi args...]"
-    name="$1"; shift; cd_wt "$name" "$@" ;;
-  "")  die "usage: pi-worktree start <name> [pi args...]  (or list / info / out / remove / prune)" ;;
-  *)   die "unknown command: $1  (usage: pi-worktree start <name> [pi args...])" ;;
+  create) shift; cmd_create "$@" ;;
+  "")  die "usage: pi-worktree create <name>  (or list / info / out / remove / prune)" ;;
+  *)   die "unknown command: $1  (usage: pi-worktree create <name>)" ;;
 esac

package/packages/worktree/bin/pi-worktree-completion.bash

@@ -4,7 +4,7 @@ _pi_worktree() {
   cur="${COMP_WORDS[COMP_CWORD]}"
   first="${COMP_WORDS[1]}"
 
-  local SUBS="start prepare list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
+  local SUBS="create list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
 
   # existing worktree names (only linked worktrees, i.e. under .worktrees/)
   local wts=""
@@ -17,13 +17,13 @@ _pi_worktree() {
   fi
 
   if (( COMP_CWORD == 1 )); then
-    # first word: subcommands, flags, and existing worktree names (to enter)
+    # first word: subcommands, flags, and existing worktree names
     COMPREPLY=($(compgen -W "$SUBS $wts" -- "$cur"))
     return
   fi
 
   case "$first" in
-    -i|--info|info|-r|--remove|remove|rm|start|prepare)
+    -i|--info|info|-r|--remove|remove|rm|create)
       # only the second word of info/remove completes worktree names;
       # later words offer nothing (info/remove take no further args)
       if (( COMP_CWORD == 2 )); then
@@ -33,7 +33,7 @@ _pi_worktree() {
       fi
       ;;
     *)
-      # after a name: default (file) completion for pi args
+      # no command-specific completion
       COMPREPLY=()
       ;;
   esac

package/packages/worktree/extensions/worktree.ts

@@ -7,14 +7,14 @@ import { Type } from "typebox";
 const CLI_PATH = fileURLToPath(new URL("../bin/pi-worktree", import.meta.url));
 const PENDING_SWITCH_ARGUMENT = "__enter_worktree_pending__";
 
-export interface WorktreePrepareResult {
+export interface WorktreeCreateResult {
   status: "created" | "attached" | "reused" | "already-active";
   path: string;
   branch: string;
   dirty: boolean;
 }
 
-export interface EnterWorktreeResult extends WorktreePrepareResult {
+export interface EnterWorktreeResult extends WorktreeCreateResult {
   switch: "scheduled" | "already-active";
 }
 
@@ -49,41 +49,41 @@ function parseCommandArgs(input: string): { name: string; base?: string } {
   return { name, base };
 }
 
-function parsePrepareOutput(stdout: string): WorktreePrepareResult {
+function parseCreateOutput(stdout: string): WorktreeCreateResult {
   const line = stdout.trim().split("\n").filter(Boolean).at(-1);
-  if (!line) throw new Error("pi-worktree prepare 没有返回结果");
-  const result = JSON.parse(line) as Partial<WorktreePrepareResult>;
+  if (!line) throw new Error("pi-worktree create 没有返回结果");
+  const result = JSON.parse(line) as Partial<WorktreeCreateResult>;
   if (
     !["created", "attached", "reused", "already-active"].includes(String(result.status))
     || typeof result.path !== "string"
     || typeof result.branch !== "string"
     || typeof result.dirty !== "boolean"
   ) {
-    throw new Error("pi-worktree prepare 返回了无效结果");
+    throw new Error("pi-worktree create 返回了无效结果");
   }
-  return result as WorktreePrepareResult;
+  return result as WorktreeCreateResult;
 }
 
-async function prepareWorktree(
+async function createWorktree(
   pi: ExtensionAPI,
   cwd: string,
   name: string,
   base?: string,
   signal?: AbortSignal,
-): Promise<WorktreePrepareResult> {
-  const args = ["prepare", "--json"];
+): Promise<WorktreeCreateResult> {
+  const args = ["create", "--json"];
   if (base) args.push("--base", base);
   args.push(name);
   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}）`);
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `pi-worktree create 失败（退出码 ${result.code}）`);
   }
   if (signal?.aborted) throw new Error("worktree 创建已取消");
-  return parsePrepareOutput(result.stdout);
+  return parseCreateOutput(result.stdout);
 }
 
 export default function worktreeExtension(pi: ExtensionAPI) {
-  let pendingSwitch: WorktreePrepareResult | undefined;
+  let pendingSwitch: WorktreeCreateResult | undefined;
   let pendingDispatchScheduled = false;
   let transitionReserved = false;
 
@@ -108,7 +108,7 @@ export default function worktreeExtension(pi: ExtensionAPI) {
     description: "创建或复用 worktree，并在当前界面切换过去",
     handler: async (input, ctx) => {
       const isPendingSwitch = input.trim() === PENDING_SWITCH_ARGUMENT;
-      let prepared: WorktreePrepareResult;
+      let created: WorktreeCreateResult;
       let targetSessionFile: string;
       try {
         if (!isPendingSwitch && transitionReserved) {
@@ -127,25 +127,25 @@ export default function worktreeExtension(pi: ExtensionAPI) {
 
         await ctx.waitForIdle();
         if (requestedSwitch) {
-          prepared = requestedSwitch;
+          created = requestedSwitch;
         } else {
           const { name, base } = parseCommandArgs(input);
-          prepared = await prepareWorktree(pi, ctx.cwd, name, base);
+          created = await createWorktree(pi, ctx.cwd, name, base);
         }
-        if (resolve(ctx.cwd) === resolve(prepared.path)) {
+        if (resolve(ctx.cwd) === resolve(created.path)) {
           if (isPendingSwitch) {
             pendingSwitch = undefined;
             pendingDispatchScheduled = false;
           }
           transitionReserved = false;
-          ctx.ui.notify(`已经位于 worktree：${prepared.path}`, "info");
+          ctx.ui.notify(`已经位于 worktree：${created.path}`, "info");
           return;
         }
 
         const sessionDir = ctx.sessionManager.usesDefaultSessionDir()
           ? undefined
           : ctx.sessionManager.getSessionDir();
-        const target = SessionManager.forkFrom(sourceSessionFile, prepared.path, sessionDir);
+        const target = SessionManager.forkFrom(sourceSessionFile, created.path, sessionDir);
         targetSessionFile = target.getSessionFile() ?? "";
         if (!targetSessionFile) throw new Error("无法为 worktree 创建持久会话");
       } catch (error) {
@@ -162,12 +162,12 @@ export default function worktreeExtension(pi: ExtensionAPI) {
       try {
         switched = await ctx.switchSession(targetSessionFile, {
           withSession: async (next) => {
-            const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
+            const dirtyNote = created.dirty ? "（已有未提交改动）" : "";
             await next.sendMessage({
               customType: "worktree-switch",
-              content: `✓ 已进入 worktree：${prepared.path}\nBranch: ${prepared.branch}${dirtyNote}\n\n在worktree继续任务`,
+              content: `✓ 已进入 worktree：${created.path}\nBranch: ${created.branch}${dirtyNote}\n\n在worktree继续任务`,
               display: true,
-              details: prepared,
+              details: created,
             }, { triggerTurn: true, deliverAs: "followUp" });
           },
         });
@@ -214,28 +214,28 @@ export default function worktreeExtension(pi: ExtensionAPI) {
       }
       transitionReserved = true;
 
-      let prepared: WorktreePrepareResult;
+      let created: WorktreeCreateResult;
       try {
-        prepared = await prepareWorktree(pi, ctx.cwd, params.name, params.base, signal);
+        created = await createWorktree(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 alreadyActive = resolve(ctx.cwd) === resolve(created.path);
       const result: EnterWorktreeResult = {
         switch: alreadyActive ? "already-active" : "scheduled",
-        ...prepared,
+        ...created,
       };
       if (alreadyActive) transitionReserved = false;
-      else pendingSwitch = prepared;
-      const dirtyNote = prepared.dirty ? " 目标 worktree 已有未提交改动。" : "";
+      else pendingSwitch = created;
+      const dirtyNote = created.dirty ? " 目标 worktree 已有未提交改动。" : "";
       return {
         content: [{
           type: "text",
           text: alreadyActive
-            ? `已经位于 worktree：${prepared.path}.${dirtyNote}`
-            : `Worktree ${prepared.status}: ${prepared.path}.${dirtyNote} 当前 Agent run 结束后会自动切换到该目录；不要继续调用仓库工具。`,
+            ? `已经位于 worktree：${created.path}.${dirtyNote}`
+            : `Worktree ${created.status}: ${created.path}.${dirtyNote} 当前 Agent run 结束后会自动切换到该目录；不要继续调用仓库工具。`,
         }],
         details: result,
         structuredContent: result,

package/packages/worktree/package.json

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

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

@@ -15,9 +15,7 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 |---|---|
 | `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. |
-| `pi-worktree start --base <ref> <name> [pi args...]` | Same, but branch from `<ref>` instead of the current branch. |
+| `pi-worktree create [--base <ref>] [--json] <name>` | Idempotently create/reuse without launching Pi; `--json` is the machine interface. |
 | `pi-worktree list` | All worktrees; the main checkout is marked `(main checkout)`, stale registrations are flagged. |
 | `pi-worktree info <name>` | Clean/dirty status, branch and HEAD, base commit, ahead/behind `main`, unique commits. |
 | `pi-worktree out` | Open a shell in the main checkout (for merging). |
@@ -27,7 +25,7 @@ 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; 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.
+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>`.
 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.
@@ -36,6 +34,5 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 
 - 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.
+- `create` is idempotent and never launches Pi. It reports whether the target was created, attached, reused, or already active, and reports dirty reuse rather than discarding anything.
 - `remove` asks before discarding dirty files or unmerged commits, and a non-interactive stdin (EOF) aborts safely. Answer explicitly when the removal is intended: `printf 'y\ny\n' | pi-worktree remove <name>`.

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

@@ -140,7 +140,7 @@ test("public /worktree forwards --base to the CLI and switches", async () => {
   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.deepEqual(f.execCalls[0].args, ["create", "--json", "--base", "main", "feature"]);
     assert.equal(f.execCalls[0].options.cwd, f.cwd);
     assert.ok(f.switchedTo());
   } finally {
@@ -159,7 +159,7 @@ test("aborted agent settlement discards the scheduled switch", async () => {
   }
 });
 
-test("a user command cannot race an Agent tool that is still preparing", async () => {
+test("a user command cannot race an Agent tool that is still creating", async () => {
   const f = await fixture({ deferExec: true });
   try {
     const toolResult = f.handlers.tool.execute(

package/packages/worktree/tests/run-tests.sh

@@ -5,14 +5,6 @@ PACKAGE_DIR=$(cd "$(dirname "$0")/.." && pwd)
 ROOT=$(mktemp -d)
 trap 'rm -rf "$ROOT"' EXIT
 
-mkdir -p "$ROOT/bin"
-cat > "$ROOT/bin/pi" <<'EOF'
-#!/usr/bin/env bash
-printf '%s\n' "$PWD" > "${PI_WORKTREE_TEST_OUTPUT}.cwd"
-printf '%s\n' "$@" > "${PI_WORKTREE_TEST_OUTPUT}.args"
-EOF
-chmod +x "$ROOT/bin/pi"
-
 mkdir "$ROOT/repo"
 cd "$ROOT/repo"
 git init -q -b main
@@ -23,15 +15,11 @@ printf 'base\n' > tracked.txt
 git add .gitignore tracked.txt
 git commit -qm initial
 
-export PATH="$ROOT/bin:$PATH"
-export PI_WORKTREE_TEST_OUTPUT="$ROOT/pi"
-bash "$PACKAGE_DIR/bin/pi-worktree" start feature --model fake/model
+feature_json=$(bash "$PACKAGE_DIR/bin/pi-worktree" create --json feature)
 
 test -d .worktrees/feature
 test "$(git -C .worktrees/feature branch --show-current)" = feature
-test "$(cat "$ROOT/pi.cwd")" = "$ROOT/repo/.worktrees/feature"
-grep -qx -- '--model' "$ROOT/pi.args"
-grep -qx -- 'fake/model' "$ROOT/pi.args"
+node -e 'if (JSON.parse(process.argv[1]).status !== "created") process.exit(1)' "$feature_json"
 
 bash "$PACKAGE_DIR/bin/pi-worktree" list > "$ROOT/list.txt"
 grep -q 'main checkout' "$ROOT/list.txt"
@@ -42,14 +30,14 @@ grep -q 'status:   clean' "$ROOT/info.txt"
 grep -q 'branch:   feature' "$ROOT/info.txt"
 grep -q 'based on:' "$ROOT/info.txt"
 
-bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json feature > "$ROOT/reused.json"
+bash "$PACKAGE_DIR/bin/pi-worktree" create --json feature > "$ROOT/reused.json"
 node -e '
   const fs = require("node:fs");
   const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
   if (value.status !== "reused" || value.branch !== "feature" || value.dirty !== false) process.exit(1);
 ' "$ROOT/reused.json"
 
-bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json prepared > "$ROOT/created.json"
+bash "$PACKAGE_DIR/bin/pi-worktree" create --json prepared > "$ROOT/created.json"
 node -e '
   const fs = require("node:fs");
   const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
@@ -57,7 +45,7 @@ node -e '
 ' "$ROOT/created.json"
 
 mkdir -p nested/path
-(cd nested/path && bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json from-subdir) > "$ROOT/subdir.json"
+(cd nested/path && bash "$PACKAGE_DIR/bin/pi-worktree" create --json from-subdir) > "$ROOT/subdir.json"
 node -e '
   const fs = require("node:fs");
   const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
@@ -65,50 +53,50 @@ node -e '
 ' "$ROOT/subdir.json" "$ROOT/repo"
 
 git branch attachable
-bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json attachable > "$ROOT/attached.json"
+bash "$PACKAGE_DIR/bin/pi-worktree" create --json attachable > "$ROOT/attached.json"
 node -e '
   const fs = require("node:fs");
   const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
   if (value.status !== "attached" || value.branch !== "attachable") process.exit(1);
 ' "$ROOT/attached.json"
 
-bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json stale > /dev/null
+bash "$PACKAGE_DIR/bin/pi-worktree" create --json stale > /dev/null
 rm -rf .worktrees/stale
-if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json stale >/dev/null 2>&1; then
-  echo "prepare silently replaced a stale worktree registration" >&2
+if bash "$PACKAGE_DIR/bin/pi-worktree" create --json stale >/dev/null 2>&1; then
+  echo "create silently replaced a stale worktree registration" >&2
   exit 1
 fi
 git worktree prune
 
 git worktree add .worktrees/wrong -b another-branch >/dev/null
-if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json wrong >/dev/null 2>&1; then
-  echo "prepare reused a path checked out on the wrong branch" >&2
+if bash "$PACKAGE_DIR/bin/pi-worktree" create --json wrong >/dev/null 2>&1; then
+  echo "create reused a path checked out on the wrong branch" >&2
   exit 1
 fi
 
 mkdir .worktrees/main
-if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json main >/dev/null 2>&1; then
-  echo "prepare reused an ordinary directory as a worktree"
+if bash "$PACKAGE_DIR/bin/pi-worktree" create --json main >/dev/null 2>&1; then
+  echo "create reused an ordinary directory as a worktree"
   exit 1
 fi
 
 printf 'changed\n' >> .worktrees/prepared/tracked.txt
-bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json prepared > "$ROOT/dirty.json"
+bash "$PACKAGE_DIR/bin/pi-worktree" create --json prepared > "$ROOT/dirty.json"
 node -e '
   const fs = require("node:fs");
   const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
   if (value.status !== "reused" || value.dirty !== true) process.exit(1);
 ' "$ROOT/dirty.json"
 
-(cd .worktrees/prepared && bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json prepared) > "$ROOT/active.json"
+(cd .worktrees/prepared && bash "$PACKAGE_DIR/bin/pi-worktree" create --json prepared) > "$ROOT/active.json"
 node -e '
   const fs = require("node:fs");
   const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
   if (value.status !== "already-active" || value.dirty !== true) process.exit(1);
 ' "$ROOT/active.json"
 
-if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json ../escape >/dev/null 2>&1; then
-  echo "prepare accepted an unsafe worktree name" >&2
+if bash "$PACKAGE_DIR/bin/pi-worktree" create --json ../escape >/dev/null 2>&1; then
+  echo "create accepted an unsafe worktree name" >&2
   exit 1
 fi
 
@@ -122,11 +110,19 @@ mkdir "$ROOT/symlink-repo" "$ROOT/outside-worktrees"
   git add tracked.txt
   git commit -qm initial
   ln -s "$ROOT/outside-worktrees" .worktrees
-  if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json escaped >/dev/null 2>&1; then
-    echo "prepare followed a symlinked .worktrees directory" >&2
+  if bash "$PACKAGE_DIR/bin/pi-worktree" create --json escaped >/dev/null 2>&1; then
+    echo "create followed a symlinked .worktrees directory" >&2
     exit 1
   fi
 )
 
-bash "$PACKAGE_DIR/bin/pi-worktree" --help | grep -q 'pi-worktree start'
+bash "$PACKAGE_DIR/bin/pi-worktree" --help | grep -q 'pi-worktree create'
+if bash "$PACKAGE_DIR/bin/pi-worktree" prepare feature >/dev/null 2>&1; then
+  echo "removed prepare command is still accepted" >&2
+  exit 1
+fi
+if bash "$PACKAGE_DIR/bin/pi-worktree" start feature >/dev/null 2>&1; then
+  echo "removed start command is still accepted" >&2
+  exit 1
+fi
 printf 'PASS worktree CLI integration cases\n'