@pify/worktree 0.2.0 → 0.3.1

package/README.md

@@ -1,25 +1,84 @@
 # @pify/worktree
 
-Safe git-worktree management for [pi](https://github.com/earendil-works/pi) — isolated workspaces for parallel or risky changes, with safety rails everywhere and a clean merge-back flow. Windows-first: no tmux, no daemons, no shell interpolation.
+Safe git-worktree management for [pi](https://github.com/earendil-works/pi) — isolated workspaces for parallel or risky changes, with safety rails on every destructive path and a clean merge-back flow. Windows-first: no tmux, no daemons, no shell interpolation.
 
 Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install worktree`](https://github.com/pifydev/cli) or `pi install npm:@pify/worktree`.
 
-## What it does
+## Why
 
-- **`worktree_create`** — new branch (or existing unoccupied one) checked out under `~/.worktrees/<repo>/<branch>`; reports the base commit and how to open pi there. The main checkout stays untouched.
-- **`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).
-- **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`).
+Two changes that touch the same files cannot share one checkout. The usual workarounds — stashing, branching back and forth, or just being careful — all fail the same way: work gets lost, or the main checkout ends up in a state nobody can build. A worktree gives each line of work its own directory and its own branch, and git already knows how to do it. What was missing was a way to drive it that refuses to destroy anything by accident, and a way to actually *go there* without abandoning the conversation.
+
+## Tools
+
+### `worktree_create`
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `branch` | string | A new branch, or an existing one not checked out anywhere |
+| `base` | string, optional | Base ref for a new branch; defaults to HEAD |
+
+Creates the worktree under `~/.worktrees/<repo>/<branch>` and reports the path and base commit. The main checkout is untouched. The result also says plainly that the agent's own tools still point at the main checkout — only you can move the session (see below).
+
+### `worktree_list`
+
+No parameters. Every worktree with its branch and `primary` / `dirty` / `locked` / `prunable` flags.
+
+### `worktree_merge`
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `branch` | string | Branch of the worktree to merge back |
+
+With your confirmation: merges into the primary worktree's branch, then removes the worktree (keeping the branch). Both sides must be clean first. **A conflicting merge aborts cleanly** — the primary is restored and nothing is left half-merged.
+
+### `worktree_remove`
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `target` | string | Branch name or worktree path |
+
+Refuses the primary worktree, the one this session runs in, and locked ones outright. Uncommitted changes require your explicit confirmation, and are refused outright when there is no UI to ask through. The branch itself is always kept.
+
+## Entering a worktree
+
+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` returns to the session you came from. `/worktree create <branch> --enter` does both in one step.
+
+Two refusals, each with a different fix:
+
+- **`--no-session`** — entering forks a session file, so there has to be one.
+- **A session pi has not 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.
+
+Session switching is a user command, so **the agent cannot move itself**. That is why `worktree_create` says so in its result instead of implying the tools followed it there.
+
+## Command
+
+`/worktree` — the same list as `worktree_list`.
+`/worktree create <branch> [base] [--enter]` — create, optionally entering it.
+`/worktree enter <branch|path>` — take the conversation into a worktree.
+`/worktree exit` — return to the session you came from.
+`/worktree remove <branch|path>` — remove, with the same rails as the tool.
+`/worktree merge <branch>` — merge back and clean up.
+`/worktree prune` — drop administrative records for worktrees whose directories are gone.
+
+Everything after the route is taken whole, so paths with spaces work.
+
+## Targets resolve the way you would name them
+
+A branch, a full path, a directory name — or, for worktrees created by `isolation: "worktree"` in [`@pify/subagent`](https://github.com/pifydev/subagent), [`@pify/swarm`](https://github.com/pifydev/swarm) or [`@pify/workflow`](https://github.com/pifydev/workflow), the agent slug alone: `worker-1` finds branch `agent/worker-1`.
 
 ## 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.
+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 they reach git.
+
+Removal risk is assessed before anything happens: primary, current-session, locked, and dirty are four distinct verdicts, and only dirty is confirmable. Containment is checked on directory boundaries, so sitting in `feature-2` does not block removing `feature`.
+
+Integration tests run the whole create → merge → remove flow, and the conflict-abort path, against real repositories rather than mocks.
 
 ## Where this sits in the suite
 
-`@pify/subagent` and `@pify/swarm` run agents in-place (shared files — fine for read-mostly work). Worktrees are the isolation layer for parallel **mutating** work; spawning agents directly into worktrees is planned v0.2 integration across the three packages.
+`@pify/subagent` and `@pify/swarm` run agents in place — shared files, which is fine for read-mostly work. Worktrees are the isolation layer for parallel **mutating** work, and all three of the agent packages can create one per child with `isolation: "worktree"`. A worktree whose child changed nothing is removed automatically; anything uncommitted is kept and reported.
 
 ## License
 

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.1",
   "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

@@ -1,6 +1,6 @@
 ---
 name: worktree
-description: Use when work should happen in isolation from the main checkout - risky refactors, parallel efforts, or long-running changes - explains the worktree tools, safety rails, and the merge-back flow
+description: Use when work should happen in isolation from the main checkout - risky refactors, parallel efforts, or long-running changes
 ---
 
 # Git worktrees
@@ -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(" ");
+}