@pify/worktree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @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.
+
+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
+
+- **`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>` / `remove <target>` / `prune` for humans.
+
+## 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 integration tests run the whole create→merge→remove and conflict-abort flows against real repositories.
+
+## 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.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/worktree.ts

@@ -0,0 +1,281 @@
+/**
+ * @pify/worktree — safe git-worktree management for pi.
+ *
+ * The foundation for parallel MUTATING work: create isolated worktrees the
+ * agent (or you) can build in without touching the main checkout. Windows-
+ * first and dependency-free — no tmux, no daemons; every git call is an
+ * execFile argv (no shell, no interpolation — narumiruna's rule), and
+ * removal runs behind safety rails: primary/current/locked refuse outright,
+ * dirty needs explicit confirmation (fail-closed when headless).
+ *
+ * Spawning agents INTO worktrees is deliberately v0.2 integration work with
+ * @pify/subagent and @pify/swarm — v0.1 hands off cleanly: every created
+ * worktree's result says how to open pi there.
+ *
+ * Design synthesis: guarded manager + safety checks + path suggestion
+ * (@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 { Type } from "typebox";
+
+import {
+  createWorktree,
+  isDirty,
+  listWorktrees,
+  mergeBranch,
+  pruneWorktrees,
+  removeWorktree,
+  repoToplevel,
+} from "../src/git.ts";
+import { assessRemoval, formatWorktrees, validBranchName } from "../src/parse.ts";
+
+type UiContext = ExtensionContext;
+
+export default function worktree(pi: ExtensionAPI) {
+  function requireRepo(ctx: UiContext): string {
+    const top = repoToplevel(ctx.cwd);
+    if (!top) throw new Error("Not inside a git repository.");
+    return top;
+  }
+
+  function listText(ctx: UiContext): string {
+    const worktrees = listWorktrees(ctx.cwd);
+    const dirty = new Set(worktrees.filter((w) => isDirty(w.path)).map((w) => w.path));
+    return formatWorktrees(worktrees, dirty);
+  }
+
+  function resolveTarget(ctx: UiContext, target: string) {
+    const worktrees = listWorktrees(ctx.cwd);
+    const norm = (p: string) => p.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+    return worktrees.find(
+      (w) => w.branch === target || norm(w.path) === norm(target),
+    );
+  }
+
+  // ── Tools ────────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "worktree_list",
+    label: "List worktrees",
+    description:
+      "List the repository's git worktrees with branch, dirty/locked/prunable state, and which one " +
+      "is primary. Use before creating, removing, or merging.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      requireRepo(ctx as UiContext);
+      return { content: [{ type: "text", text: listText(ctx as UiContext) }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "worktree_create",
+    label: "Create worktree",
+    description:
+      "Create an isolated git worktree under ~/.worktrees/<repo>/ for parallel work that modifies " +
+      "files. branch: a new branch (created from base, default HEAD) or an existing unoccupied local " +
+      "branch. The main checkout stays untouched; report the returned path to the user so they can " +
+      "open pi there.",
+    parameters: Type.Object({
+      branch: Type.String({ description: "Branch name (new or existing-unoccupied)" }),
+      base: Type.Optional(Type.String({ description: "Base ref for a new branch (default HEAD)" })),
+    }),
+    async execute(_id, params: { branch: string; base?: string }, _signal, _onUpdate, ctx) {
+      requireRepo(ctx as UiContext);
+      const branch = params.branch.trim();
+      if (!validBranchName(branch)) {
+        throw new Error(`Invalid branch name ${JSON.stringify(params.branch)}.`);
+      }
+      if (params.base !== undefined && !validBranchName(params.base.trim()) && !/^[0-9a-f]{4,40}$/i.test(params.base.trim())) {
+        throw new Error(`Invalid base ref ${JSON.stringify(params.base)}.`);
+      }
+      const result = createWorktree((ctx as UiContext).cwd, branch, params.base?.trim());
+      if (!result.ok) throw new Error(result.message);
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `Worktree ready at ${result.path} (${result.message} base: ${result.base}).`,
+              `Open a pi session there with: cd "${result.path}" && pi`,
+              `When the work is done: worktree_merge branch="${branch}" merges it back and cleans up.`,
+            ].join("\n"),
+          },
+        ],
+        details: { path: result.path, branch, createdBranch: result.createdBranch },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "worktree_remove",
+    label: "Remove worktree",
+    description:
+      "Remove a worktree by branch name or path. Refuses the primary worktree, the one this session " +
+      "runs in, and locked ones; uncommitted changes need the user's confirmation (denied when no UI). " +
+      "The branch itself is kept.",
+    parameters: Type.Object({
+      target: Type.String({ description: "Branch name or worktree path" }),
+    }),
+    async execute(_id, params: { target: string }, _signal, _onUpdate, ctx) {
+      const uiCtx = ctx as UiContext;
+      requireRepo(uiCtx);
+      const target = resolveTarget(uiCtx, params.target.trim());
+      if (!target) throw new Error(`No worktree matches ${JSON.stringify(params.target)}. Use worktree_list.`);
+
+      const dirty = isDirty(target.path);
+      const risk = assessRemoval(target, uiCtx.cwd, dirty);
+
+      if (!risk.ok && !risk.confirmable) {
+        throw new Error(`Refusing to remove ${target.path}: ${risk.reasons.join("; ")}.`);
+      }
+      if (!risk.ok && risk.confirmable) {
+        if (!uiCtx.hasUI) {
+          throw new Error(
+            `Refusing to remove ${target.path}: ${risk.reasons.join("; ")} (no UI to confirm — fail-closed).`,
+          );
+        }
+        const approved = await uiCtx.ui.confirm(
+          "Remove dirty worktree",
+          `${target.path} has uncommitted changes that will be LOST. Remove anyway?`,
+        );
+        if (!approved) {
+          return {
+            content: [{ type: "text", text: "The user declined. Worktree kept." }],
+            details: {},
+          };
+        }
+      }
+
+      const result = removeWorktree(uiCtx.cwd, target.path, dirty);
+      if (!result.ok) throw new Error(result.output);
+      return {
+        content: [
+          { type: "text", text: `Removed worktree ${target.path}. Branch "${target.branch ?? "(detached)"}" was kept.` },
+        ],
+        details: { path: target.path },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "worktree_merge",
+    label: "Merge worktree",
+    description:
+      "Merge a worktree's branch into the primary worktree's current branch (with the user's " +
+      "confirmation), then remove the worktree on success. Conflicting merges abort cleanly and " +
+      "report — nothing is left half-merged.",
+    parameters: Type.Object({
+      branch: Type.String({ description: "Branch of the worktree to merge back" }),
+    }),
+    async execute(_id, params: { branch: string }, _signal, _onUpdate, ctx) {
+      const uiCtx = ctx as UiContext;
+      requireRepo(uiCtx);
+      const branch = params.branch.trim();
+      if (!validBranchName(branch)) throw new Error(`Invalid branch name ${JSON.stringify(params.branch)}.`);
+
+      const worktrees = listWorktrees(uiCtx.cwd);
+      const primary = worktrees.find((w) => w.primary);
+      const source = worktrees.find((w) => w.branch === branch);
+      if (!primary) throw new Error("Could not locate the primary worktree.");
+      if (!source) throw new Error(`No worktree has branch "${branch}". Use worktree_list.`);
+      if (source.primary) throw new Error("That is the primary worktree's own branch.");
+      if (isDirty(source.path)) {
+        throw new Error(`Worktree ${source.path} has uncommitted changes — commit them there first.`);
+      }
+      if (isDirty(primary.path)) {
+        throw new Error(`The primary worktree has uncommitted changes — commit or stash them first.`);
+      }
+
+      if (!uiCtx.hasUI) {
+        throw new Error("Merging needs the user's confirmation and no UI is available (fail-closed).");
+      }
+      const approved = await uiCtx.ui.confirm(
+        "Merge worktree",
+        `Merge branch "${branch}" into "${primary.branch ?? "the primary branch"}" and remove ${source.path}?`,
+      );
+      if (!approved) {
+        return { content: [{ type: "text", text: "The user declined the merge." }], details: {} };
+      }
+
+      const merge = mergeBranch(primary.path, branch);
+      if (!merge.ok) throw new Error(merge.message);
+
+      const removal = removeWorktree(uiCtx.cwd, source.path, false);
+      const cleanup = removal.ok
+        ? `Worktree ${source.path} removed (branch kept).`
+        : `Merge done, but removing the worktree failed: ${removal.output}`;
+      return {
+        content: [{ type: "text", text: `Merged "${branch}" into ${primary.branch ?? "primary"}.\n${cleanup}` }],
+        details: { branch, removed: removal.ok },
+      };
+    },
+  });
+
+  // ── Command ──────────────────────────────────────────────────────────
+
+  pi.registerCommand("worktree", {
+    description: "Manage git worktrees: /worktree [create <branch> | remove <target> | prune]",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) return;
+      const [route, arg] = (args ?? "").trim().split(/\s+/);
+      try {
+        requireRepo(ctx);
+        switch ((route || "list").toLowerCase()) {
+          case "list": {
+            ctx.ui.notify(listText(ctx), "info");
+            return;
+          }
+          case "create": {
+            if (!arg || !validBranchName(arg)) {
+              ctx.ui.notify("Usage: /worktree create <branch>", "warning");
+              return;
+            }
+            const result = createWorktree(ctx.cwd, arg);
+            ctx.ui.notify(
+              result.ok ? `Worktree ready: ${result.path}\nOpen with: cd "${result.path}" && pi` : result.message,
+              result.ok ? "info" : "error",
+            );
+            return;
+          }
+          case "remove": {
+            if (!arg) {
+              ctx.ui.notify("Usage: /worktree remove <branch|path>", "warning");
+              return;
+            }
+            const target = resolveTarget(ctx, arg);
+            if (!target) {
+              ctx.ui.notify(`No worktree matches "${arg}".`, "warning");
+              return;
+            }
+            const dirty = isDirty(target.path);
+            const risk = assessRemoval(target, ctx.cwd, dirty);
+            if (!risk.ok && !risk.confirmable) {
+              ctx.ui.notify(`Cannot remove: ${risk.reasons.join("; ")}.`, "error");
+              return;
+            }
+            if (dirty) {
+              const approved = await ctx.ui.confirm(
+                "Remove dirty worktree",
+                `${target.path} has uncommitted changes that will be LOST. Remove anyway?`,
+              );
+              if (!approved) return;
+            }
+            const result = removeWorktree(ctx.cwd, target.path, dirty);
+            ctx.ui.notify(result.ok ? `Removed ${target.path}.` : result.output, result.ok ? "info" : "error");
+            return;
+          }
+          case "prune": {
+            const result = pruneWorktrees(ctx.cwd);
+            ctx.ui.notify(result.output || "Nothing to prune.", result.ok ? "info" : "error");
+            return;
+          }
+          default:
+            ctx.ui.notify("Usage: /worktree [create <branch> | remove <target> | prune]", "warning");
+        }
+      } catch (err) {
+        ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@pify/worktree",
+  "version": "0.1.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",
+    "pi-extension",
+    "pi",
+    "pify",
+    "worktree",
+    "git"
+  ],
+  "homepage": "https://github.com/pifydev/worktree#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/worktree/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/worktree.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/worktree.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/worktree/SKILL.md

@@ -0,0 +1,37 @@
+---
+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
+---
+
+# Git worktrees
+
+This project has the `@pify/worktree` extension installed: create isolated
+worktrees for work that modifies files without touching the main checkout.
+
+## When to use
+
+- A risky or large change the user may want to abandon cleanly.
+- Parallel efforts on the same repo (each gets its own worktree + branch).
+- Keeping the main checkout buildable while something long-running proceeds.
+
+Not for read-only exploration (subagents already read in place) or trivial
+edits.
+
+## The flow
+
+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
+   primary branch, removes the worktree. Conflicts abort cleanly; nothing
+   is left half-merged.
+5. `worktree_remove target="feature-x"` — abandon instead; dirty worktrees
+   need the user's confirmation, the branch is always kept.
+
+## Rules
+
+- 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.

package/src/git.ts

@@ -0,0 +1,145 @@
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { existsSync } from "node:fs";
+import { branchToDirName, parseWorktreeList, type WorktreeInfo } from "./parse.ts";
+
+/**
+ * Git operations for @pify/worktree. Every call is execFile with an argv
+ * array — no shell, no interpolation, ever (narumiruna's rule). Errors
+ * surface git's own stderr so the agent/user sees the real reason.
+ */
+
+export interface GitResult {
+  ok: boolean;
+  output: string;
+}
+
+export function git(cwd: string, args: string[]): GitResult {
+  try {
+    const output = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: 30_000,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, output: output.trim() };
+  } catch (err) {
+    const e = err as { stderr?: string; stdout?: string; message?: string };
+    return { ok: false, output: (e.stderr || e.stdout || e.message || "git failed").toString().trim() };
+  }
+}
+
+export function repoToplevel(cwd: string): string | null {
+  const result = git(cwd, ["rev-parse", "--show-toplevel"]);
+  return result.ok ? result.output : null;
+}
+
+export function listWorktrees(cwd: string): WorktreeInfo[] {
+  const result = git(cwd, ["worktree", "list", "--porcelain"]);
+  return result.ok ? parseWorktreeList(result.output) : [];
+}
+
+export function isDirty(worktreePath: string): boolean {
+  const result = git(worktreePath, ["status", "--porcelain"]);
+  return result.ok && result.output !== "";
+}
+
+export function branchExists(cwd: string, branch: string): boolean {
+  return git(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]).ok;
+}
+
+export function currentShortHead(cwd: string): string {
+  const result = git(cwd, ["rev-parse", "--short", "HEAD"]);
+  return result.ok ? result.output : "unknown";
+}
+
+/** Suggested location: ~/.worktrees/<repo-name>/<branch-dir> (narumiruna). */
+export function suggestPath(cwd: string, branch: string): string {
+  const top = repoToplevel(cwd);
+  const repo = top ? basename(top) : "repo";
+  let candidate = join(homedir(), ".worktrees", repo, branchToDirName(branch));
+  let counter = 2;
+  while (existsSync(candidate)) {
+    candidate = join(homedir(), ".worktrees", repo, `${branchToDirName(branch)}-${counter}`);
+    counter++;
+  }
+  return candidate;
+}
+
+export interface CreateResult {
+  ok: boolean;
+  path: string;
+  base: string;
+  createdBranch: boolean;
+  message: string;
+}
+
+/**
+ * Create a worktree: a NEW branch from HEAD (default) or an existing,
+ * unoccupied local branch checked out into the new worktree.
+ */
+export function createWorktree(cwd: string, branch: string, base?: string): CreateResult {
+  const path = suggestPath(cwd, branch);
+  const exists = branchExists(cwd, branch);
+
+  if (exists) {
+    const occupied = listWorktrees(cwd).find((w) => w.branch === branch);
+    if (occupied) {
+      return {
+        ok: false,
+        path: occupied.path,
+        base: "",
+        createdBranch: false,
+        message: `Branch "${branch}" is already checked out at ${occupied.path}.`,
+      };
+    }
+    const result = git(cwd, ["worktree", "add", path, branch]);
+    return {
+      ok: result.ok,
+      path,
+      base: branch,
+      createdBranch: false,
+      message: result.ok ? `Checked out existing branch "${branch}".` : result.output,
+    };
+  }
+
+  const baseRef = base ?? "HEAD";
+  const result = git(cwd, ["worktree", "add", "-b", branch, path, baseRef]);
+  return {
+    ok: result.ok,
+    path,
+    base: baseRef === "HEAD" ? currentShortHead(cwd) : baseRef,
+    createdBranch: true,
+    message: result.ok ? `Created branch "${branch}".` : result.output,
+  };
+}
+
+export function removeWorktree(cwd: string, path: string, force: boolean): GitResult {
+  const args = ["worktree", "remove", ...(force ? ["--force"] : []), path];
+  return git(cwd, args);
+}
+
+export function pruneWorktrees(cwd: string): GitResult {
+  return git(cwd, ["worktree", "prune", "-v"]);
+}
+
+export interface MergeResult {
+  ok: boolean;
+  message: string;
+}
+
+/** Merge a worktree's branch into the primary worktree's current branch. */
+export function mergeBranch(primaryPath: string, branch: string): MergeResult {
+  const result = git(primaryPath, ["merge", "--no-edit", branch]);
+  if (!result.ok && isDirty(primaryPath)) {
+    // A failed merge may leave conflicts — abort to restore a clean state.
+    git(primaryPath, ["merge", "--abort"]);
+    return {
+      ok: false,
+      message: `Merge of "${branch}" conflicts — aborted, primary worktree restored. Resolve manually:\n${result.output}`,
+    };
+  }
+  return { ok: result.ok, message: result.output };
+}

package/src/parse.ts

@@ -0,0 +1,128 @@
+/**
+ * Pure parsing/validation for @pify/worktree.
+ * No imports from pi packages; no fs/process — fully unit-testable.
+ */
+
+export interface WorktreeInfo {
+  path: string;
+  head: string;
+  /** Branch name without refs/heads/, or null when detached. */
+  branch: string | null;
+  detached: boolean;
+  locked: boolean;
+  prunable: boolean;
+  /** The repository's primary worktree (first entry in porcelain output). */
+  primary: boolean;
+}
+
+/** Parse `git worktree list --porcelain` output. */
+export function parseWorktreeList(porcelain: string): WorktreeInfo[] {
+  const worktrees: WorktreeInfo[] = [];
+  let current: Partial<WorktreeInfo> | null = null;
+
+  const flush = () => {
+    if (current?.path) {
+      worktrees.push({
+        path: current.path,
+        head: current.head ?? "",
+        branch: current.branch ?? null,
+        detached: current.detached ?? false,
+        locked: current.locked ?? false,
+        prunable: current.prunable ?? false,
+        primary: worktrees.length === 0,
+      });
+    }
+    current = null;
+  };
+
+  for (const line of porcelain.split("\n")) {
+    const trimmed = line.trimEnd();
+    if (trimmed === "") {
+      flush();
+      continue;
+    }
+    if (trimmed.startsWith("worktree ")) {
+      flush();
+      current = { path: trimmed.slice("worktree ".length) };
+    } else if (!current) {
+      continue;
+    } else if (trimmed.startsWith("HEAD ")) {
+      current.head = trimmed.slice(5);
+    } else if (trimmed.startsWith("branch ")) {
+      current.branch = trimmed.slice(7).replace(/^refs\/heads\//, "");
+    } else if (trimmed === "detached") {
+      current.detached = true;
+    } else if (trimmed === "locked" || trimmed.startsWith("locked ")) {
+      current.locked = true;
+    } else if (trimmed === "prunable" || trimmed.startsWith("prunable ")) {
+      current.prunable = true;
+    }
+  }
+  flush();
+  return worktrees;
+}
+
+/**
+ * Branch-name safety: git's own rules, restricted further so a name can never
+ * smuggle flags or path tricks into an argv (no leading '-', no '..', no
+ * control chars, printable subset only).
+ */
+export function validBranchName(name: string): boolean {
+  if (!name || name.length > 200) return false;
+  if (name.startsWith("-") || name.startsWith("/") || name.endsWith("/")) return false;
+  if (name.endsWith(".lock") || name.includes("..") || name.includes("//")) return false;
+  if (name.includes("@{") || name === "@") return false;
+  return /^[A-Za-z0-9._\-/]+$/.test(name);
+}
+
+/** Filesystem-safe directory name for a branch (feature/x → feature-x). */
+export function branchToDirName(branch: string): string {
+  return branch.replace(/\//g, "-").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 100);
+}
+
+export interface RemovalRisk {
+  ok: boolean;
+  reasons: string[];
+  /** Risks a user may explicitly confirm through (dirty). */
+  confirmable: boolean;
+}
+
+/** Assess whether a worktree can be removed safely (narumiruna's rails). */
+export function assessRemoval(
+  target: WorktreeInfo,
+  currentCwd: string,
+  dirty: boolean,
+): RemovalRisk {
+  const reasons: string[] = [];
+  const norm = (p: string) => p.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+
+  if (target.primary) reasons.push("it is the primary worktree");
+  if (norm(currentCwd).startsWith(norm(target.path))) {
+    reasons.push("the current session is running inside it");
+  }
+  if (target.locked) reasons.push("it is locked (git worktree lock)");
+
+  const hard = reasons.length > 0;
+  if (dirty) reasons.push("it has uncommitted changes");
+
+  return { ok: reasons.length === 0, reasons, confirmable: !hard && dirty };
+}
+
+export function formatWorktrees(worktrees: WorktreeInfo[], dirtyPaths: Set<string>): string {
+  if (worktrees.length === 0) return "No worktrees.";
+  return worktrees
+    .map((w) => {
+      const flags = [
+        w.primary ? "primary" : "",
+        w.detached ? "detached" : "",
+        w.locked ? "locked" : "",
+        w.prunable ? "prunable" : "",
+        dirtyPaths.has(w.path) ? "dirty" : "",
+      ]
+        .filter(Boolean)
+        .join(", ");
+      const label = w.branch ?? w.head.slice(0, 8);
+      return `${w.path}\n  ${label}${flags ? ` (${flags})` : ""}`;
+    })
+    .join("\n");
+}