@henryqw/pi-herdr-clone 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # `@henryqw/pi-herdr-clone`
 
-Pi extension that clones the current conversation path into a new Pi process in a new tab of the current Herdr workspace. Requires Pi Coding Agent 0.84.x (minimum 0.84.2) and a Pi session running inside Herdr.
+Pi extension that clones the current conversation path into a new Pi process in a new tab of the current Herdr workspace, or into a new Herdr Git worktree workspace. Requires Pi Coding Agent 0.84.x (minimum 0.84.2) and a Pi session running inside Herdr.
 
 ## Install
 
@@ -8,25 +8,37 @@ Pi extension that clones the current conversation path into a new Pi process in
 pi install npm:@henryqw/pi-herdr-clone
 ```
 
-Remove with:
+## Use
 
-```bash
-pi remove npm:@henryqw/pi-herdr-clone
-```
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `/clone-tab` | command | Clone the current conversation into a new tab of the current Herdr workspace. |
+| `/clone-worktree` | command | Clone the current conversation into a new Herdr Git worktree workspace. |
+
+Both commands wait until Pi is idle, then validate the current Herdr pane (`HERDR_ENV=1`, `HERDR_PANE_ID`), the persisted session file, and the current session leaf. They copy only the active root-to-leaf path into a new persisted session file: sibling branches are excluded and the original Pi session is not switched. Neither command has configuration.
+
+### `/clone-tab` behavior
 
-## `/clone-tab`
+1. Creates an unfocused Herdr tab in the current workspace with the current working directory.
+2. Starts Pi in the tab's root pane with `--session <absolute-clone-file>`.
+3. Focuses the new tab after Pi starts successfully.
 
-The command waits until Pi is idle, then:
+### `/clone-worktree` behavior
 
-1. Validates the current Herdr pane and resolves its live workspace.
-2. Copies only the current Pi session path into a new persisted session file. Sibling branches are excluded and the original Pi session is not switched.
-3. Creates an unfocused Herdr tab in that workspace with the current working directory.
-4. Starts Pi in the tab's root pane with `--session <absolute-clone-file>`.
-5. Focuses the new tab after Pi starts successfully.
+1. Creates a Git worktree-backed workspace with `herdr worktree create --workspace <current-workspace> --no-focus`; Herdr creates the branch from `HEAD` unless the name exists, checks out the worktree under its configured `worktrees.directory`, and opens it as a grouped workspace.
+2. Copies the active path into a clone session stamped with the fresh checkout path as its working directory.
+3. Starts Pi in the new workspace's root pane (whose shell runs inside the checkout) with `--session <absolute-clone-file>`.
+4. Focuses the new tab after Pi starts successfully.
 
-The command requires `HERDR_ENV=1`, `HERDR_PANE_ID`, an existing persisted session file, and a current session leaf. It has no configuration or worktree behavior.
+### Failure semantics
 
-If tab creation itself fails, the cloned session file is removed. If Herdr creates the tab but the response is incomplete, or once agent start is attempted, the tab and session file are retained because the launch outcome can be unknown; the error reports any known IDs for recovery. A later focus failure is shown as a warning and does not report the already-started clone as failed.
+If target creation fails outright, no clone session is kept or created. A killed or incomplete creation response is ambiguous because Herdr may have retained partial state; the error reports every identifier returned so far and suggests inspecting `herdr workspace list`. Once agent start is attempted, the target tab, panes, and session file are retained because the launch outcome can be unknown; the error reports any known IDs for recovery. A later focus failure is shown as a warning and does not report the already-started clone as failed.
+
+## Remove
+
+```bash
+pi remove npm:@henryqw/pi-herdr-clone
+```
 
 ## Development
 

package/extensions/clone-tab.ts

@@ -5,8 +5,21 @@ import { setTimeout as delay } from "node:timers/promises";
 import {
 	SessionManager,
 	type ExtensionAPI,
+	type ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
-import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode } from "@henryqw/pi-herdr";
+import {
+	createHerdrClient,
+	herdrCommandFailure,
+	hasHerdrErrorCode,
+	withWorktreeLock,
+	type HerdrClient,
+	type HerdrExecResult,
+} from "@henryqw/pi-herdr";
+
+type WorkspaceInfo = {
+	workspace_id?: unknown;
+	worktree?: { checkout_path?: unknown } | null;
+};
 
 const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
 
@@ -15,6 +28,112 @@ function requiredString(value: unknown, label: string): string {
 	return value;
 }
 
+type SourceContext = {
+	sessionFile: string;
+	leafId: string;
+	workspaceId: string;
+	checkout: string | undefined;
+};
+
+async function resolveSource(
+	commandName: string,
+	herdr: HerdrClient<{ cwd: string }>,
+	ctx: ExtensionCommandContext,
+): Promise<SourceContext> {
+	if (process.env.HERDR_ENV !== "1") {
+		throw new Error(`/${commandName} requires the current Pi session inside Herdr (HERDR_ENV=1).`);
+	}
+	const requestedPaneId = requiredString(process.env.HERDR_PANE_ID, "HERDR_PANE_ID");
+	const currentSessionFile = requiredString(
+		ctx.sessionManager.getSessionFile(),
+		"Persisted Pi session file",
+	);
+	const leafId = requiredString(ctx.sessionManager.getLeafId(), "Current Pi session leaf");
+	const sessionFile = resolve(currentSessionFile);
+	let sourceStat;
+	try {
+		sourceStat = await stat(sessionFile);
+	} catch (error) {
+		throw new Error(`Persisted Pi session file does not exist: ${sessionFile}`, { cause: error });
+	}
+	if (!sourceStat.isFile()) throw new Error(`Persisted Pi session path is not a file: ${sessionFile}`);
+
+	const paneResponse = await herdr.json(["pane", "get", requestedPaneId], { cwd: ctx.cwd });
+	const pane = (paneResponse as { result?: { pane?: { pane_id?: unknown; workspace_id?: unknown } } }).result?.pane;
+	requiredString(pane?.pane_id, "Herdr pane response pane_id");
+	const workspaceId = requiredString(pane?.workspace_id, "Herdr pane response workspace_id");
+	const workspaceResponse = await herdr.json(["workspace", "get", workspaceId], { cwd: ctx.cwd });
+	const workspace = (workspaceResponse as { result?: { workspace?: WorkspaceInfo } }).result?.workspace;
+	if (requiredString(workspace?.workspace_id, "Herdr workspace response workspace_id") !== workspaceId) {
+		throw new Error(`Herdr workspace response did not match ${workspaceId}.`);
+	}
+	const checkout = workspace?.worktree == null
+		? undefined
+		: requiredString(workspace.worktree.checkout_path, "Herdr workspace response checkout_path");
+	return { sessionFile, leafId, workspaceId, checkout };
+}
+
+async function createBranchedClone(
+	ctx: ExtensionCommandContext,
+	source: SourceContext,
+	cwd: string,
+): Promise<string> {
+	const session = SessionManager.open(source.sessionFile, ctx.sessionManager.getSessionDir(), cwd);
+	const createdClone = session.createBranchedSession(source.leafId);
+	if (!createdClone) throw new Error("Pi did not create a persisted clone session file.");
+	const cloneFile = resolve(createdClone);
+	let cloneStat;
+	try {
+		cloneStat = await stat(cloneFile);
+	} catch (error) {
+		throw new Error(`Pi clone session file was not created: ${cloneFile}`, { cause: error });
+	}
+	if (!cloneStat.isFile()) throw new Error(`Pi clone session path is not a file: ${cloneFile}`);
+	return cloneFile;
+}
+
+async function discardCloneOrAggregate(cloneFile: string, error: Error): Promise<never> {
+	try {
+		await unlink(cloneFile);
+	} catch (cleanupError) {
+		throw new AggregateError(
+			[error, cleanupError],
+			`${error.message} Clone cleanup also failed for ${cloneFile}: ${errorMessage(cleanupError)}`,
+		);
+	}
+	throw error;
+}
+
+async function launchCloneAgent(
+	herdr: HerdrClient<{ cwd: string }>,
+	ctx: ExtensionCommandContext,
+	rootPaneId: string,
+	cloneFile: string,
+	retained: string,
+): Promise<string> {
+	const agentName = `clone-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
+	const startArgs = [
+		"agent", "start", agentName, "--kind", "pi", "--pane", rootPaneId,
+		"--", "--session", cloneFile,
+	];
+	try {
+		for (let attempt = 1; attempt <= 5; attempt += 1) {
+			const result = await herdr.exec(startArgs, { cwd: ctx.cwd });
+			if (result.code === 0 && !result.killed) return agentName;
+			if (!hasHerdrErrorCode(result, "agent_pane_busy") || attempt === 5) {
+				throw new Error(herdrCommandFailure(startArgs, result));
+			}
+			await delay(250);
+		}
+		throw new Error("Herdr agent start retry loop exited unexpectedly.");
+	} catch (error) {
+		throw new Error(
+			`Clone launch could not be confirmed after starting agent ${agentName}; retained ${retained}: ${errorMessage(error)}`,
+			{ cause: error },
+		);
+	}
+}
+
 export default function herdrCloneExtension(pi: ExtensionAPI): void {
 	const herdr = createHerdrClient<{ cwd: string }>((command, args, options) =>
 		pi.exec(command, [...args], options));
@@ -23,57 +142,17 @@ export default function herdrCloneExtension(pi: ExtensionAPI): void {
 		description: "Clone the current conversation path into a new Herdr tab",
 		handler: async (_args, ctx) => {
 			await ctx.waitForIdle();
-
-			if (process.env.HERDR_ENV !== "1") {
-				throw new Error("/clone-tab requires the current Pi session inside Herdr (HERDR_ENV=1).");
-			}
-			const requestedPaneId = requiredString(process.env.HERDR_PANE_ID, "HERDR_PANE_ID");
-			const currentSessionFile = requiredString(
-				ctx.sessionManager.getSessionFile(),
-				"Persisted Pi session file",
-			);
-			const leafId = requiredString(ctx.sessionManager.getLeafId(), "Current Pi session leaf");
-			const sessionFile = resolve(currentSessionFile);
-			let sourceStat;
-			try {
-				sourceStat = await stat(sessionFile);
-			} catch (error) {
-				throw new Error(`Persisted Pi session file does not exist: ${sessionFile}`, { cause: error });
-			}
-			if (!sourceStat.isFile()) throw new Error(`Persisted Pi session path is not a file: ${sessionFile}`);
-
-			const paneResponse = await herdr.json(["pane", "get", requestedPaneId], { cwd: ctx.cwd });
-			const pane = (paneResponse as { result?: { pane?: { pane_id?: unknown; workspace_id?: unknown } } }).result?.pane;
-			requiredString(pane?.pane_id, "Herdr pane response pane_id");
-			const workspaceId = requiredString(pane?.workspace_id, "Herdr pane response workspace_id");
-
-			const session = SessionManager.open(sessionFile, ctx.sessionManager.getSessionDir(), ctx.cwd);
-			const createdClone = session.createBranchedSession(leafId);
-			if (!createdClone) throw new Error("Pi did not create a persisted clone session file.");
-			const cloneFile = resolve(createdClone);
-			let cloneStat;
-			try {
-				cloneStat = await stat(cloneFile);
-			} catch (error) {
-				throw new Error(`Pi clone session file was not created: ${cloneFile}`, { cause: error });
-			}
-			if (!cloneStat.isFile()) throw new Error(`Pi clone session path is not a file: ${cloneFile}`);
-
-			const tabCreateArgs = ["tab", "create", "--workspace", workspaceId, "--cwd", ctx.cwd, "--no-focus"] as const;
-			const createdTab = await herdr.exec(tabCreateArgs, { cwd: ctx.cwd });
-			if (createdTab.code !== 0 || createdTab.killed) {
-				const createError = new Error(herdrCommandFailure(tabCreateArgs, createdTab));
-				try {
-					await unlink(cloneFile);
-				} catch (cleanupError) {
-					throw new AggregateError(
-						[createError, cleanupError],
-						`${createError.message} Clone cleanup also failed for ${cloneFile}: ${errorMessage(cleanupError)}`,
-					);
+			const source = await resolveSource("clone-tab", herdr, ctx);
+			const mutate = async (): Promise<{ createdTab: HerdrExecResult; cloneFile: string }> => {
+				const cloneFile = await createBranchedClone(ctx, source, ctx.cwd);
+				const tabCreateArgs = ["tab", "create", "--workspace", source.workspaceId, "--cwd", ctx.cwd, "--no-focus"] as const;
+				const createdTab = await herdr.exec(tabCreateArgs, { cwd: ctx.cwd });
+				if (createdTab.code !== 0 || createdTab.killed) {
+					await discardCloneOrAggregate(cloneFile, new Error(herdrCommandFailure(tabCreateArgs, createdTab)));
 				}
-				throw createError;
-			}
-
+				return { createdTab, cloneFile };
+			};
+			const { createdTab, cloneFile } = source.checkout ? await withWorktreeLock(source.checkout, mutate) : await mutate();
 			let tabId: string | undefined;
 			let rootPaneId: string | undefined;
 			try {
@@ -92,38 +171,111 @@ export default function herdrCloneExtension(pi: ExtensionAPI): void {
 					{ cause: error },
 				);
 			}
-			const agentName = `clone-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
-			const startArgs = [
-				"agent", "start", agentName, "--kind", "pi", "--pane", rootPaneId,
-				"--", "--session", cloneFile,
-			];
+			const agentName = await launchCloneAgent(herdr, ctx, rootPaneId!, cloneFile, `Herdr tab ${tabId}, root pane ${rootPaneId}, and session ${cloneFile}`);
+
 			try {
-				for (let attempt = 1; attempt <= 5; attempt += 1) {
-					const result = await herdr.exec(startArgs, { cwd: ctx.cwd });
-					if (result.code === 0 && !result.killed) break;
-					if (!hasHerdrErrorCode(result, "agent_pane_busy") || attempt === 5) {
-						throw new Error(herdrCommandFailure(startArgs, result));
-					}
-					await delay(250);
+				await herdr.run(["tab", "focus", tabId!], { cwd: ctx.cwd });
+			} catch (error) {
+				ctx.ui.notify(
+					`Clone agent ${agentName} started in Herdr tab ${tabId} (root pane ${rootPaneId}), but focus failed: ${errorMessage(error)}`,
+					"warning",
+				);
+				return;
+			}
+			ctx.ui.notify(
+				`Cloned current conversation into Herdr tab ${tabId} (root pane ${rootPaneId}, agent ${agentName}).`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("clone-worktree", {
+		description: "Clone the current conversation into Pi in a new Herdr Git worktree",
+		handler: async (_args, ctx) => {
+			await ctx.waitForIdle();
+			const source = await resolveSource("clone-worktree", herdr, ctx);
+
+			// Create the worktree before the clone so the session header can be
+			// stamped with the fresh checkout cwd. A killed or incomplete create is
+			// ambiguous: Herdr may have retained partial worktree state.
+			const worktreeCreateArgs = ["worktree", "create", "--workspace", source.workspaceId, "--no-focus"] as const;
+			const createdWorktree = await herdr.exec(worktreeCreateArgs, { cwd: ctx.cwd });
+			if (createdWorktree.code !== 0 && !createdWorktree.killed) {
+				throw new Error(herdrCommandFailure(worktreeCreateArgs, createdWorktree));
+			}
+
+			let workspaceId: string | undefined;
+			let tabId: string | undefined;
+			let rootPaneId: string | undefined;
+			let checkoutPath: string | undefined;
+			try {
+				const response: unknown = JSON.parse(createdWorktree.stdout);
+				if (!response || typeof response !== "object" || Array.isArray(response)) {
+					throw new Error("Herdr worktree create returned invalid JSON");
+				}
+				const result = (response as {
+					result?: {
+						workspace?: { workspace_id?: unknown };
+						tab?: { tab_id?: unknown };
+						root_pane?: { pane_id?: unknown };
+						worktree?: { checkout_path?: unknown };
+					};
+				}).result;
+				// Collect every returned identifier before validating so recovery
+				// keeps all known IDs even when an earlier field is missing.
+				workspaceId = typeof result?.workspace?.workspace_id === "string" ? result.workspace.workspace_id : undefined;
+				tabId = typeof result?.tab?.tab_id === "string" ? result.tab.tab_id : undefined;
+				rootPaneId = typeof result?.root_pane?.pane_id === "string" ? result.root_pane.pane_id : undefined;
+				checkoutPath = typeof result?.worktree?.checkout_path === "string" ? result.worktree.checkout_path : undefined;
+				const missing = [
+					[workspaceId, "workspace_id"],
+					[tabId, "tab_id"],
+					[rootPaneId, "root_pane.pane_id"],
+					[checkoutPath, "worktree.checkout_path"],
+				].filter(([value]) => !value).map(([, label]) => label);
+				if (missing.length > 0) {
+					throw new Error(`Herdr worktree create response is missing ${missing.join(", ")}.`);
 				}
+			} catch (error) {
+				const known = [
+					workspaceId && `workspace ${workspaceId}`,
+					tabId && `tab ${tabId}`,
+					rootPaneId && `root pane ${rootPaneId}`,
+					checkoutPath && `checkout ${checkoutPath}`,
+				].filter(Boolean).join(", ");
+				throw new Error(
+					`Clone could not be confirmed after creating a Herdr worktree${known ? ` (${known})` : ""}; Herdr may have retained a partial worktree workspace, inspect herdr workspace list: ${errorMessage(error)}`,
+					{ cause: error },
+				);
+			}
+
+			let cloneFile: string;
+			try {
+				cloneFile = source.checkout
+					? await withWorktreeLock(source.checkout, () => createBranchedClone(ctx, source, checkoutPath!))
+					: await createBranchedClone(ctx, source, checkoutPath!);
 			} catch (error) {
 				throw new Error(
-					`Clone launch could not be confirmed after starting agent ${agentName}; retained Herdr tab ${tabId}, root pane ${rootPaneId}, and session ${cloneFile}: ${errorMessage(error)}`,
+					`Clone session could not be created for Herdr worktree workspace ${workspaceId} (tab ${tabId}, checkout ${checkoutPath}); retained worktree without a clone session: ${errorMessage(error)}`,
 					{ cause: error },
 				);
 			}
+			const agentName = await launchCloneAgent(
+				herdr, ctx, rootPaneId!, cloneFile,
+				`Herdr workspace ${workspaceId}, tab ${tabId}, root pane ${rootPaneId}, and session ${cloneFile}`,
+			);
 
 			try {
-				await herdr.run(["tab", "focus", tabId], { cwd: ctx.cwd });
+				await herdr.run(["tab", "focus", tabId!], { cwd: ctx.cwd });
 			} catch (error) {
 				ctx.ui.notify(
-					`Clone agent ${agentName} started in Herdr tab ${tabId} (root pane ${rootPaneId}), but focus failed: ${errorMessage(error)}`,
+					`Clone agent ${agentName} started in Herdr worktree workspace ${workspaceId} (tab ${tabId}, checkout ${checkoutPath}), but focus failed: ${errorMessage(error)}`,
 					"warning",
 				);
 				return;
 			}
 			ctx.ui.notify(
-				`Cloned current conversation into Herdr tab ${tabId} (root pane ${rootPaneId}, agent ${agentName}).`,
+				`Cloned current conversation into Herdr worktree workspace ${workspaceId} (tab ${tabId}, checkout ${checkoutPath}, agent ${agentName}).`,
 				"info",
 			);
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-herdr-clone",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Clone the current Pi conversation path into a new Herdr tab.",
   "keywords": [
     "pi-package",
@@ -28,7 +28,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.2"
   },
   "dependencies": {
-    "@henryqw/pi-herdr": "^0.1.1"
+    "@henryqw/pi-herdr": "^0.2.0"
   },
   "repository": {
     "type": "git",