@signalridge/pi-worktree 1.4.3 → 1.4.5

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.4.5
+### Patch Changes
+
+- c2fd867: Bound stdin Git cancellation and timeout cleanup with owned TERM-to-KILL escalation and a final confirmation deadline. Retain every concurrent unconfirmed handle per cwd/argv key and refuse equivalent replacements while any failed owner remains live; one late exit cannot release another owner's lease. Release retained handle leases on late actual exit without requiring a retry, and preserve captured output and signal-failure diagnostics through GitWorktreeError wrapping.
+- Updated dependencies [c2fd867]
+  - @signalridge/pi-ui@1.4.0
+
+## 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/README.md

@@ -23,6 +23,8 @@ This package is the full interactive worktree manager. It is publishable and sta
 - Always previews stale metadata before pruning it and revalidates the preview after confirmation.
 - Runs Git through argv-based subprocess calls, without interpolating user input into shell commands.
 
+Stdin Git cancellation and timeout use bounded TERM/KILL escalation on the captured process handle. If termination remains unconfirmed, equivalent cwd/argv invocations are blocked until every failed live handle exits, including when multiple invocations were already concurrent. A late exit releases only its own handle; no saved PID is adopted or signaled. Captured output and signal failure diagnostics remain available for recovery.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-worktree",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "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.4.0",
     "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-input.ts

@@ -0,0 +1,178 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import type { ExecResult } from "@earendil-works/pi-coding-agent";
+
+// An unconfirmed process remains owned by its actual handle. Never signal a
+// saved PID or allow an equivalent invocation to replace it while still alive.
+const unconfirmed = new Map<string, Set<ChildProcessWithoutNullStreams>>();
+const TERM_GRACE_MS = 250;
+const CONFIRMATION_MS = 1_000;
+
+type SignalAttempt = { signal: NodeJS.Signals; accepted: boolean; error?: Error };
+
+/** Captured diagnostics without inventing an exit code for an unconfirmed process. */
+export class GitInputError extends Error {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly reason: string;
+  readonly terminationConfirmed: boolean;
+  readonly signals: readonly SignalAttempt[];
+
+  constructor(
+    message: string,
+    stdout: string,
+    stderr: string,
+    reason: string,
+    terminationConfirmed: boolean,
+    signals: readonly SignalAttempt[],
+    cause?: Error,
+  ) {
+    super(message, { cause });
+    this.name = "GitInputError";
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.reason = reason;
+    this.terminationConfirmed = terminationConfirmed;
+    this.signals = [...signals];
+  }
+}
+
+function retainUntilExit(key: string, child: ChildProcessWithoutNullStreams): void {
+  let owners = unconfirmed.get(key);
+  if (!owners) {
+    owners = new Set();
+    unconfirmed.set(key, owners);
+  }
+  owners.add(child);
+  const release = () => {
+    owners.delete(child);
+    if (owners.size === 0 && unconfirmed.get(key) === owners) unconfirmed.delete(key);
+    child.removeListener("exit", release);
+    child.removeListener("close", release);
+  };
+  child.once("exit", release);
+  child.once("close", release);
+  if (child.exitCode !== null || child.signalCode !== null) release();
+}
+
+export function runGitInput(
+  args: string[],
+  cwd: string,
+  input: string,
+  signal?: AbortSignal,
+  timeout = 15_000,
+): Promise<ExecResult> {
+  const key = JSON.stringify([cwd, args]);
+  const previous = unconfirmed.get(key);
+  if (previous) {
+    for (const child of previous) {
+      if (child.exitCode === null && child.signalCode === null) {
+        return Promise.reject(
+          new Error("Previous Git termination is unconfirmed. Check the owned Git process and retry after it exits."),
+        );
+      }
+    }
+    unconfirmed.delete(key);
+  }
+  if (signal?.aborted) return Promise.resolve({ stdout: "", stderr: "", code: 1, killed: true });
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, { cwd, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let stopping = false;
+    let reason = "";
+    let failure: Error | undefined;
+    const signals: SignalAttempt[] = [];
+    const capturedFailure = (message: string, confirmed: boolean, cause?: Error) =>
+      new GitInputError(message, stdout, stderr, reason, confirmed, signals, cause);
+    let escalation: ReturnType<typeof setTimeout> | undefined;
+    let confirmation: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      clearTimeout(deadline);
+      clearTimeout(escalation);
+      clearTimeout(confirmation);
+      signal?.removeEventListener("abort", abort);
+      child.removeListener("error", error);
+      child.removeListener("close", close);
+      child.stdin.removeListener("error", inputError);
+      child.stdout.removeListener("data", output);
+      child.stderr.removeListener("data", diagnostics);
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+    };
+    const finish = (result?: ExecResult, error?: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) reject(error);
+      else if (result) resolve(result);
+    };
+    const sendSignal = (name: NodeJS.Signals) => {
+      try {
+        const accepted = child.kill(name);
+        signals.push({ signal: name, accepted });
+        if (!accepted) failure ??= new Error(`Git did not accept ${name}.`);
+      } catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        signals.push({ signal: name, accepted: false, error: cause });
+        failure ??= cause;
+      }
+    };
+    const stop = (why: string) => {
+      if (settled || stopping) return;
+      stopping = true;
+      reason = why;
+      clearTimeout(deadline);
+      sendSignal("SIGTERM");
+      escalation = setTimeout(() => {
+        if (settled) return;
+        sendSignal("SIGKILL");
+        confirmation = setTimeout(() => {
+          if (settled) return;
+          retainUntilExit(key, child);
+          finish(
+            undefined,
+            capturedFailure(
+              `Git termination could not be confirmed after ${reason}. Check the owned Git process before retrying.${failure ? ` ${failure.message}` : ""}`,
+              false,
+              failure,
+            ),
+          );
+        }, CONFIRMATION_MS);
+      }, TERM_GRACE_MS);
+    };
+    const abort = () => stop("cancellation");
+    const error = (value: Error) => {
+      failure = value;
+      if (child.pid === undefined) finish(undefined, capturedFailure(value.message, true, value));
+      else stop("process failure");
+    };
+    const inputError = (value: NodeJS.ErrnoException) => {
+      if (value.code !== "EPIPE") error(value);
+    };
+    const output = (chunk: string) => {
+      stdout += chunk;
+    };
+    const diagnostics = (chunk: string) => {
+      stderr += chunk;
+    };
+    const close = (code: number | null, closeSignal: NodeJS.Signals | null) => {
+      finish(
+        { stdout, stderr, code: code ?? 1, killed: stopping || closeSignal !== null },
+        failure ? capturedFailure(failure.message, true, failure) : undefined,
+      );
+    };
+    const deadline = setTimeout(() => stop(`${timeout}ms timeout`), timeout);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", output);
+    child.stderr.on("data", diagnostics);
+    child.stdin.on("error", inputError);
+    child.once("error", error);
+    child.once("close", close);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    child.stdin.end(input);
+  });
+}

package/src/git.ts

@@ -1,10 +1,10 @@
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { lstat, readdir, rename, rmdir, unlink } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import type { ExecResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import lockfile from "proper-lockfile";
+import { GitInputError, runGitInput } from "./git-input.ts";
 
 const GIT_TIMEOUT_MS = 15_000;
 const GIT_MUTATION_TIMEOUT_MS = 60_000;
@@ -63,13 +63,27 @@ interface GitExecOptions {
 
 export class GitWorktreeError extends Error {
   readonly args?: readonly string[];
-
-  constructor(message: string, args?: readonly string[]) {
-    super(message);
+  readonly stdout?: string;
+  readonly stderr?: string;
+
+  constructor(message: string, args?: readonly string[], cause?: unknown) {
+    super(message, { cause });
+    if (cause instanceof GitInputError) {
+      this.stdout = cause.stdout;
+      this.stderr = cause.stderr;
+    }
     this.name = "GitWorktreeError";
     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 +390,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 +428,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 +550,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 +869,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 +885,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 +893,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 +909,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 +1024,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 +1115,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)) {
@@ -1159,65 +1227,13 @@ function runGitWithInputAllowFailure(
   if (signal?.aborted) {
     return Promise.resolve({ stdout: "", stderr: "", code: 1, killed: true });
   }
-  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,
-    });
-    let stdout = "";
-    let stderr = "";
-    let killed = false;
-    let settled = false;
-    const finish = (result: ExecResult) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeoutHandle);
-      signal?.removeEventListener("abort", stop);
-      resolveResult(result);
-    };
-    const fail = (error: unknown) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeoutHandle);
-      signal?.removeEventListener("abort", stop);
-      child.kill();
-      const message = formatError(error);
-      reject(
-        /\bENOENT\b|not found/i.test(message)
-          ? new GitWorktreeError("Git executable was not found. Install Git and retry.", args)
-          : new GitWorktreeError(`Could not start git ${args.slice(0, 2).join(" ")}: ${message}`, args),
-      );
-    };
-    const stop = () => {
-      killed = true;
-      child.kill();
-    };
-    const timeoutHandle = setTimeout(stop, timeout);
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk: string) => {
-      stdout += chunk;
-    });
-    child.stderr.on("data", (chunk: string) => {
-      stderr += chunk;
-    });
-    child.stdin.on("error", (error) => {
-      if (!isNodeError(error) || error.code !== "EPIPE") fail(error);
-    });
-    child.once("error", fail);
-    child.once("close", (code, closeSignal) => {
-      finish({
-        stdout,
-        stderr,
-        code: code ?? 1,
-        killed: killed || closeSignal !== null,
-      });
-    });
-    signal?.addEventListener("abort", stop, { once: true });
-    if (signal?.aborted) stop();
-    child.stdin.end(input);
+  // ExtensionAPI.exec has no stdin channel. This local argv-only owner bounds
+  // both cancellation and timeout cleanup without changing native Git settings.
+  return runGitInput(args, cwd, input, signal, timeout).catch((error: unknown) => {
+    const message = formatError(error);
+    throw /\bENOENT\b|not found/i.test(message)
+      ? new GitWorktreeError("Git executable was not found. Install Git and retry.", args, error)
+      : new GitWorktreeError(`git ${args.slice(0, 2).join(" ")}: ${message}`, args, error);
   });
 }
 

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"));