@pify/worktree 0.2.0 → 0.3.0

package/README.md

@@ -10,9 +10,25 @@ Part of the [Pify suite](https://github.com/pifydev). Install with [`pify instal
 - **`worktree_list`** — every worktree with branch, `primary`/`dirty`/`locked`/`prunable` flags.
 - **`worktree_merge`** — with your confirmation: merges the worktree's branch into the primary branch, then removes the worktree. **Conflicting merges abort cleanly** — the primary is restored, nothing half-merged.
 - **`worktree_remove`** — refuses the primary worktree, the one the session runs in, and locked ones outright; uncommitted changes need your explicit confirmation (fail-closed without a UI). The branch is always kept.
-- **`/worktree`** — `list` / `create <branch> [base]` / `remove <target>` / `merge <branch>` / `prune` for humans. Everything after the route is taken whole, so paths with spaces work (v0.2).
+- **`/worktree enter <target>` / `/worktree exit`** (v0.3) — take the conversation into a worktree and back out again. See below.
+- **`/worktree`** — `list` / `create <branch> [base] [--enter]` / `enter <target>` / `exit` / `remove <target>` / `merge <branch>` / `prune` for humans. Everything after the route is taken whole, so paths with spaces work (v0.2).
 - **Targets resolve the way you'd name them** (v0.2): a branch, a path, a directory name, or — for worktrees created by `isolation: "worktree"` in `@pify/subagent`/`swarm`/`workflow` — the agent slug alone (`worker-1` finds branch `agent/worker-1`).
 
+## Entering a worktree (v0.3)
+
+Creating a worktree used to be half the job. pi binds `read`, `edit`, `bash` and `@` completion to the session's working directory, and a session cannot change its own — so the worktree existed, and everything you had just discussed stayed in the terminal you were in.
+
+`/worktree enter <branch|path>` forks the current session into the worktree and switches to it. The conversation comes along, the tools rebind, and the branch you were reading about is the branch you are now in. `/worktree exit` switches back to the session you came from; `/worktree create <branch> --enter` does both in one step.
+
+Two things it will refuse, and why:
+
+- **`--no-session`** — entering forks a session file, so there has to be one.
+- **A session pi hasn't written yet** — pi keeps a session in memory until the agent has replied, so a brand-new session has nothing on disk to fork. Ask something first, or open the worktree in its own pi.
+
+Only you can do this: session switching is a user command, so the agent cannot move itself. `worktree_create` says so in its result rather than implying the tools followed it.
+
+The mechanism is [FradSer/pi-packages](https://github.com/FradSer/pi-packages)' — `utils` found it first.
+
 ## Safety model
 
 Every git call is an `execFile` argv — no shell, no string interpolation, ever. Branch names are validated against a restricted grammar (no leading `-`, no `..`, no ref tricks) before reaching git. Removal risk is assessed (primary / current-session / locked / dirty) before anything happens — and containment is checked on directory boundaries (v0.2), so sitting in `feature-2` no longer blocks removing `feature`, and integration tests run the whole create→merge→remove and conflict-abort flows against real repositories.

package/extensions/worktree.ts

@@ -16,7 +16,14 @@
  * (@narumitw/pi-worktree), merge-back cleanup flow (rielj/pi-git-worktrees,
  * minus the tmux), worktree-as-concurrency-safety framing (pi-napkin).
  */
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  SessionManager,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { existsSync, statSync } from "node:fs";
+
 import { Type } from "typebox";
 
 import {
@@ -29,8 +36,17 @@ import {
   repoToplevel,
 } from "../src/git.ts";
 import { assessRemoval, formatWorktrees, resolveWorktree, validBranchName } from "../src/parse.ts";
+import {
+  WORKTREE_SESSION_ENTRY,
+  enteredNote,
+  exitNote,
+  planEnter,
+  readWorktreeSession,
+  type WorktreeSession,
+} from "../src/enter.ts";
 
 type UiContext = ExtensionContext;
+type CommandContext = ExtensionCommandContext;
 
 export default function worktree(pi: ExtensionAPI) {
   function requireRepo(ctx: UiContext): string {
@@ -102,6 +118,81 @@ export default function worktree(pi: ExtensionAPI) {
     };
   }
 
+  /**
+   * Enter a worktree by forking this session into it. pi binds its built-in
+   * tools to the session cwd and a session cannot change its own, so the only
+   * way to take the conversation along is a replacement session.
+   */
+  async function enterWorktree(ctx: CommandContext, wanted: string, created = false): Promise<void> {
+    requireRepo(ctx);
+    if (typeof ctx.switchSession !== "function") {
+      ctx.ui.notify("This pi build cannot switch sessions, so /worktree enter is unavailable.", "error");
+      return;
+    }
+
+    const match = resolveWorktree(listWorktrees(ctx.cwd), wanted);
+    const file = ctx.sessionManager.getSessionFile() ?? null;
+    const plan = planEnter(
+      ctx.cwd,
+      { file, onDisk: Boolean(file && existsSync(file) && statSync(file).size > 0) },
+      match ? { path: match.path, branch: match.branch } : null,
+    );
+    if ("kind" in plan) {
+      ctx.ui.notify(plan.message, plan.kind === "already-here" ? "info" : "warning");
+      return;
+    }
+
+    const state: WorktreeSession = {
+      path: plan.target.path,
+      branch: plan.target.branch,
+      parentSession: plan.parentSession,
+      created,
+      enteredAt: Date.now(),
+    };
+
+    try {
+      // forkFrom copies the conversation into a session file rooted at the
+      // worktree; switching to it is what rebinds read/edit/bash and @.
+      const replacement = SessionManager.forkFrom(plan.parentSession, state.path);
+      const replacementFile = replacement.getSessionFile();
+      if (!replacementFile) throw new Error("the forked session has no file");
+      replacement.appendCustomEntry(WORKTREE_SESSION_ENTRY, state);
+      const { cancelled } = await ctx.switchSession(replacementFile, {
+        withSession: async (next) => {
+          next.ui.notify(enteredNote(state), "info");
+        },
+      });
+      if (cancelled) ctx.ui.notify("Staying put — the session switch was cancelled.", "info");
+    } catch (err) {
+      ctx.ui.notify(`Could not enter: ${err instanceof Error ? err.message : String(err)}`, "error");
+    }
+  }
+
+  /** Return to the session this one was forked from. */
+  async function exitWorktree(ctx: CommandContext): Promise<void> {
+    const state = readWorktreeSession(ctx.sessionManager.getBranch() as never);
+    if (!state) {
+      ctx.ui.notify("This session was not entered with /worktree enter.", "warning");
+      return;
+    }
+    if (!state.parentSession || !existsSync(state.parentSession)) {
+      ctx.ui.notify(
+        "The session this was forked from is gone, so there is nowhere to go back to. This session stays in the worktree.",
+        "warning",
+      );
+      return;
+    }
+    try {
+      await ctx.switchSession(state.parentSession, {
+        withSession: async (next) => {
+          next.ui.notify(exitNote(state), "info");
+        },
+      });
+    } catch (err) {
+      ctx.ui.notify(`Could not exit: ${err instanceof Error ? err.message : String(err)}`, "error");
+    }
+  }
+
   // ── Tools ────────────────────────────────────────────────────────────
 
   pi.registerTool({
@@ -146,7 +237,10 @@ export default function worktree(pi: ExtensionAPI) {
             type: "text",
             text: [
               `Worktree ready at ${result.path} (${result.message} base: ${result.base}).`,
-              `Open a pi session there with: cd "${result.path}" && pi`,
+              // Only the user can switch sessions, so tell them how rather than
+              // implying this session moved.
+              `Your tools still point at the main checkout. The user can run /worktree enter ${branch} to ` +
+                `bring this conversation into the worktree, or open it separately with: cd "${result.path}" && pi`,
               `When the work is done: worktree_merge branch="${branch}" merges it back and cleans up.`,
             ].join("\n"),
           },
@@ -229,7 +323,8 @@ export default function worktree(pi: ExtensionAPI) {
   // ── Command ──────────────────────────────────────────────────────────
 
   pi.registerCommand("worktree", {
-    description: "Manage git worktrees: /worktree [create <branch> [base] | remove <target> | merge <branch> | prune]",
+    description:
+      "Manage git worktrees: /worktree [create <branch> [base] [--enter] | enter <target> | exit | remove <target> | merge <branch> | prune]",
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
       const text = (args ?? "").trim();
@@ -244,9 +339,11 @@ export default function worktree(pi: ExtensionAPI) {
             return;
           }
           case "create": {
-            const [arg, base] = rest.split(/\s+/);
+            const words = rest.split(/\s+/).filter(Boolean);
+            const enterAfter = words.includes("--enter");
+            const [arg, base] = words.filter((w) => w !== "--enter");
             if (!arg) {
-              ctx.ui.notify("Usage: /worktree create <branch> [base]", "warning");
+              ctx.ui.notify("Usage: /worktree create <branch> [base] [--enter]", "warning");
               return;
             }
             if (!validBranchName(arg)) {
@@ -254,9 +351,19 @@ export default function worktree(pi: ExtensionAPI) {
               return;
             }
             const result = createWorktree(ctx.cwd, arg, base);
+            if (!result.ok) {
+              ctx.ui.notify(result.message, "error");
+              return;
+            }
+            if (enterAfter) {
+              ctx.ui.notify(`Worktree ready: ${result.path}`, "info");
+              await enterWorktree(ctx, arg, true);
+              return;
+            }
             ctx.ui.notify(
-              result.ok ? `Worktree ready: ${result.path}\nOpen with: cd "${result.path}" && pi` : result.message,
-              result.ok ? "info" : "error",
+              `Worktree ready: ${result.path}\n` +
+                `/worktree enter ${arg} takes this conversation there, or open it separately with: cd "${result.path}" && pi`,
+              "info",
             );
             return;
           }
@@ -287,6 +394,18 @@ export default function worktree(pi: ExtensionAPI) {
             ctx.ui.notify(result.ok ? `Removed ${target.path}.` : result.output, result.ok ? "info" : "error");
             return;
           }
+          case "enter": {
+            if (!rest) {
+              ctx.ui.notify("Usage: /worktree enter <branch|path>", "warning");
+              return;
+            }
+            await enterWorktree(ctx, rest);
+            return;
+          }
+          case "exit": {
+            await exitWorktree(ctx);
+            return;
+          }
           case "merge": {
             if (!rest) {
               ctx.ui.notify("Usage: /worktree merge <branch>", "warning");
@@ -303,7 +422,7 @@ export default function worktree(pi: ExtensionAPI) {
           }
           default:
             ctx.ui.notify(
-              `Unknown route "${route}". Usage: /worktree [list | create <branch> [base] | remove <target> | merge <branch> | prune]`,
+              `Unknown route "${route}". Usage: /worktree [list | create <branch> [base] [--enter] | enter <target> | exit | remove <target> | merge <branch> | prune]`,
               "warning",
             );
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/worktree",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Safe git-worktree management for pi: create/list/merge/remove with safety rails, no shell interpolation, Windows-first, zero tmux",
   "keywords": [
     "pi-package",
@@ -57,7 +57,7 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
     "@types/node": "^22.10.2",
     "typebox": "^1.1.38",
     "typescript": "^5.7.2"

package/skills/worktree/SKILL.md

@@ -21,13 +21,16 @@ edits.
 
 1. `worktree_list` — see what exists (primary, dirty, locked flags).
 2. `worktree_create branch="feature-x"` — new branch from HEAD (or pass
-   `base`), checked out under `~/.worktrees/<repo>/`. Tell the user the
-   path — they can run pi there (`cd <path> && pi`).
-3. Work happens in the worktree; commit there.
-4. `worktree_merge branch="feature-x"` — asks the user, merges into the
+   `base`), checked out under `~/.worktrees/<repo>/`.
+3. Say where the worktree is and that your tools still point at the main
+   checkout. Only the user can move this session: `/worktree enter feature-x`
+   brings the conversation into the worktree, `/worktree exit` returns.
+   Otherwise they can open it separately with `cd <path> && pi`.
+4. Work happens in the worktree; commit there.
+5. `worktree_merge branch="feature-x"` — asks the user, merges into the
    primary branch, removes the worktree. Conflicts abort cleanly; nothing
    is left half-merged.
-5. `worktree_remove target="feature-x"` — abandon instead; dirty worktrees
+6. `worktree_remove target="feature-x"` — abandon instead; dirty worktrees
    need the user's confirmation, the branch is always kept.
 
 ## Rules
@@ -35,3 +38,5 @@ edits.
 - Never try to bypass a refusal (primary/current/locked worktrees).
 - Commit inside the worktree before merging — both sides must be clean.
 - One branch per worktree; a branch already checked out elsewhere refuses.
+- Do not claim you are "now working in" a worktree you created. Until the user
+  enters it, every path you read and edit is still the main checkout.

package/src/enter.ts

@@ -0,0 +1,138 @@
+/**
+ * Entering a worktree without losing the conversation.
+ *
+ * Creating a worktree was only ever half the job: pi binds `read`, `edit`,
+ * `bash` and `@` completion to the session's cwd, and a session cannot change
+ * its own cwd. So until now this package could hand you a path and a
+ * suggestion to open a second terminal — and everything you had discussed
+ * stayed in the terminal you left.
+ *
+ * The way through is a replacement session: fork the current session file
+ * into the worktree and switch to it. The conversation comes along, the tools
+ * rebind, and the branch you were reading about is the branch you are now in.
+ * (Mechanism from FradSer/pi-packages' utils, which found it first.)
+ *
+ * Pure helpers only — the switch itself needs the host and lives in the
+ * extension.
+ */
+
+export const WORKTREE_SESSION_ENTRY = "pify-worktree-session";
+
+export interface WorktreeSession {
+  /** Absolute path of the worktree this session is rooted in. */
+  path: string;
+  branch: string | null;
+  /** Session file we forked from, so ExitWorktree knows where to go back. */
+  parentSession: string;
+  /** True when entering created the worktree, so leaving may offer to remove it. */
+  created: boolean;
+  enteredAt: number;
+}
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+/** The worktree state this session was entered with, if any. */
+export function readWorktreeSession(entries: readonly BranchEntryLike[]): WorktreeSession | null {
+  let state: WorktreeSession | null = null;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== WORKTREE_SESSION_ENTRY) continue;
+    const data = entry.data as Partial<WorktreeSession> | null;
+    if (!data || typeof data.path !== "string" || !data.path) continue;
+    state = {
+      path: data.path,
+      branch: typeof data.branch === "string" ? data.branch : null,
+      parentSession: typeof data.parentSession === "string" ? data.parentSession : "",
+      created: data.created === true,
+      enteredAt: typeof data.enteredAt === "number" ? data.enteredAt : 0,
+    };
+  }
+  return state;
+}
+
+export type EnterProblem =
+  | { kind: "no-session"; message: string }
+  | { kind: "unwritten"; message: string }
+  | { kind: "not-found"; message: string }
+  | { kind: "already-here"; message: string };
+
+export interface EnterPlan {
+  target: { path: string; branch: string | null };
+  parentSession: string;
+}
+
+/** What we know about the session we would be forking. */
+export interface ParentSession {
+  file: string | null;
+  /**
+   * Whether that file exists with entries in it. pi keeps a session in memory
+   * until the first assistant message, so a brand-new session has a name on
+   * disk and nothing behind it — and forking from it throws.
+   */
+  onDisk: boolean;
+}
+
+function samePath(a: string, b: string): boolean {
+  return a.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase() ===
+    b.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+}
+
+/**
+ * Decide whether entering is possible before anything is forked. Each refusal
+ * names which of the four things went wrong, because the fixes differ: start a
+ * persisted session, say something first, create the worktree, or do nothing
+ * at all.
+ */
+export function planEnter(
+  cwd: string,
+  parent: ParentSession,
+  target: { path: string; branch: string | null } | null,
+): EnterPlan | EnterProblem {
+  if (!parent.file) {
+    return {
+      kind: "no-session",
+      message:
+        "Entering a worktree forks this session, so it needs a persisted one. Start pi without --no-session.",
+    };
+  }
+  if (!parent.onDisk) {
+    return {
+      kind: "unwritten",
+      message:
+        "This session has not been written to disk yet — pi saves it once the agent has replied, and there is " +
+        "nothing to carry across until then. Ask something first, or open the worktree in its own pi.",
+    };
+  }
+  if (!target) {
+    return {
+      kind: "not-found",
+      message: "No worktree matches that. /worktree list shows them; /worktree create <branch> makes one.",
+    };
+  }
+  if (samePath(cwd, target.path)) {
+    return { kind: "already-here", message: "This session is already rooted in that worktree." };
+  }
+  return { target, parentSession: parent.file };
+}
+
+export function enteredNote(session: WorktreeSession): string {
+  const branch = session.branch ? ` on ${session.branch}` : "";
+  return [
+    `Entered worktree ${session.path}${branch}.`,
+    "read, edit, bash and @ completion are rooted here now; the conversation came with you.",
+    "/worktree exit returns to the session you came from.",
+  ].join(" ");
+}
+
+export function exitNote(session: WorktreeSession): string {
+  return [
+    `Left the worktree at ${session.path}.`,
+    session.created
+      ? "It was created by entering, and is still there — /worktree remove drops it, worktree_merge merges it back."
+      : "It is untouched.",
+  ].join(" ");
+}