@signalridge/pi-subagents 1.15.0 → 1.15.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.15.1
+### Patch Changes
+
+- 4d37546: Retain worktree contents and Git registration when preservation fails, verify directory removal and deregistration before reporting cleanup success, and replace destructive recovery advice with inspection and save guidance. Report the preservation branch if removal is refused. Preserve missing-checkout registrations for detached HEAD, reflog, and index recovery, using metadata-only Git recovery locks across shutdown, reload, and later pruning, including when execution or descendant pins prevent checkout cleanup. Preserve existing locks, report lock failures, and defer all global orphan pruning while any worktree cleanup remains unresolved. Quote recovery paths literally so shell metacharacters cannot execute.
+
 ## 1.15.0
 ### Minor Changes
 

package/README.md

@@ -912,7 +912,7 @@ pi.events.emit("subagents:rpc:spawn", {
 
 `options.model` accepts either a `Model` object (e.g. `ctx.model`) or a `"provider/modelId"` string — strings are resolved against `ctx.modelRegistry` at the RPC boundary, so cross-extension callers can forward serializable values without losing auth context.
 
-`options.cwd` (absolute path to an existing directory — anything else returns an error envelope; `null` means unset) runs the agent in a different working directory than the parent session. Its tools operate there and the prompt's environment block describes it, but **`.pi` config still loads from the parent session's project** — the target directory's `.pi` extensions never execute, and its agents/skills/settings are not picked up. Combined with `isolation: "worktree"`, the worktree is created *from* the target directory's repo, the agent works at the equivalent subdirectory inside the copy (a monorepo-package cwd stays scoped to that package), and the resulting `pi-agent-*` branch lands in that repo — the completion message names it. On session end, worktree registrations are pruned in every repo that received one; only a hard crash can leave a stale entry (then: `git worktree prune` in the target repo). Agents with `memory:` keep reading/writing the parent project's memory.
+`options.cwd` (absolute path to an existing directory — anything else returns an error envelope; `null` means unset) runs the agent in a different working directory than the parent session. Its tools operate there and the prompt's environment block describes it, but **`.pi` config still loads from the parent session's project** — the target directory's `.pi` extensions never execute, and its agents/skills/settings are not picked up. Combined with `isolation: "worktree"`, the worktree is created *from* the target directory's repo, the agent works at the equivalent subdirectory inside the copy (a monorepo-package cwd stays scoped to that package), and the resulting `pi-agent-*` branch lands in that repo — the completion message names it. On session end, cleanup is attempted in every repo that received a worktree. Failed preservation or removal retains the worktree reference and recovery diagnostics; inspect and save its contents before repairing Git or retrying cleanup. Agents with `memory:` keep reading/writing the parent project's memory.
 
 ### Stop
 
@@ -976,7 +976,7 @@ The agent gets a full, isolated copy of the repository. On completion:
 The automatic preservation commit uses `--no-verify`, so local pre-commit hooks can't block it — the commit is local-only and never pushed, and pre-push/server-side hooks still apply.
 
 If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `Agent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint. Initialize git and commit at least once, or omit `isolation`.
-If cleanup cannot be confirmed, the result keeps the worktree path and includes a bounded diagnostic plus recovery commands. Cleanup first tries `git worktree remove --force`; when that fails, pi-subagents only uses direct filesystem removal for a verified package-created temporary path, then prunes and verifies Git's worktree registration. It never recursively removes an arbitrary caller-supplied path automatically. At session shutdown, failed removals are retried deepest-first without blocking siblings or ancestors; late provider continuations are quarantined, and remaining failures are reported as immutable path- and repository-specific diagnostics via `getWorktreeCleanupFailures()`.
+If status, commit, or both preservation-branch attempts fail, cleanup retains the checkout and its Git registration; it does not attempt destructive error cleanup. The result keeps the worktree path, diagnostic, and non-destructive inspection/recovery guidance. Inspect and copy the checkout, including untracked files, before repairing Git or retrying cleanup. After preservation (or confirming no changes), cleanup uses `git worktree remove --force` without overriding Git worktree locks and reports success only after verifying both directory removal and deregistration. A missing checkout with a retained registration reports failure because its detached HEAD, reflog, or index may still be recoverable. A metadata-only helper locks an observed missing registration with a fixed recovery reason so later sessions and Git pruning retain it, even when provider, native-input, child-teardown, or descendant pins prevent checkout cleanup. Existing locks are preserved and never automatically unlocked. Failure to establish a recovery lock is reported explicitly and requires manual recovery. A repeated call after verified directory removal and deregistration is a successful no-op. A removal failure reports the preservation branch when one was created; no direct filesystem-removal fallback runs. At session shutdown, failed removals are retried deepest-first while dependent ancestors remain pinned, and global orphan pruning across all targets is deferred while any worktree reference remains attached; late provider continuations are quarantined, and remaining failures are reported as immutable path- and repository-specific diagnostics via `getWorktreeCleanupFailures()`.
 
 The child prompt also states that the temporary worktree is the only writable checkout and names the original base repository as off-limits. This prevents inherited parent instructions from sending the agent back into the shared tree.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",

package/src/agent-manager.ts

@@ -8,7 +8,7 @@
  */
 
 import { createHash, randomUUID } from "node:crypto";
-import { realpathSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type {
@@ -66,6 +66,7 @@ import {
   cleanupWorktreeAsync,
   createWorktree,
   isWorktreeIsolationEnabled,
+  protectMissingWorktree,
   pruneWorktrees,
   pruneWorktreesAsync,
   type WorktreeCleanupResult,
@@ -266,9 +267,10 @@ function worktreeRecoveryCommands(
   const c = cwd ? shellQuote(cwd) : "'.'";
   const p = path ? shellQuote(path) : "''";
   return Object.freeze([
-    `git -C ${c} worktree remove --force ${p}`,
-    `rm -rf -- ${p}`,
-    `git -C ${c} worktree prune`,
+    `git -C ${c} worktree list --porcelain`,
+    `git -C ${p} status --short`,
+    `git -C ${p} log -5 --oneline`,
+    "# Inspect and copy the checkout (including untracked files) to a safe location before repairing Git or retrying cleanup.",
   ]);
 }
 
@@ -3719,13 +3721,23 @@ export class AgentManager {
           sameFilesystemPath(child.worktree.repoRoot, worktree.path)) ||
           child.worktree === undefined),
     );
+    let recoveryDiagnostic: string | undefined;
+    if (!existsSync(worktree.path)) {
+      try {
+        // Metadata-only protection is safe before quiescence. Never run actual
+        // checkout cleanup just to retain recovery across manager replacement.
+        recoveryDiagnostic = protectMissingWorktree(worktree.repoRoot, worktree.path);
+      } catch (error) {
+        recoveryDiagnostic = error instanceof Error ? error.message : String(error);
+      }
+    }
+    const pinnedDiagnostic = diagnostic ??
+      `Worktree cleanup is pinned because descendant ${dependent?.id ?? "agent"} still depends on ${worktree.path}`;
     const result: WorktreeCleanupResult = {
       hasChanges: false,
       path: worktree.path,
       cleanupSucceeded: false,
-      cleanupDiagnostic:
-        diagnostic ??
-        `Worktree cleanup is pinned because descendant ${dependent?.id ?? "agent"} still depends on ${worktree.path}`,
+      cleanupDiagnostic: recoveryDiagnostic ? `${pinnedDiagnostic} ${recoveryDiagnostic}` : pinnedDiagnostic,
       recoveryCommands: worktreeRecoveryCommands(
         worktree.repoRoot,
         worktree.path,
@@ -4669,11 +4681,16 @@ export class AgentManager {
       }
     };
     const pruneRepositories = async (): Promise<void> => {
+      // Defer all global orphan pruning while any worktree remains attached:
+      // its registration may hold recoverable HEAD/reflog/index data. Paths
+      // cannot establish Git identity; cwd may be a subdirectory or another
+      // linked checkout of the same repository as a retained failure.
+      if (orderedRecords.some((record) => record.worktree !== undefined)) return;
       await Promise.all([...reposToPrune].map((repo) => pruneRepository(repo)));
     };
 
-    // Pruning after the first pass can release stale child registrations. Retry
-    // only records whose worktree reference remains, still deepest-first.
+    // Retry retained worktrees deepest-first even when global orphan pruning
+    // is deferred. Individual cleanup of siblings remains independent.
     await pruneRepositories();
     for (const record of orderedRecords) {
       if (record.worktree) await attemptCleanup(record);

package/src/worktree.ts

@@ -10,7 +10,7 @@ import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 
 export interface WorktreeInfo {
   /** Absolute path to the worktree directory (the copied repo's root). */
@@ -65,6 +65,10 @@ export interface WorktreeCleanupResult {
   recoveryCommands?: readonly string[] | string[];
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 /**
  * Create a temporary git worktree for an agent.
  * Returns the worktree path, or undefined if not in a git repo.
@@ -119,12 +123,15 @@ export function cleanupWorktree(
   worktree: WorktreeInfo,
   agentDescription: string,
 ): WorktreeCleanupResult {
-  if (!existsSync(worktree.path)) {
-    return { hasChanges: false, cleanupSucceeded: true };
-  }
-
   let hasChanges = false;
+  let preservedBranch: string | undefined;
   try {
+    if (!existsSync(worktree.path)) {
+      // A vanished directory can still have recoverable detached HEAD/index
+      // state. Only an already-deregistered checkout is a confirmed no-op.
+      removeWorktree(cwd, worktree.path);
+      return { hasChanges: false, cleanupSucceeded: true };
+    }
     // Check for uncommitted changes in the worktree
     const status = execFileSync("git", ["status", "--porcelain"], {
       cwd: worktree.path,
@@ -179,6 +186,7 @@ export function cleanupWorktree(
     }
     // Update branch name in worktree info for the caller
     worktree.branch = branchName;
+    preservedBranch = branchName;
 
     // Remove the worktree (branch persists in main repo)
     removeWorktree(cwd, worktree.path);
@@ -190,17 +198,19 @@ export function cleanupWorktree(
       cleanupSucceeded: true,
     };
   } catch (error) {
-    // Best effort cleanup on error
-    try { removeWorktree(cwd, worktree.path); } catch { /* ignore */ }
+    // Preservation failed or removal was refused. Keep the checkout and Git
+    // registration as recovery references; never remove unpreserved work here.
     return {
       hasChanges,
+      ...(preservedBranch ? { branch: preservedBranch } : {}),
       path: worktree.path,
       cleanupSucceeded: false,
       cleanupDiagnostic: error instanceof Error ? error.message : String(error),
       recoveryCommands: [
-        `git -C ${JSON.stringify(cwd)} worktree remove --force ${JSON.stringify(worktree.path)}`,
-        `git -C ${JSON.stringify(cwd)} worktree prune`,
-        `rm -rf -- ${JSON.stringify(worktree.path)}`,
+        `git -C ${shellQuote(cwd)} worktree list --porcelain`,
+        `git -C ${shellQuote(worktree.path)} status --short`,
+        `git -C ${shellQuote(worktree.path)} log -5 --oneline`,
+        "# Inspect and copy the checkout (including untracked files) to a safe location before repairing Git or retrying cleanup.",
       ],
     };
   }
@@ -217,21 +227,59 @@ export async function cleanupWorktreeAsync(
   return cleanupWorktree(cwd, worktree, agentDescription);
 }
 
+function worktreeRegistration(cwd: string, worktreePath: string): string[] | undefined {
+  // Git reports canonical paths (e.g. /private/var on macOS). Resolve the
+  // parent so verification also works after the directory has disappeared.
+  const canonicalPath = join(realpathSync(dirname(worktreePath)), basename(worktreePath));
+  return execFileSync("git", ["worktree", "list", "--porcelain", "-z"], {
+    cwd,
+    stdio: "pipe",
+    timeout: 5000,
+  }).toString().split("\0\0").map((record) => record.split("\0")).find((fields) =>
+    fields.some((field) => field.startsWith("worktree ") && [canonicalPath, resolve(worktreePath)].includes(field.slice(9))),
+  );
+}
+
 /**
- * Force-remove a worktree.
+ * Protect observed missing-checkout metadata, even while execution is pinned.
+ * Only inspects registration and establishes a Git recovery lock; never stages,
+ * commits, removes, or unlocks anything. Lock failures propagate to the owner.
  */
+export function protectMissingWorktree(cwd: string, worktreePath: string): string | undefined {
+  if (existsSync(worktreePath)) return undefined;
+  const registered = worktreeRegistration(cwd, worktreePath);
+  if (!registered) return undefined;
+  // A Git-owned lock survives manager/session replacement. Preserve existing
+  // locks and never automatically unlock them, including after repair/retry.
+  if (!registered.some((field) => field === "locked" || field.startsWith("locked "))) {
+    try {
+      execFileSync("git", ["worktree", "lock", "--reason", "pi-subagents: missing checkout retained for HEAD/index recovery", worktreePath], {
+        cwd,
+        stdio: "pipe",
+        timeout: 5000,
+      });
+    } catch (error) {
+      throw new Error(`Missing worktree recovery registration could not be locked for ${worktreePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return `Worktree checkout is missing; its Git registration remains locked for HEAD/index recovery: ${worktreePath}`;
+}
+
+/** Remove a preserved/unchanged checkout and positively verify deregistration. */
 function removeWorktree(cwd: string, worktreePath: string): void {
-  try {
+  const recoveryDiagnostic = protectMissingWorktree(cwd, worktreePath);
+  if (recoveryDiagnostic) throw new Error(recoveryDiagnostic);
+  if (worktreeRegistration(cwd, worktreePath) || existsSync(worktreePath)) {
+    // One --force permits a preserved dirty checkout, but does not override a
+    // Git worktree lock. Propagate refusal rather than pretending prune fixed it.
     execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
       cwd,
       stdio: "pipe",
       timeout: 10000,
     });
-  } catch {
-    // If git worktree remove fails, try pruning
-    try {
-      execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
-    } catch { /* ignore */ }
+  }
+  if (existsSync(worktreePath) || worktreeRegistration(cwd, worktreePath)) {
+    throw new Error(`Worktree removal was not confirmed for ${worktreePath}`);
   }
 }