@maxiaochao/pi-worktree 0.3.2 → 0.4.0

package/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/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/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/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/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/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/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/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>`.