@signalridge/pi-worktree 0.49.4 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.2.1
+### Patch Changes
+
+- 24a8af4: Remove references to the maintainer's personal dotfile setup from shipped docs
+  and source comments. Each constraint is restated as a property of the package
+  itself: which manager owns a settings file, whether a project permits git
+  worktrees, and installing a package from a single source. No runtime behavior
+  changes.
+
+## 1.0.0
+### Major Changes
+
+- Adopt a unified 1.0.0 across every published package.
+  
+  The version numbers no longer track their upstream forks individually; from this release each package
+  is versioned on its own merit against the Signalridge line, and 1.0.0 is the shared starting point.
+  Packages whose behavior changed in this release document that change in their own changeset entries;
+  the remainder are re-released unchanged so the whole set shares one baseline.
+
+### Patch Changes
+
+- Strip Unicode bidirectional overrides — and DCS/PM/APC payloads in the footer and recall picker — from untrusted text before display, so a crafted branch name, worktree path, model id, or recalled message can no longer visually reverse what the user reads and acts on.
+- Wire the hardened terminal sanitizers to the fields that actually carry hostile text, bound the escape-sequence skippers, and give worktree Add base-commit provenance.
+  
+  - `pi-statusline`: the `branch`, `provider`, and `tools` segments now pass through `sanitizeTerminalText`. The branch is sanitized before the GitHub PR context is composed in, so a hostile ref name can no longer emit raw OSC/CSI/bidi into the footer while the PR hyperlink keeps working.
+  - `pi-statusline` / `pi-recall`: an escape-sequence introducer with no terminator now drops only itself instead of consuming the rest of the string, so a single `0x90` in a branch name or saved message no longer blanks a footer row, a preview, or the fuzzy-search text. SOS is handled alongside DCS/PM/APC.
+  - `pi-recall`: previews are sanitized before truncation, so the preview budget is spent on visible characters instead of invisible escape bytes.
+  - `pi-worktree`: line separators are replaced with a space instead of being dropped, so multi-line Git output no longer welds two records together inside a destructive confirmation body.
+  - `pi-worktree`: Add resolves the base commit for both the create and the attach case (the attach case previously captured none, letting Git re-resolve the branch at exec time), shows the full base OID in the confirmation, and re-reads `git worktree list`, the local branch ref, and the base OID under the worktree mutation lock immediately before `git worktree add`. A base that moved, or a branch or path claimed while the dialog was open, refuses the add with a message naming both OIDs instead of silently creating a worktree from an unapproved base.
+
 ## 0.49.4
 ### Patch Changes
 

package/README.md

@@ -6,7 +6,7 @@
 
 Pi cannot change its parent process working directory with `cd`. This extension performs the safe equivalent: it prepares a Pi session whose cwd is the selected worktree and switches to that session, preserving the current conversation when it has already been persisted.
 
-This package is the full interactive worktree manager. It is publishable and stable, but it is not automatically enabled by the signalridge dotfiles configuration: the user's AGENTS constitution forbids worktrees.
+This package is the full interactive worktree manager. It is publishable and stable, and opt-in: install it only if your project allows git worktrees. Some repositories forbid them outright — a worktree placed inside the source tree can be picked up by tooling that scans the tree, so check your repository's own guidance before enabling it.
 
 ## ✨ Features
 
@@ -52,7 +52,7 @@ Run the command without arguments:
 
 Choose one action:
 
-- **Add worktree** — enter a branch, optional start point, and optional path; confirm creation and optionally switch.
+- **Add worktree** — enter a branch, optional start point, and optional path; the confirmation names the branch, base ref, full base commit, and target path before creation, then optionally switch.
 - **Switch worktree** — select another existing worktree and continue this Pi conversation there.
 - **Remove worktree** — remove a linked worktree without deleting its branch; local ignored data must be removed first.
 - **Prune stale metadata** — inspect Git's dry-run output, then optionally run the matching prune.
@@ -129,8 +129,10 @@ A successfully created Git worktree is never rolled back merely because Pi sessi
 - Removal and prune inspect reflogs, pseudorefs, per-worktree refs, and `FETCH_HEAD`. Historical commits reachable only through this administrative recovery state are listed by full OID in the destructive confirmation; approval removes those recovery pointers, so Git may later garbage-collect the commits. Create a branch or tag instead when any listed commit should survive.
 - Staged-only administrative index state, a missing attached branch ref, or an unreachable current detached HEAD still blocks prune without an override.
 - Removal never deletes a branch and never uses `--force`.
+- Worktree paths, branches, and lock reasons are stripped of terminal control characters and bidirectional overrides before display, so a crafted branch name cannot make the menu read as a different worktree than the one a removal acts on. Line separators become a single space rather than disappearing, so multi-line Git output in a destructive confirmation never welds two records into one.
 - Safe removal invokes argv-based `git worktree move <path> <quarantine>` before validation, moves the real tree to a private tombstone, reserves the registered path with an exclusive non-directory entry, and uses an isolated `git worktree prune --expire now` for metadata only. Failed pre-removal recovery uses the inverse Git move and retains an unsafe quarantine; production runtime never invokes a shell, `rm`, or `rm -rf`.
 - Prune always runs `git worktree prune --dry-run --verbose` before confirmation, inspects candidates omitted from porcelain, rechecks the exact preview and recovery-risk set after confirmation, and uses Git's default expiry. Remove likewise rechecks worktree identity, filesystem path identity, inventory immediately before deletion, administrative path, and the approved recovery-risk set before mutation.
+- Add resolves the base commit before confirmation — for a new branch from the requested start point, and for an existing branch from `refs/heads/<branch>` so a same-named tag cannot stand in — shows branch, base ref, full base OID, and path in the confirmation, and then re-reads `git worktree list`, the local branch ref, and the base OID under the worktree mutation lock immediately before `git worktree add`. A base that moved, a branch that was created, deleted, or checked out elsewhere, or a path that was claimed while the dialog was open refuses the add instead of creating a worktree from a base the user did not approve; the message names both OIDs so you can re-run Add to approve the new base. The created worktree is verified against the approved branch ref and base OID.
 - The extension does not expose commit, push, rebase, repair, user-requested move, lock, or unlock worktree actions.
 
 Use Git directly when you intentionally need force removal, branch deletion, custom prune expiry, detach/orphan creation, move, repair, lock, or unlock behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-worktree",
-  "version": "0.49.4",
+  "version": "1.2.1",
   "description": "Pi extension for safe interactive Git worktree management and workspace switching.",
   "type": "module",
   "license": "MIT",

package/src/command.ts

@@ -14,6 +14,7 @@ import {
   formatWorktree,
   listWorktrees,
   localBranchExists,
+  localBranchRef,
   pathEntryExists,
   pathIdentity,
   pathsEqual,
@@ -58,6 +59,15 @@ interface AdministrativeHistoryRisk {
   oids: string[];
 }
 
+/** The base commit the user approved, captured before the confirmation and re-checked after it. */
+interface AddBaseProvenance {
+  kind: "create" | "attach";
+  /** Human-facing base, e.g. "main" for a new branch or "refs/heads/feature" for an attach. */
+  label: string;
+  /** Lowercased full OID that `label` resolved to when the preview was built. */
+  oid: string;
+}
+
 export function registerWorktreeCommand(
   pi: ExtensionAPI,
   settings: WorktreeSettingsRuntime,
@@ -179,9 +189,18 @@ async function addFlow(
     throw new Error(`Branch ${branch} is already checked out at ${occupied.path}.`);
   }
 
-  let startOid: string | undefined;
-  let startLabel: string | undefined;
-  if (!branchExists) {
+  // Capture the base commit for BOTH cases. The attach case never had one: argv is
+  // ["worktree", "add", <path>, <branch>], so Git resolves the branch at exec time and a
+  // concurrent `git branch -f` or rebase silently moved the base out from under the user.
+  let provenance: AddBaseProvenance;
+  if (branchExists) {
+    const ref = localBranchRef(branch);
+    provenance = {
+      kind: "attach",
+      label: ref,
+      oid: (await resolveCommit(pi, ctx.cwd, ref, ctx.signal)).toLowerCase(),
+    };
+  } else {
     const defaultStart = await symbolicBranch(pi, ctx.cwd, ctx.signal);
     const requestedStart = await ctx.ui.input(
       stripTerminalControls(
@@ -192,9 +211,13 @@ async function addFlow(
       stripTerminalControls(defaultStart ?? "commit-ish"),
     );
     if (requestedStart === undefined) return;
-    startLabel = requestedStart.trim() || defaultStart;
+    const startLabel = requestedStart.trim() || defaultStart;
     if (!startLabel) throw new Error("An explicit start point is required from detached HEAD.");
-    startOid = await resolveCommit(pi, ctx.cwd, startLabel, ctx.signal);
+    provenance = {
+      kind: "create",
+      label: startLabel,
+      oid: (await resolveCommit(pi, ctx.cwd, startLabel, ctx.signal)).toLowerCase(),
+    };
   }
 
   const suggestedPath = defaultWorktreePath(main.path, branch, worktreeRoot);
@@ -210,27 +233,95 @@ async function addFlow(
     throw new Error(`The target path is already registered as a worktree: ${pathCollision.path}.`);
   }
 
-  const summary = branchExists
-    ? `Attach existing branch ${branch} at ${targetPath}?`
-    : `Create branch ${branch} from ${startLabel} at ${targetPath}?`;
-  if (!(await ctx.ui.confirm("Create Git worktree", stripTerminalControls(summary)))) return;
+  // Sanitize each line, then join: stripTerminalControls maps a newline to a space, so stripping
+  // the joined string would collapse the preview back onto one line.
+  const summary = [
+    provenance.kind === "attach" ? `Attach existing branch ${branch}.` : `Create branch ${branch}.`,
+    `Branch:      ${branch}`,
+    `Base:        ${provenance.label}`,
+    `Base commit: ${provenance.oid}`,
+    `Path:        ${targetPath}`,
+  ]
+    .map((line) => stripTerminalControls(line))
+    .join("\n");
+  if (!(await ctx.ui.confirm("Create Git worktree", summary))) return;
+
+  // Re-check under the mutation lock, mirroring pruneFlow: `records` was captured when the menu
+  // opened, so every pre-confirmation check above is stale by the whole menu lifetime. The lock
+  // cannot stop an external `git branch -f` — that is what the base-OID check is for — but it does
+  // shrink the window against this package's own flows, and it never spans a dialog.
+  const created = await withWorktreeMutationLock(
+    ctx.cwd,
+    async () => {
+      assertTargetFilesystemAvailable(targetPath);
 
-  assertTargetFilesystemAvailable(targetPath);
-  await addWorktree(pi, ctx.cwd, { path: targetPath, branch, startOid }, ctx.signal);
-  let created: WorktreeRecord;
-  try {
-    const updated = await listWorktrees(pi, ctx.cwd, ctx.signal);
-    const verified = updated.find((record) => pathsEqual(record.path, targetPath));
-    if (!verified || verified.branch !== branch) {
-      throw new Error("the expected path and branch were not present in Git porcelain output");
-    }
-    created = verified;
-  } catch (error) {
-    throw new Error(
-      `Git add completed, so the worktree was retained at ${targetPath}, but verification failed: ${formatError(error)}. Inspect git worktree list before retrying.`,
-    );
-  }
-  safeNotify(ctx, `Created worktree ${targetPath} on branch ${branch}.`, "info");
+      const latest = await listWorktrees(pi, ctx.cwd, ctx.signal);
+      const occupiedNow = worktreeForBranch(latest, branch);
+      if (occupiedNow) {
+        throw new Error(`Branch ${branch} was checked out at ${occupiedNow.path} after confirmation; add was refused.`);
+      }
+      const collisionNow = latest.find((record) => pathsEqual(record.path, targetPath));
+      if (collisionNow) {
+        throw new Error(`The target path became a registered worktree after confirmation: ${collisionNow.path}.`);
+      }
+
+      const existsNow = await localBranchExists(pi, ctx.cwd, branch, ctx.signal);
+      if (existsNow !== branchExists) {
+        throw new Error(
+          existsNow
+            ? `Branch ${branch} was created by another process after confirmation; add was refused.`
+            : `Branch ${branch} was deleted after confirmation; add was refused.`,
+        );
+      }
+
+      const currentOid = (
+        await resolveCommit(
+          pi,
+          ctx.cwd,
+          provenance.kind === "attach" ? localBranchRef(branch) : provenance.label,
+          ctx.signal,
+        )
+      ).toLowerCase();
+      if (!sameOid(currentOid, provenance.oid)) {
+        throw new Error(
+          `${provenance.label} moved from ${provenance.oid} to ${currentOid} after confirmation; add was refused. Run Add again to approve the new base.`,
+        );
+      }
+
+      await addWorktree(
+        pi,
+        ctx.cwd,
+        {
+          path: targetPath,
+          branch,
+          startOid: provenance.kind === "create" ? provenance.oid : undefined,
+        },
+        ctx.signal,
+      );
+
+      try {
+        const updated = await listWorktrees(pi, ctx.cwd, ctx.signal);
+        const verified = updated.find((record) => pathsEqual(record.path, targetPath));
+        // branchRef is stricter than branch: a deleted branch shadowed by a same-named tag produces
+        // a detached record whose branchRef is undefined.
+        if (
+          !verified ||
+          verified.branchRef !== localBranchRef(branch) ||
+          !verified.head ||
+          !sameOid(verified.head, provenance.oid)
+        ) {
+          throw new Error("the expected path, branch, and base commit were not present in Git porcelain output");
+        }
+        return verified;
+      } catch (error) {
+        throw new Error(
+          `Git add completed, so the worktree was retained at ${targetPath}, but verification failed: ${formatError(error)}. Inspect git worktree list before retrying.`,
+        );
+      }
+    },
+    ctx.signal,
+  );
+  safeNotify(ctx, `Created worktree ${targetPath} on branch ${branch} at ${provenance.oid}.`, "info");
 
   if (
     await ctx.ui.confirm("Switch Pi workspace?", stripTerminalControls(`Continue this conversation in ${targetPath}?`))
@@ -243,6 +334,10 @@ async function addFlow(
   }
 }
 
+function sameOid(left: string, right: string): boolean {
+  return left.toLowerCase() === right.toLowerCase();
+}
+
 function assertTargetFilesystemAvailable(targetPath: string): void {
   if (pathEntryExists(targetPath)) {
     throw new Error(`The target path already exists: ${targetPath}.`);

package/src/git.ts

@@ -137,8 +137,17 @@ export function parseWorktreePorcelain(output: string): WorktreeRecord[] {
   return records;
 }
 
+/**
+ * Fully qualify a local branch. Provenance must be resolved through this ref rather than the bare
+ * name: `git rev-parse` prefers `refs/tags/<name>`, so a same-named tag would otherwise yield the
+ * OID of an object `git worktree add <path> <branch>` will not check out.
+ */
+export function localBranchRef(branch: string): string {
+  return `${LOCAL_BRANCH_PREFIX}${branch}`;
+}
+
 export function worktreeForBranch(records: readonly WorktreeRecord[], branch: string): WorktreeRecord | undefined {
-  const branchRef = `${LOCAL_BRANCH_PREFIX}${branch}`;
+  const branchRef = localBranchRef(branch);
   return records.find((record) => record.branchRef === branchRef);
 }
 
@@ -263,12 +272,7 @@ export async function localBranchExists(
   branch: string,
   signal?: AbortSignal,
 ): Promise<boolean> {
-  const result = await runGitAllowFailure(
-    pi,
-    ["show-ref", "--verify", "--quiet", `${LOCAL_BRANCH_PREFIX}${branch}`],
-    cwd,
-    signal,
-  );
+  const result = await runGitAllowFailure(pi, ["show-ref", "--verify", "--quiet", localBranchRef(branch)], cwd, signal);
   if (result.killed) throw killedError(["show-ref", "--verify", "--quiet"]);
   if (result.code === 0) return true;
   if (result.code === 1) return false;
@@ -627,7 +631,9 @@ export async function administrativePruneCandidates(
     candidates.push(candidate);
     administrativeIdentities.set(candidate, metadataSnapshot(candidate.administrativePath));
   };
-  for (const entry of readdirSync(administrativeRoot, { withFileTypes: true })) {
+  for (const entry of readdirSync(administrativeRoot, {
+    withFileTypes: true,
+  })) {
     const administrativePath = resolve(administrativeRoot, entry.name);
     if (!entry.isDirectory() || entry.isSymbolicLink()) {
       throw new GitWorktreeError(`Unexpected Git worktree administrative entry: ${administrativePath}.`);
@@ -948,15 +954,55 @@ export function formatWorktree(record: WorktreeRecord, currentPath?: string): st
   return stripTerminalControls(`${record.path}  [${labels.join(", ") || "unknown"}]  ${head}`);
 }
 
+/**
+ * Layout-preserving sanitizer contract (the same shape pi-statusline implements, duplicated per the
+ * package boundary rule; pi-recall implements the prose variant that also collapses whitespace):
+ * - line separators become one space, so multi-line Git output stays readable as a single line
+ *   instead of welding the end of one record onto the start of the next;
+ * - every other unsafe code point (C0, DEL/C1, bidi overrides) is dropped with no replacement;
+ * - whitespace is neither collapsed nor trimmed.
+ * There is no escape-sequence parser here: dropping ESC and the C1 introducers already leaves any
+ * residual payload as inert text, and consuming it would let one byte erase the rest of a
+ * destructive confirmation prompt.
+ */
 export function stripTerminalControls(value: string): string {
   return [...value]
-    .filter((character) => {
-      const code = character.codePointAt(0) ?? 0;
-      return code > 0x1f && (code < 0x7f || code > 0x9f);
+    .map((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      if (isLineSeparator(codePoint)) return " ";
+      return isUnsafeTerminalCodePoint(codePoint) ? "" : character;
     })
     .join("");
 }
 
+// Git output is joined with newlines before it reaches a confirmation body. Dropping them outright
+// glued "Removing a: reason" onto "Removing b: reason", changing what the user reads before
+// approving an irreversible prune or removal.
+function isLineSeparator(codePoint: number): boolean {
+  return (
+    codePoint === 0x09 ||
+    codePoint === 0x0a ||
+    codePoint === 0x0d ||
+    codePoint === 0x85 ||
+    codePoint === 0x2028 ||
+    codePoint === 0x2029
+  );
+}
+
+// Bidi controls reorder what the menu shows without changing the path we act on, so a removal
+// prompt could name one worktree while the user reads another.
+function isUnsafeTerminalCodePoint(codePoint: number): boolean {
+  return (
+    codePoint <= 0x1f ||
+    (codePoint >= 0x7f && codePoint <= 0x9f) ||
+    codePoint === 0x061c ||
+    codePoint === 0x200e ||
+    codePoint === 0x200f ||
+    (codePoint >= 0x202a && codePoint <= 0x202e) ||
+    (codePoint >= 0x2066 && codePoint <= 0x2069)
+  );
+}
+
 async function runGit(
   pi: Pick<ExtensionAPI, "exec">,
   args: string[],
@@ -1089,7 +1135,11 @@ function runGitWithInputAllowFailure(
   }
   return new Promise((resolveResult, reject) => {
     // ExtensionAPI.exec has no stdin channel, so this read-only check uses an argv-only child.
-    const child = spawn("git", args, { cwd, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    const child = spawn("git", args, {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
     let stdout = "";
     let stderr = "";
     let killed = false;
@@ -1132,7 +1182,12 @@ function runGitWithInputAllowFailure(
     });
     child.once("error", fail);
     child.once("close", (code, closeSignal) => {
-      finish({ stdout, stderr, code: code ?? 1, killed: killed || closeSignal !== null });
+      finish({
+        stdout,
+        stderr,
+        code: code ?? 1,
+        killed: killed || closeSignal !== null,
+      });
     });
     signal?.addEventListener("abort", stop, { once: true });
     if (signal?.aborted) stop();