@maxiaochao/pi-toolkit 0.10.7 → 0.10.9

package/packages/scheduler/extensions/scheduler.ts

@@ -1,11 +1,11 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { Scheduler, systemClock, type ScheduleSnapshot } from "../src/scheduler.ts";
 
 const Params = Type.Object({
-	action: StringEnum(["add", "list", "trigger", "cancel"] as const),
+	action: StringEnum(["add", "list", "trigger", "cancel", "clear"] as const),
 	every: Type.Optional(Type.String({ description: "Interval for add, for example 30s, 5m, or 1h30m" })),
 	prompt: Type.Optional(Type.String({ description: "Prompt delivered to the main agent on each trigger" })),
 	id: Type.Optional(Type.String({ description: "Schedule ID for trigger or cancel" })),
@@ -22,29 +22,94 @@ function formatList(schedules: ScheduleSnapshot[]): string {
 	).join("\n");
 }
 
-function parseCommand(input: string): { action: "add" | "list" | "trigger" | "cancel"; every?: string; prompt?: string; id?: string } {
+type ScheduleAction = "add" | "list" | "trigger" | "cancel" | "clear";
+
+function parseCommand(input: string): { action: ScheduleAction; every?: string; prompt?: string; id?: string } {
 	const text = input.trim();
 	if (!text || text === "list") return { action: "list" };
 	const [action, first, ...rest] = text.split(/\s+/);
 	if (action === "add") return { action, every: first, prompt: rest.join(" ") };
 	if (action === "trigger" || action === "cancel") return { action, id: first };
-	throw new Error("usage: /schedule add <interval> <prompt> | list | trigger <id> | cancel <id>");
+	if (action === "clear") return { action };
+	throw new Error("usage: /schedule add <interval> <prompt> | list | trigger <id> | cancel <id> | clear");
+}
+
+const WIDGET_KEY = "scheduler";
+
+export class ScheduleWidget {
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+	private readonly getSchedules: () => ScheduleSnapshot[];
+	private readonly theme: Theme;
+
+	constructor(getSchedules: () => ScheduleSnapshot[], theme: Theme) {
+		this.getSchedules = getSchedules;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const schedules = this.getSchedules();
+		this.cachedLines = [
+			truncateToWidth(this.theme.fg("accent", `⏱ ${schedules.length} active schedule${schedules.length === 1 ? "" : "s"}`), width),
+			...schedules.map((item) => {
+				const marker = item.pending ? this.theme.fg("warning", "●") : this.theme.fg("dim", "○");
+				const state = item.pending ? " · pending" : "";
+				return truncateToWidth(`  ${marker} ${this.theme.fg("accent", item.id)} · ${item.every} · next ${formatTime(item.nextRunAt)}${state} · ${this.theme.fg("text", item.prompt)}`, width);
+			}),
+		];
+		this.cachedWidth = width;
+		return this.cachedLines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}
+
+interface MountedWidget {
+	component: ScheduleWidget;
+	tui: { requestRender(): void };
 }
 
 export default function (pi: ExtensionAPI) {
 	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1") return;
 	let context: ExtensionContext | undefined;
+	let mountedWidget: MountedWidget | undefined;
 
-	const refreshStatus = () => {
+	const refreshUI = () => {
 		if (!context?.hasUI) return;
 		const schedules = scheduler.list();
-		const next = schedules[0];
-		context.ui.setStatus("scheduler", next ? `⏱ ${schedules.length} schedule${schedules.length === 1 ? "" : "s"} · next ${formatTime(next.nextRunAt)}` : undefined);
+		if (context.mode !== "tui") {
+			const next = schedules[0];
+			context.ui.setStatus(WIDGET_KEY, next ? `⏱ ${schedules.length} schedule${schedules.length === 1 ? "" : "s"} · next ${formatTime(next.nextRunAt)}` : undefined);
+			return;
+		}
+		context.ui.setStatus(WIDGET_KEY, undefined);
+		if (schedules.length === 0) {
+			if (mountedWidget) {
+				context.ui.setWidget(WIDGET_KEY, undefined);
+				mountedWidget.tui.requestRender();
+				mountedWidget = undefined;
+			}
+			return;
+		}
+		if (mountedWidget) {
+			mountedWidget.component.invalidate();
+			mountedWidget.tui.requestRender();
+			return;
+		}
+		context.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+			const component = new ScheduleWidget(() => scheduler.list(), theme);
+			mountedWidget = { component, tui };
+			return component;
+		}, { placement: "aboveEditor" });
 	};
 
 	const scheduler = new Scheduler({
 		clock: systemClock,
-		onChange: refreshStatus,
+		onChange: refreshUI,
 		onTrigger(schedule, source) {
 			pi.sendMessage({
 				customType: "scheduler-trigger",
@@ -55,13 +120,17 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	const perform = (params: { action: "add" | "list" | "trigger" | "cancel"; every?: string; prompt?: string; id?: string }) => {
+	const perform = (params: { action: ScheduleAction; every?: string; prompt?: string; id?: string }) => {
 		if (params.action === "add") {
 			if (!params.every || !params.prompt) throw new Error("add requires every and prompt");
 			const item = scheduler.add(params.every, params.prompt);
 			return `Created ${item.id}: every ${item.every}; next ${formatTime(item.nextRunAt)}.`;
 		}
 		if (params.action === "list") return formatList(scheduler.list());
+		if (params.action === "clear") {
+			const count = scheduler.clear();
+			return count === 0 ? "No active schedules to clear." : `Cleared ${count} schedule${count === 1 ? "" : "s"}. Already queued prompts cannot be withdrawn.`;
+		}
 		if (!params.id) throw new Error(`${params.action} requires id`);
 		if (params.action === "cancel") {
 			if (!scheduler.cancel(params.id)) throw new Error(`unknown schedule: ${params.id}`);
@@ -77,7 +146,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		context = ctx;
-		refreshStatus();
+		refreshUI();
 	});
 	pi.on("message_start", async (event) => {
 		if (event.message.role !== "custom" || event.message.customType !== "scheduler-trigger") return;
@@ -91,14 +160,18 @@ export default function (pi: ExtensionAPI) {
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
 		scheduler.clear();
-		if (ctx.hasUI) ctx.ui.setStatus("scheduler", undefined);
+		if (ctx.hasUI) {
+			ctx.ui.setStatus(WIDGET_KEY, undefined);
+			if (ctx.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, undefined);
+		}
+		mountedWidget = undefined;
 		context = undefined;
 	});
 
 	pi.registerTool({
 		name: "schedule",
 		label: "Schedule",
-		description: "Manage session-scoped interval prompts for the main agent. Use add when the user asks the agent to check something repeatedly. Use trigger for one immediate check without changing the regular cadence. Schedules end with the current session.",
+		description: "Manage session-scoped interval prompts for the main agent. Use add when the user asks the agent to check something repeatedly, cancel for one schedule, and clear for all schedules. Use trigger for one immediate check without changing the regular cadence. Schedules end with the current session.",
 		parameters: Params,
 		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
 		async execute(_toolCallId, params) {
@@ -120,7 +193,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("schedule", {
-		description: "Add, list, trigger, or cancel session-scoped interval prompts",
+		description: "Add, list, trigger, cancel, or clear session-scoped interval prompts",
 		handler: async (args, ctx) => {
 			try {
 				const text = perform(parseCommand(args));

package/packages/scheduler/package.json

@@ -1,16 +1,31 @@
 {
   "name": "@maxiaochao/pi-scheduler",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Session-scoped interval prompts for Pi agents.",
   "type": "module",
-  "keywords": ["pi-package", "pi-extension", "scheduler"],
-  "files": ["extensions", "src", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "scheduler"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "docs",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
     "directory": "packages/scheduler"
   },
-  "pi": { "extensions": ["./extensions/scheduler.ts"] },
+  "pi": {
+    "extensions": [
+      "./extensions/scheduler.ts"
+    ]
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
@@ -21,5 +36,7 @@
     "test": "node --experimental-strip-types tests/scheduler-core.mjs && node --experimental-strip-types tests/scheduler-extension.mjs",
     "load-test": "pi -ne -e ./extensions/scheduler.ts"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/packages/scheduler/src/scheduler.ts

@@ -122,12 +122,14 @@ export class Scheduler {
 		return released;
 	}
 
-	clear(): void {
+	clear(): number {
+		const count = this.schedules.size;
 		for (const schedule of this.schedules.values()) {
 			if (schedule.timer !== undefined) this.clock.clearTimeout(schedule.timer);
 		}
 		this.schedules.clear();
-		this.onChange();
+		if (count > 0) this.onChange();
+		return count;
 	}
 
 	private arm(schedule: Schedule): void {

package/packages/scheduler/tests/scheduler-core.mjs

@@ -59,5 +59,12 @@ assert.equal(scheduler.trigger(added.id).ok, true, "a settled run releases a fol
 assert.equal(scheduler.cancel(added.id), true);
 assert.equal(scheduler.cancel(added.id), false);
 assert.equal(scheduler.list().length, 0);
+const firstClear = scheduler.add("1h", "Check build");
+const secondClear = scheduler.add("2h", "Check deployment");
+assert.notEqual(firstClear.id, secondClear.id);
+assert.equal(clock.timers.size, 2);
+assert.equal(scheduler.clear(), 2);
+assert.equal(clock.timers.size, 0, "clear cancels every timer");
+assert.equal(scheduler.clear(), 0);
 assert.ok(changes >= 5);
 console.log("Scheduler core tests passed");

package/packages/scheduler/tests/scheduler-extension.mjs

@@ -6,6 +6,9 @@ const commands = new Map();
 const messages = [];
 const statuses = new Map();
 let tool;
+const widgets = new Map([["herdr-subagents", { render: () => ["Herdr Fleet"] }]]);
+const widgetOptions = new Map([["herdr-subagents", { placement: "belowEditor" }]]);
+let renderRequests = 0;
 const originalSetTimeout = globalThis.setTimeout;
 const originalClearTimeout = globalThis.clearTimeout;
 let nextTimer = 1;
@@ -34,18 +37,34 @@ const notifications = [];
 const asAppMessage = ({ message }) => ({ ...message, role: "custom" });
 const context = {
 	hasUI: true,
+	mode: "tui",
 	ui: {
 		setStatus(key, value) { if (value === undefined) statuses.delete(key); else statuses.set(key, value); },
+		setWidget(key, value, options) {
+			if (value === undefined) {
+				widgets.delete(key);
+				widgetOptions.delete(key);
+			} else {
+				widgets.set(key, value({ requestRender() { renderRequests += 1; } }, { fg(_color, text) { return text; } }));
+				widgetOptions.set(key, options);
+			}
+		},
 		notify(message, level) { notifications.push({ message, level }); },
 	},
 };
 await handlers.get("session_start")({}, context);
 assert.ok(tool);
 assert.ok(commands.has("schedule"));
+assert.deepEqual(tool.parameters.properties.action.enum, ["add", "list", "trigger", "cancel", "clear"]);
 
 const add = await tool.execute("add", { action: "add", every: "1h", prompt: "Check CI" });
 assert.match(add.content[0].text, /Created schedule-1/);
-assert.match(statuses.get("scheduler"), /1 schedule/);
+assert.equal(statuses.has("scheduler"), false, "scheduler no longer competes for footer status space");
+assert.deepEqual(widgetOptions.get("scheduler"), { placement: "aboveEditor" });
+assert.deepEqual(widgetOptions.get("herdr-subagents"), { placement: "belowEditor" });
+assert.match(widgets.get("scheduler").render(100).join("\n"), /1 active schedule/);
+assert.match(widgets.get("scheduler").render(100).join("\n"), /schedule-1 · 1h · next/);
+assert.ok(widgets.has("herdr-subagents"), "Scheduler mounting preserves the Herdr Fleet widget");
 
 const trigger = await tool.execute("trigger", { action: "trigger", id: "schedule-1" });
 assert.match(trigger.content[0].text, /Triggered schedule-1/);
@@ -71,11 +90,28 @@ await handlers.get("message_start")({ message: asAppMessage(messages[2]) });
 await commands.get("schedule").handler("cancel schedule-1", context);
 assert.match(notifications.at(-1).message, /Already queued prompts cannot be withdrawn/);
 assert.equal(statuses.has("scheduler"), false);
-await tool.execute("shutdown-add", { action: "add", every: "2h", prompt: "Check deployment" });
+assert.equal(widgets.has("scheduler"), false, "removing the final schedule removes the multi-line widget");
+assert.ok(widgets.has("herdr-subagents"), "Scheduler cleanup preserves the Herdr Fleet widget");
+await tool.execute("clear-add-one", { action: "add", every: "2h", prompt: "Check deployment" });
+await tool.execute("clear-add-two", { action: "add", every: "3h", prompt: "Check release" });
+assert.match(widgets.get("scheduler").render(100).join("\n"), /2 active schedules/);
+assert.match(widgets.get("scheduler").render(100).join("\n"), /schedule-2/);
+assert.match(widgets.get("scheduler").render(100).join("\n"), /schedule-3/);
+await commands.get("schedule").handler("clear", context);
+assert.match(notifications.at(-1).message, /Cleared 2 schedules/);
+assert.equal(timers.size, 0, "clear cancels every active timer");
+assert.equal(widgets.has("scheduler"), false, "clear removes the widget");
+assert.ok(widgets.has("herdr-subagents"), "clear does not remove Herdr Fleet");
+const emptyClear = await tool.execute("empty-clear", { action: "clear" });
+assert.equal(emptyClear.content[0].text, "No active schedules to clear.");
+await tool.execute("shutdown-add", { action: "add", every: "4h", prompt: "Check shutdown" });
 assert.equal(timers.size, 1, "active schedule owns one timer");
 await handlers.get("session_shutdown")({}, context);
 assert.equal(statuses.has("scheduler"), false);
 assert.equal(timers.size, 0, "session shutdown clears active timers");
+assert.equal(widgets.has("scheduler"), false);
+assert.ok(widgets.has("herdr-subagents"), "Scheduler shutdown does not remove Herdr Fleet");
+assert.ok(renderRequests >= 4, "schedule changes request widget rerenders");
 globalThis.setTimeout = originalSetTimeout;
 globalThis.clearTimeout = originalClearTimeout;
 console.log("Scheduler extension integration tests passed");

package/packages/worktree/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-10-09 - v0.2.0
+
+- add current-session worktree switching for users, Agents, and SDK Harnesses
+- 新增 `/worktree start` 用户命令，在当前 Pi 界面中把持久会话 fork 并切换到 worktree。
+- 新增 `enter_worktree` Agent Tool 和 `pi-worktree/switch-request` Harness 协议。
+- 新增幂等的 `pi-worktree prepare --json` 机器接口，安全处理创建、挂载、复用、dirty 和 stale 状态。
+
 ## 2026-09-30 - v0.1.0
 
 - 将 pi-worktree CLI、bash completion 和 Pi skill 合并为可独立安装的子包。

package/packages/worktree/README.md

@@ -1,6 +1,6 @@
 # @maxiaochao/pi-worktree
 
-`pi-worktree` CLI 与配套 Pi skill。CLI 创建、检查和清理 Git worktree，并在隔离目录中启动 Pi。
+`pi-worktree` CLI、Pi Extension 与配套 skill。它既能启动独立 Pi，也能让用户在当前界面切换 worktree，或让 Agent 向 SDK Harness 发出结构化切换请求。
 
 ![Worktree 在真实临时 Git 仓库中的运行截图](docs/screenshot.png)
 
@@ -14,16 +14,28 @@
 
 ```bash
 pi-worktree start feature -p "implement the feature"
+pi-worktree prepare feature --json
 pi-worktree info feature
 pi-worktree out
 pi-worktree remove feature
 ```
 
-`start` 从当前分支创建或复用 `.worktrees/feature`，记录 base，并在该目录启动 Pi。
+`start` 从当前分支创建或复用 `.worktrees/feature`，记录 base，并在该目录启动 Pi。`prepare` 复用同一创建逻辑，但只返回目标，不启动嵌套 Pi。
+
+在交互式 Pi 中，用户可以保留当前界面和完整对话：
+
+```text
+/worktree start feature
+/worktree start feature --base main
+```
+
+命令会把当前持久会话 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` 完成切换。
 
 ## 安装
 
-完整工具包已经包含 CLI 和 skill：
+完整工具包已经包含 CLI、Extension 和 skill：
 
 ```bash
 pi install npm:@maxiaochao/pi-toolkit
@@ -50,6 +62,7 @@ pi update npm:@maxiaochao/pi-worktree # 更新独立子包
 
 ```bash
 pi-worktree start <name> [pi args...]
+pi-worktree prepare [--base <ref>] [--json] <name>
 pi-worktree list
 pi-worktree info <name>
 pi-worktree out
@@ -57,4 +70,6 @@ pi-worktree remove <name>
 pi-worktree prune
 ```
 
+`prepare --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

@@ -2,7 +2,7 @@
 
 ## 流程
 
-1. `npm --prefix packages/worktree test`：在临时 Git 仓库中使用假的 `pi` 命令运行 CLI。
+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。
@@ -11,6 +11,9 @@
 
 - `--help` 输出命令说明。
 - `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，并请求终止当前工具轮。
 - 假 Pi 收到正确工作目录和参数。
 - `list` 标记主 checkout 和子 worktree。
 - `info` 报告 clean、branch、base 和 ahead。
@@ -18,4 +21,4 @@
 
 ## 最近验证结果
 
-迁移基线要求全部 shell 断言通过，且 `npm pack --dry-run` 包含 `bin/`、`skills/` 和 `scripts/install.mjs`。
+验收要求全部 Node/shell 断言通过，Extension 能被 Pi 单独加载，且 `npm pack --dry-run` 包含 `bin/`、`extensions/`、`skills/` 和 `scripts/install.mjs`。

package/packages/worktree/bin/pi-worktree

@@ -4,6 +4,7 @@
 # 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 -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
@@ -18,7 +19,7 @@ else
   C_BOLD='' C_DIM='' C_RED='' C_GREEN='' C_YELLOW='' C_CYAN='' C_RESET=''
 fi
 
-ok()      { printf '%spi-worktree:%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
+ok()      { [[ "${QUIET:-0}" == 1 ]] || printf '%spi-worktree:%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
 warn()    { printf '%s⚠️  %s%s\n' "$C_YELLOW" "$C_RESET" "$*"; }
 die()     { printf '%spi-worktree: %s%s\n' "$C_RED" "$C_RESET" "$*" >&2; exit 1; }
 
@@ -40,6 +41,12 @@ in_linked_worktree() {
 
 wt_dir() { echo ".worktrees/$1"; }
 
+validate_name() {
+  local name="$1"
+  [[ "$name" != */* ]] || die "worktree name must not contain '/': $name"
+  git check-ref-format --branch "$name" >/dev/null 2>&1 || die "invalid worktree/branch name: $name"
+}
+
 # Best available base ref: current branch > HEAD (worktrees should branch
 # from where you actually are; a stale origin/main must not win)
 pick_base() {
@@ -63,12 +70,14 @@ resolve_base() {
 }
 
 ensure_gitignore() {
+  local root
+  root=$(main_checkout)
   # The trailing slash is load-bearing: `.worktrees/` is a directory-only
   # pattern, and git check-ignore cannot match it against a path that does not
   # exist yet — so `.worktrees` would look unignored on every first run and the
   # rule would be appended again.
-  if ! git check-ignore -q .worktrees/ 2>/dev/null; then
-    printf '.worktrees/\n' >> .gitignore
+  if ! git -C "$root" check-ignore -q .worktrees/ 2>/dev/null; then
+    printf '.worktrees/\n' >> "$root/.gitignore"
     ok "added .worktrees/ to .gitignore"
   fi
 }
@@ -226,55 +235,140 @@ cmd_remove() {
   fi
 }
 
-cd_wt() {
-  local name="$1"; shift
+prepare_wt() {
+  local name="$1"
   require_repo
+  validate_name "$name"
 
-  # Already isolated? Just launch pi here (superpowers Step 0).
+  # A linked checkout cannot safely create another `.worktrees/` tree relative
+  # to itself. Re-entering the active branch is nevertheless idempotent.
   if in_linked_worktree; then
-    ok "already in an isolated worktree ($(pwd)), launching pi here"
-    exec pi "$@"
+    local current_branch
+    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
+    return 0
   fi
 
-  local dir; dir="$(wt_dir "$name")"
+  local root worktrees_dir dir
+  root=$(main_checkout)
+  worktrees_dir="$root/.worktrees"
+  dir="$worktrees_dir/$name"
+  [[ ! -L "$worktrees_dir" ]] || die "$worktrees_dir must be a real directory, not a symlink"
+  [[ ! -L "$dir" ]] || die "$dir must not be a symlink"
 
   if [[ -d "$dir" ]]; then
     # Reuse: must be a registered worktree for this repo.
     # Skip the dirty-workspace prompt — the worktree already exists, nothing new to create.
+    local registered_path
+    registered_path=$(git worktree list --porcelain | sed -n 's/^worktree //p' | grep -Fx "$dir" || true)
+    [[ -n "$registered_path" ]] || die "$dir exists but is not a registered git worktree"
     git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || die "$dir exists but is not a git worktree"
+    [[ "$(git -C "$dir" rev-parse --path-format=absolute --git-common-dir)" == "$(git rev-parse --path-format=absolute --git-common-dir)" ]] \
+      || die "$dir belongs to a different git repository"
+    [[ "$(git -C "$dir" branch --show-current)" == "$name" ]] \
+      || die "$dir is not checked out on expected branch '$name'"
     ensure_gitignore
     ok "reusing existing worktree $dir"
+    PREPARE_STATUS="reused"
   else
-    # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
-    if ! 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
-
-    # After the check above, so the tool's own .gitignore edit is not reported
-    # as (and does not prompt about) the user's uncommitted work.
+    local target_abs registered_path
+    target_abs="$dir"
+    registered_path=$(git worktree list --porcelain | sed -n 's/^worktree //p' | grep -Fx "$target_abs" || true)
+    [[ -z "$registered_path" ]] \
+      || die "stale worktree registration for $dir; run 'pi-worktree prune' first"
     ensure_gitignore
-    mkdir -p .worktrees
+    mkdir -p "$worktrees_dir"
     # Reuse branch if it exists, else create it
     if git show-ref --verify --quiet "refs/heads/$name"; then
-      git worktree add "$dir" "$name"
+      if [[ "${QUIET:-0}" == 1 ]]; then
+        git worktree add "$dir" "$name" >/dev/null
+      else
+        git worktree add "$dir" "$name"
+      fi
       ok "checked out existing branch '$name'"
+      PREPARE_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")" \
         && git config "branch.$name.baseRef" main
     else
       local base; base=$(resolve_base)
-      git worktree add "$dir" -b "$name" "$base"
+      if [[ "${QUIET:-0}" == 1 ]]; then
+        git worktree add "$dir" -b "$name" "$base" >/dev/null
+      else
+        git worktree add "$dir" -b "$name" "$base"
+      fi
       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"
     fi
   fi
 
-  cd "$dir"
+  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
+}
+
+print_prepare_json() {
+  PI_WORKTREE_STATUS="$PREPARE_STATUS" \
+  PI_WORKTREE_PATH="$PREPARE_DIR" \
+  PI_WORKTREE_BRANCH="$PREPARE_BRANCH" \
+  PI_WORKTREE_DIRTY="$PREPARE_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() {
+  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>"
+        BASE_OVERRIDE="$1"; shift ;;
+      --json) json=1; QUIET=1; shift ;;
+      --*) die "unknown prepare option: $1" ;;
+      *) break ;;
+    esac
+  done
+  [[ $# -eq 1 ]] || die "usage: pi-worktree prepare [--base <ref>] [--json] <name>"
+  prepare_wt "$1"
+  if [[ "$json" == 1 ]]; then
+    print_prepare_json
+  else
+    ok "$PREPARE_STATUS worktree: $PREPARE_DIR ($PREPARE_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 "$@"
 }
 
@@ -285,6 +379,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

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 list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
+  local SUBS="start prepare 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=""
@@ -23,7 +23,7 @@ _pi_worktree() {
   fi
 
   case "$first" in
-    -i|--info|info|-r|--remove|remove|rm|start)
+    -i|--info|info|-r|--remove|remove|rm|start|prepare)
       # 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