@signalridge/pi-worktree 1.4.3 → 1.4.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.4.4
+### Patch Changes
+
+- 3364cc0: Use patched Vitest 4.1.11 for development and regression testing without moving to a new major version. Refresh compatible transitive dependencies to include fixed source-map and brace-expansion releases.
+- 3364cc0: Adopt Pi 1.0.4's host-provided dependency contract: declare imported Pi and TypeBox modules as `*` peers rather than installing duplicate runtime modules, and align Pi development pins with the repository's tested 1.0.4 baseline. The wildcard identifies host module ownership; it does not promise compatibility with every Pi version.
+- 3364cc0: Cancel credential loaders, settings dialogs, and worktree operations when their owning session or branch retires, and ignore late results. Include boundary-generated usage receipts in statusline polling, mark only subscription-backed OAuth costs, and report headless worktree rejection on stderr.
+- 3364cc0: Keep runtime settings synchronized after successful atomic publication even when the command owner retires. Preserve sanitized recovery diagnostics for retained worktrees and uncertain metadata removal outcomes after cancellation, without notifying obsolete UI contexts or attempting to restore committed Git registrations.
+- Updated dependencies [3364cc0]
+- Updated dependencies [3364cc0]
+- Updated dependencies [3364cc0]
+  - @signalridge/pi-ui@1.3.3
+
 ## 1.4.3
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-worktree",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Pi extension for safe interactive Git worktree management and workspace switching.",
   "type": "module",
   "license": "MIT",
@@ -35,16 +35,16 @@
     "lint": "biome check ."
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1"
+    "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.7",
-    "@earendil-works/pi-coding-agent": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
     "@types/node": "26.1.2",
     "@types/proper-lockfile": "^4.1.4",
     "typescript": "7.0.2",
-    "vitest": "4.0.18"
+    "vitest": "4.1.11"
   },
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
   },
   "dependencies": {
     "@narumitw/pi-tui-kit": "^0.54.0",
-    "@signalridge/pi-ui": "^1.3.2",
+    "@signalridge/pi-ui": "^1.3.3",
     "proper-lockfile": "^4.1.2"
   }
 }

package/src/command-owner.ts

@@ -0,0 +1,51 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export interface WorktreeMenuOwner {
+  signal: AbortSignal;
+  isCurrent(): boolean;
+}
+
+/** Await host work without retaining abort listeners or requiring an RPC response. */
+export async function awaitOwned<T>(owner: WorktreeMenuOwner, start: () => Promise<T>): Promise<T> {
+  assertOwner(owner);
+  let cancel!: () => void;
+  const cancelled = new Promise<never>((_resolve, reject) => {
+    cancel = () => reject(new DOMException("Worktree command cancelled", "AbortError"));
+    owner.signal.addEventListener("abort", cancel, { once: true });
+  });
+  try {
+    assertOwner(owner);
+    const result = await Promise.race([start(), cancelled]);
+    assertOwner(owner);
+    return result;
+  } finally {
+    owner.signal.removeEventListener("abort", cancel);
+  }
+}
+
+export function assertOwner(owner: WorktreeMenuOwner): void {
+  if (owner.signal.aborted || !owner.isCurrent()) {
+    throw new DOMException("Worktree command cancelled", "AbortError");
+  }
+}
+
+/** All flows use the lifecycle/action signal, never the agent-run ctx.signal. */
+export function ownedContext(ctx: ExtensionCommandContext, owner: WorktreeMenuOwner): ExtensionCommandContext {
+  return {
+    ...ctx,
+    signal: owner.signal,
+    waitForIdle: () => awaitOwned(owner, () => ctx.waitForIdle()),
+    ui: {
+      ...ctx.ui,
+      input: (title, placeholder, options) =>
+        awaitOwned(owner, () => ctx.ui.input(title, placeholder, { ...options, signal: owner.signal })),
+      confirm: (title, message, options) =>
+        awaitOwned(owner, () => ctx.ui.confirm(title, message, { ...options, signal: owner.signal })),
+      select: (title, choices, options) =>
+        awaitOwned(owner, () => ctx.ui.select(title, choices, { ...options, signal: owner.signal })),
+      notify: (message, level) => {
+        if (!owner.signal.aborted && owner.isCurrent()) ctx.ui.notify(message, level);
+      },
+    },
+  };
+}

package/src/command.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 import { withBorderedCustomUi } from "@signalridge/pi-ui";
+import { assertOwner, ownedContext, type WorktreeMenuOwner } from "./command-owner.js";
 import {
   type AdministrativePruneCandidate,
   addWorktree,
@@ -28,6 +29,7 @@ import {
   unresolvableSymlinkAncestor,
   validateBranch,
   type WorktreeRecord,
+  WorktreeRecoveryError,
   withWorktreeMutationLock,
   worktreeAdministrativeDirectory,
   worktreeForBranch,
@@ -54,11 +56,6 @@ const ACTIONS = {
   configure: ACTION_CONFIGURE_ROOT,
 } as const;
 
-interface WorktreeMenuOwner {
-  signal: AbortSignal;
-  isCurrent(): boolean;
-}
-
 interface AdministrativeHistoryRisk {
   label: string;
   oids: string[];
@@ -90,19 +87,31 @@ export function registerWorktreeCommand(
         return;
       }
 
+      // Capture ownership before idle/Git preflight, not after it.
+      const owner = getMenuOwner();
+      const originalCtx = ctx;
+      if (owner.signal.aborted || !owner.isCurrent()) return;
+      ctx = ownedContext(ctx, owner);
       try {
         await ctx.waitForIdle();
         const records = await listWorktrees(pi, ctx.cwd, ctx.signal);
         const currentPath = await currentWorktreePath(pi, ctx.cwd, ctx.signal);
         const root = settings.get();
         const warning = root.warning ? " — settings warning" : "";
-        const owner = getMenuOwner();
-        if (owner.signal.aborted || !owner.isCurrent()) return;
-        const runFlow = async (flow: () => Promise<void>) => {
+        assertOwner(owner);
+        const runFlow = async (signal: AbortSignal, flow: (flowCtx: ExtensionCommandContext) => Promise<void>) => {
+          const actionOwner = { signal: AbortSignal.any([owner.signal, signal]), isCurrent: owner.isCurrent };
           try {
-            await flow();
+            assertOwner(actionOwner);
+            await flow(ownedContext(originalCtx, actionOwner));
           } catch (error) {
-            safeNotify(ctx, formatError(error), "error");
+            if (!actionOwner.signal.aborted && actionOwner.isCurrent()) {
+              safeNotify(ctx, formatError(error), "error");
+            } else if (error instanceof WorktreeRecoveryError) {
+              // Retained trees/unknown mutation outcomes outlive their UI owner.
+              // Do not access a retired context, even to check whether it has UI.
+              console.error(stripTerminalControls(formatError(error)));
+            }
           }
           return { kind: "close" } as const;
         };
@@ -128,12 +137,15 @@ export function registerWorktreeCommand(
             }),
           },
           actions: {
-            add: async () => runFlow(() => addFlow(pi, ctx, records, root.effectiveRoot)),
-            switch: async ({ signal }) => runFlow(() => switchFlow(pi, ctx, records, currentPath, signal)),
-            remove: async ({ signal }) => runFlow(() => removeFlow(pi, ctx, records, currentPath, signal)),
-            status: async ({ signal }) => runFlow(() => statusFlow(pi, ctx, records, currentPath, signal)),
-            prune: async () => runFlow(() => pruneFlow(pi, ctx, records)),
-            configure: async () => runFlow(() => configureRootFlow(ctx, settings)),
+            add: async ({ signal }) => runFlow(signal, (flowCtx) => addFlow(pi, flowCtx, records, root.effectiveRoot)),
+            switch: async ({ signal }) =>
+              runFlow(signal, (flowCtx) => switchFlow(pi, flowCtx, records, currentPath, flowCtx.signal)),
+            remove: async ({ signal }) =>
+              runFlow(signal, (flowCtx) => removeFlow(pi, flowCtx, records, currentPath, flowCtx.signal)),
+            status: async ({ signal }) =>
+              runFlow(signal, (flowCtx) => statusFlow(pi, flowCtx, records, currentPath, flowCtx.signal)),
+            prune: async ({ signal }) => runFlow(signal, (flowCtx) => pruneFlow(pi, flowCtx, records)),
+            configure: async ({ signal }) => runFlow(signal, (flowCtx) => configureRootFlow(flowCtx, settings)),
           },
         });
         await runMenu(withBorderedCustomUi(ctx), menu, {
@@ -149,7 +161,8 @@ export function registerWorktreeCommand(
 }
 
 async function configureRootFlow(ctx: ExtensionCommandContext, settings: WorktreeSettingsRuntime): Promise<void> {
-  const current = await settings.reload();
+  const current = await settings.reload(ctx.signal);
+  ctx.signal?.throwIfAborted();
   if (!current.canSave) {
     throw new Error(current.warning ?? `Fix ${settings.getPath()} before changing pi-worktree settings.`);
   }
@@ -159,7 +172,9 @@ async function configureRootFlow(ctx: ExtensionCommandContext, settings: Worktre
   );
   if (requested === undefined) return;
   const configuredRoot = requested.trim() || undefined;
-  const updated = await settings.save(configuredRoot);
+  ctx.signal?.throwIfAborted();
+  const updated = await settings.save(configuredRoot, ctx.signal);
+  ctx.signal?.throwIfAborted();
   safeNotify(
     ctx,
     configuredRoot === undefined
@@ -320,7 +335,7 @@ async function addFlow(
         }
         return verified;
       } catch (error) {
-        throw new Error(
+        throw new WorktreeRecoveryError(
           `Git add completed, so the worktree was retained at ${targetPath}, but verification failed: ${formatError(error)}. Inspect git worktree list before retrying.`,
         );
       }
@@ -859,10 +874,15 @@ async function selectWorktree(
 }
 
 function safeNotify(ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error"): void {
+  const sanitized = stripTerminalControls(message);
+  if (!ctx.hasUI) {
+    console.error(sanitized);
+    return;
+  }
   try {
-    ctx.ui.notify(stripTerminalControls(message), level);
+    ctx.ui.notify(sanitized, level);
   } catch {
-    console.error(message);
+    console.error(sanitized);
   }
 }
 

package/src/git.ts

@@ -70,6 +70,14 @@ export class GitWorktreeError extends Error {
     this.args = args;
   }
 }
+/** A mutation left retained data or an outcome that requires recovery inspection. */
+export class WorktreeRecoveryError extends GitWorktreeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorktreeRecoveryError";
+  }
+}
+
 class MetadataDeletionRetainedError extends Error {
   readonly retainedPath: string;
   readonly outcomeUnknown: boolean;
@@ -376,19 +384,35 @@ async function acquireFilesystemMutationLock(key: string, signal?: AbortSignal):
   }
 }
 
-async function withMetadataPruneLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
+async function withMetadataPruneLock<T>(key: string, operation: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+  signal?.throwIfAborted();
   const previous = metadataPruneLocks.get(key);
   let release!: () => void;
   const current = new Promise<void>((resolveLock) => {
     release = resolveLock;
   });
   metadataPruneLocks.set(key, current);
-  if (previous) await previous;
+  let cancel: (() => void) | undefined;
   try {
+    if (previous) {
+      await Promise.race([
+        previous,
+        new Promise<never>((_resolve, reject) => {
+          cancel = () => reject(new GitWorktreeError("worktree mutation lock wait aborted."));
+          signal?.addEventListener("abort", cancel, { once: true });
+          if (signal?.aborted) cancel();
+        }),
+      ]);
+    }
+    signal?.throwIfAborted();
     return await operation();
   } finally {
-    release();
-    if (metadataPruneLocks.get(key) === current) metadataPruneLocks.delete(key);
+    if (cancel) signal?.removeEventListener("abort", cancel);
+    // A cancelled queue slot must not let its successors overtake the holder.
+    void Promise.resolve(previous).then(() => {
+      release();
+      if (metadataPruneLocks.get(key) === current) metadataPruneLocks.delete(key);
+    });
   }
 }
 
@@ -398,14 +422,19 @@ export function withWorktreeMutationLock<T>(
   signal?: AbortSignal,
 ): Promise<T> {
   const key = worktreeMutationLockKey(cwd);
-  return withMetadataPruneLock(key, async () => {
-    const release = await acquireFilesystemMutationLock(key, signal);
-    try {
-      return await operation();
-    } finally {
-      await release();
-    }
-  });
+  return withMetadataPruneLock(
+    key,
+    async () => {
+      const release = await acquireFilesystemMutationLock(key, signal);
+      try {
+        signal?.throwIfAborted();
+        return await operation();
+      } finally {
+        await release();
+      }
+    },
+    signal,
+  );
 }
 
 function commonDirectoryForGitdir(gitdir: string): string {
@@ -515,19 +544,36 @@ export async function removeWorktreeMetadata(
       throw new GitWorktreeError(`Refusing metadata prune because the stale-record preview changed.`);
     }
     if (targetAdministrative) {
-      await removeAdministrativeRecord(targetAdministrative);
+      await removeAdministrativeRecord(targetAdministrative, signal);
     } else {
-      await runGit(pi, ["worktree", "prune", "--expire", "now"], cwd, signal, GIT_MUTATION_TIMEOUT_MS);
-    }
-    const after = await listWorktrees(pi, cwd, signal);
-    if (after.some((record) => pathsEqual(record.path, path))) {
-      throw new GitWorktreeError(`Git did not remove worktree metadata for ${path}.`);
-    }
-    const administrativeAfter = await administrativePruneCandidatesIfPresent(pi, cwd, signal);
-    if (administrativeAfter.length !== 0) {
-      throw new GitWorktreeError(`Git left stale administrative records after pruning ${path}.`);
+      signal?.throwIfAborted();
+      try {
+        await runGit(pi, ["worktree", "prune", "--expire", "now"], cwd, signal, GIT_MUTATION_TIMEOUT_MS);
+      } catch (error) {
+        // An interrupted Git process may already have deregistered the tree.
+        throw new WorktreeRecoveryError(
+          `Worktree metadata removal outcome is unknown for ${path}: ${formatError(error)}`,
+        );
+      }
     }
+    // Deregistration is the commit point, not the subsequent verification.
+    // Never attempt registration rollback after successful metadata deletion.
     onMetadataRemoved?.();
+    try {
+      // Recovery verification must finish independently of the retired UI owner.
+      const after = await listWorktrees(pi, cwd);
+      if (after.some((record) => pathsEqual(record.path, path))) {
+        throw new GitWorktreeError(`Git did not remove worktree metadata for ${path}.`);
+      }
+      const administrativeAfter = await administrativePruneCandidatesIfPresent(pi, cwd);
+      if (administrativeAfter.length !== 0) {
+        throw new GitWorktreeError(`Git left stale administrative records after pruning ${path}.`);
+      }
+    } catch (error) {
+      throw new WorktreeRecoveryError(
+        `Worktree metadata removal completed for ${path}, but verification failed: ${formatError(error)}`,
+      );
+    }
   };
   if (lockHeld) await operation();
   else await withWorktreeMutationLock(cwd, operation, signal);
@@ -817,7 +863,11 @@ async function removeMetadataTree(path: string, expected: MetadataIdentity): Pro
   }
 }
 
-async function removeAdministrativeRecord(candidate: AdministrativePruneCandidate): Promise<void> {
+async function removeAdministrativeRecord(
+  candidate: AdministrativePruneCandidate,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted();
   const expected = administrativeIdentities.get(candidate);
   if (!expected) throw new GitWorktreeError(`Git metadata identity was not captured for ${candidate.id}.`);
   const source = candidate.administrativePath;
@@ -829,6 +879,7 @@ async function removeAdministrativeRecord(candidate: AdministrativePruneCandidat
     if (worktreeGitFile && existsSync(worktreeGitFile)) {
       throw new Error(`worktree ${worktreePath} became valid before metadata removal`);
     }
+    signal?.throwIfAborted();
     await rename(source, tombstone);
     moved = true;
     if (worktreeGitFile && existsSync(worktreeGitFile)) {
@@ -836,6 +887,14 @@ async function removeAdministrativeRecord(candidate: AdministrativePruneCandidat
       moved = false;
       throw new Error(`worktree ${worktreePath} became valid while claiming metadata`);
     }
+    if (signal?.aborted) {
+      // Claiming metadata is reversible; finish rollback without the cancelled signal.
+      if (!existsSync(source)) {
+        await rename(tombstone, source);
+        moved = false;
+      }
+      signal.throwIfAborted();
+    }
     await removeMetadataTree(tombstone, expected);
   } catch (error: unknown) {
     const retainedPath =
@@ -844,9 +903,9 @@ async function removeAdministrativeRecord(candidate: AdministrativePruneCandidat
       error instanceof MetadataDeletionRetainedError && error.outcomeUnknown
         ? " Metadata removal outcome is unknown."
         : "";
-    throw new GitWorktreeError(
-      `Git administrative metadata removal failed for ${candidate.id}${retainedPath ? `; retained at ${retainedPath}` : ""}.${outcomeWarning} ${formatError(error)}`,
-    );
+    const message = `Git administrative metadata removal failed for ${candidate.id}${retainedPath ? `; retained at ${retainedPath}` : ""}.${outcomeWarning} ${formatError(error)}`;
+    if (retainedPath || outcomeWarning) throw new WorktreeRecoveryError(message);
+    throw new GitWorktreeError(message);
   }
 }
 function sameAdministrativeCandidate(left: AdministrativePruneCandidate, right: AdministrativePruneCandidate): boolean {
@@ -959,7 +1018,7 @@ export async function pruneWorktrees(
       const result = await runGit(pi, ["worktree", "prune", "--verbose"], cwd, signal, GIT_MUTATION_TIMEOUT_MS);
       return combineOutput(result);
     }
-    for (const candidate of candidates) await removeAdministrativeRecord(candidate);
+    for (const candidate of candidates) await removeAdministrativeRecord(candidate, signal);
     return candidates.map((candidate) => `Removed ${candidate.id}`).join("\n");
   };
   return lockHeld ? operation() : withWorktreeMutationLock(cwd, operation, signal);
@@ -1050,7 +1109,10 @@ async function runGitAllowFailure(
   timeout = GIT_TIMEOUT_MS,
 ): Promise<ExecResult> {
   try {
-    return await pi.exec("git", args, { cwd, signal, timeout });
+    signal?.throwIfAborted();
+    const result = await pi.exec("git", args, { cwd, signal, timeout });
+    signal?.throwIfAborted();
+    return result;
   } catch (error) {
     const message = formatError(error);
     if (/\bENOENT\b|not found/i.test(message)) {

package/src/safe-remove.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { lstat, readdir, rename, rmdir, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { moveWorktree, removeWorktreeMetadata, withWorktreeMutationLock } from "./git.js";
+import { moveWorktree, removeWorktreeMetadata, WorktreeRecoveryError, withWorktreeMutationLock } from "./git.js";
 
 interface TreeSnapshot {
   kind: "directory" | "leaf";
@@ -265,12 +265,14 @@ export async function removeWorktreeSafely(
       if (signal?.aborted) throw new Error("worktree removal aborted");
       const quarantinePath = join(dirname(path), `.${randomUUID()}.pi-worktree-quarantine`);
       let metadataRemoved = false;
+      let metadataOutcomeUnknown = false;
       let moved = false;
       let tombstonePath: string | undefined;
       let moveOutcomeUnknown = false;
       let quarantineReservation: TreeSnapshot | undefined;
       try {
         await validateRegisteredWorktree?.();
+        signal?.throwIfAborted();
         const beforeSnapshot = await snapshotTree(path);
         await moveWorktree(pi, cwd, path, quarantinePath, signal);
         moved = true;
@@ -279,6 +281,7 @@ export async function removeWorktreeSafely(
           throw new Error("worktree changed while entering quarantine");
         }
         await validateQuarantine(quarantinePath);
+        signal?.throwIfAborted();
 
         // Keep the real tree on a guarded tombstone. The registered path is reserved
         // with an exclusive non-directory entry so Git never receives an unprotected
@@ -290,16 +293,22 @@ export async function removeWorktreeSafely(
         if (!sameIdentity(reservedPath, quarantineReservation)) {
           throw new QuarantineRetainedError(quarantinePath, `quarantine reservation changed: ${quarantinePath}`);
         }
-        await removeWorktreeMetadata(
-          pi,
-          cwd,
-          quarantinePath,
-          signal,
-          () => {
-            metadataRemoved = true;
-          },
-          true,
-        );
+        try {
+          await removeWorktreeMetadata(
+            pi,
+            cwd,
+            quarantinePath,
+            signal,
+            () => {
+              metadataRemoved = true;
+            },
+            true,
+          );
+        } catch (error) {
+          // Partial metadata deletion cannot be rolled back by moving the tree.
+          metadataOutcomeUnknown = !metadataRemoved && error instanceof WorktreeRecoveryError;
+          throw error;
+        }
         await releaseQuarantineReservation(quarantinePath, quarantineReservation);
         quarantineReservation = undefined;
         if (!tombstonePath || !(await pathExists(tombstonePath))) {
@@ -309,6 +318,9 @@ export async function removeWorktreeSafely(
             true,
           );
         }
+        // Once metadata is committed, cancellation retains the recovery tree
+        // rather than beginning a fresh filesystem deletion.
+        signal?.throwIfAborted();
         await removeSnapshot(tombstonePath, snapshot, beforeDeleteEntry);
       } catch (error: unknown) {
         if (!tombstonePath && !metadataRemoved) {
@@ -332,11 +344,11 @@ export async function removeWorktreeSafely(
         }
         const primaryError = reservationError ?? error;
         if (moveOutcomeUnknown) {
-          throw new Error(
+          throw new WorktreeRecoveryError(
             `Git worktree move outcome is unknown; inspect ${path} and ${quarantinePath} before retrying: ${errorDetail(primaryError)}`,
           );
         }
-        if (moved && !metadataRemoved) {
+        if (moved && !metadataRemoved && !metadataOutcomeUnknown) {
           let restoreError: unknown = reservationError;
           let restored = false;
           if (!reservationError) {
@@ -361,16 +373,19 @@ export async function removeWorktreeSafely(
               : tombstonePath && (await pathExists(tombstonePath))
                 ? tombstonePath
                 : quarantinePath;
-          throw new Error(
+          throw new WorktreeRecoveryError(
             `Git worktree removal failed: ${errorDetail(primaryError)}; quarantine retained at ${retainedPath}${
               restoreError ? ` (${errorDetail(restoreError)})` : ". The original path was recreated."
             }`,
           );
         }
-        if (metadataRemoved && tombstonePath) {
+        if ((metadataRemoved || metadataOutcomeUnknown) && tombstonePath) {
+          const metadataStatus = metadataRemoved
+            ? "Worktree metadata was removed"
+            : "Worktree metadata outcome is unknown";
           if (primaryError instanceof QuarantineRetainedError && primaryError.outcomeUnknown) {
-            throw new Error(
-              `Worktree metadata was removed, but quarantine outcome is unknown: ${errorDetail(primaryError)}`,
+            throw new WorktreeRecoveryError(
+              `${metadataStatus}, but quarantine outcome is unknown: ${errorDetail(primaryError)}`,
             );
           }
           const retainedPath =
@@ -380,8 +395,8 @@ export async function removeWorktreeSafely(
                 ? tombstonePath
                 : undefined;
           if (retainedPath) {
-            throw new Error(
-              `Worktree metadata was removed, but quarantine was retained at ${retainedPath}: ${errorDetail(primaryError)}`,
+            throw new WorktreeRecoveryError(
+              `${metadataStatus}, but quarantine was retained at ${retainedPath}: ${errorDetail(primaryError)}`,
             );
           }
         }

package/src/session.ts

@@ -12,7 +12,9 @@ export async function switchToWorktree(
 ): Promise<WorktreeSwitchResult> {
   let sessionPath: string | undefined;
   try {
+    ctx.signal?.throwIfAborted();
     sessionPath = createTargetSession(ctx, targetPath);
+    ctx.signal?.throwIfAborted();
     const result = await ctx.switchSession(sessionPath, {
       withSession: async (replacementCtx) => {
         replacementCtx.ui.notify(stripTerminalControls(`Switched Pi workspace to ${targetPath}.`), "info");

package/src/settings.ts

@@ -33,8 +33,8 @@ export interface SettingsFileOperations {
 export interface WorktreeSettingsRuntime {
   get(): Readonly<WorktreeSettingsState>;
   getPath(): string;
-  reload(): Promise<Readonly<WorktreeSettingsState>>;
-  save(configuredRoot: string | undefined): Promise<Readonly<WorktreeSettingsState>>;
+  reload(signal?: AbortSignal): Promise<Readonly<WorktreeSettingsState>>;
+  save(configuredRoot: string | undefined, signal?: AbortSignal): Promise<Readonly<WorktreeSettingsState>>;
   flush?(): Promise<void>;
 }
 
@@ -153,18 +153,22 @@ export async function saveWorktreeSettings(
   configuredRoot: string | undefined,
   path = settingsFilePath(),
   operations: Partial<SettingsFileOperations> = {},
+  signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
+  signal?.throwIfAborted();
   const nextDocument = { ...document };
   if (configuredRoot === undefined) delete nextDocument.worktreeRoot;
   else nextDocument.worktreeRoot = configuredRoot;
 
   await mkdir(dirname(path), { recursive: true });
+  signal?.throwIfAborted();
   const temporaryPath = temporaryFilePath(path);
   try {
     await (operations.write ?? DEFAULT_FILE_OPERATIONS.write)(
       temporaryPath,
       `${JSON.stringify(nextDocument, null, 2)}\n`,
     );
+    signal?.throwIfAborted();
     await (operations.rename ?? DEFAULT_FILE_OPERATIONS.rename)(temporaryPath, path);
     return nextDocument;
   } catch (error) {
@@ -202,9 +206,11 @@ export function createWorktreeSettingsRuntime(options: RuntimeOptions = {}): Wor
     async flush() {
       await operationQueue;
     },
-    reload() {
+    reload(signal) {
       return enqueue(async () => {
+        signal?.throwIfAborted();
         const loaded = await loadWorktreeSettings(getPath(), home, platform);
+        signal?.throwIfAborted();
         if (loaded.kind === "invalid") {
           state = { ...state, warning: loaded.warning, canSave: false };
           return Object.freeze({ ...state });
@@ -213,8 +219,9 @@ export function createWorktreeSettingsRuntime(options: RuntimeOptions = {}): Wor
         return Object.freeze({ ...state });
       });
     },
-    save(configuredRoot) {
+    save(configuredRoot, signal) {
       return enqueue(async () => {
+        signal?.throwIfAborted();
         if (!state.canSave) {
           throw new Error(`Fix the pi-worktree settings file at ${getPath()} before changing it.`);
         }
@@ -223,11 +230,14 @@ export function createWorktreeSettingsRuntime(options: RuntimeOptions = {}): Wor
             ? defaultWorktreeRoot(home, platform)
             : resolveWorktreeRoot(configuredRoot, home, platform);
         const latest = await loadWorktreeSettings(getPath(), home, platform);
+        signal?.throwIfAborted();
         if (latest.kind === "invalid") {
           state = { ...state, warning: latest.warning, canSave: false };
           throw new Error(`Fix the pi-worktree settings file at ${getPath()} before changing it.`);
         }
-        await saveWorktreeSettings(latest.document ?? {}, configuredRoot, getPath(), options.operations);
+        await saveWorktreeSettings(latest.document ?? {}, configuredRoot, getPath(), options.operations, signal);
+        // Successful atomic publication commits the save, even if its UI owner
+        // retired while rename was pending. Keep same-session consumers in sync.
         state = {
           effectiveRoot,
           source: configuredRoot === undefined ? "default" : "user",

package/src/worktree.ts

@@ -18,6 +18,15 @@ export default function worktreeExtension(pi: ExtensionAPI, options: WorktreeExt
     };
   });
 
+  const closeCommands = () => {
+    sessionGeneration += 1;
+    menuController.abort(new DOMException("Worktree navigation started", "AbortError"));
+    menuController = new AbortController();
+  };
+  pi.on("session_before_switch", () => closeCommands());
+  pi.on("session_before_tree", () => closeCommands());
+  pi.on("session_tree", () => closeCommands());
+
   pi.on("session_start", async (_event, ctx) => {
     const generation = ++sessionGeneration;
     menuController.abort(new DOMException("Worktree session replaced", "AbortError"));