@herbertgao/pi-subagents 0.17.0 → 0.18.0

package/src/worktree.ts

@@ -4,13 +4,17 @@
  * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
  * On completion, if no changes were made, the worktree is cleaned up.
  * If changes exist, a branch is created and returned in the result.
+ *
+ * Every git call goes through `pi.exec` (async) rather than `execFileSync`: a
+ * worktree copy can take seconds, and a session that spawns several isolated
+ * agents at once would otherwise serialize them all on the TUI's event loop.
  */
 
-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 type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 
 export interface WorktreeInfo {
   /** Absolute path to the worktree directory (the copied repo's root). */
@@ -49,49 +53,61 @@ export function isWorktreeIsolationEnabled(): boolean {
 }
 
 export interface WorktreeCleanupResult {
-  /** Whether changes were found in the worktree. */
+  /** Whether changes were found or may remain after a cleanup failure. */
   hasChanges: boolean
   /** Branch name if changes were committed. */
   branch?: string
-  /** Worktree path if it was kept. */
+  /** Worktree path. On error, the agent's changes remain here for recovery. */
   path?: string
+  /** Cleanup failure. When present, the worktree is deliberately preserved. */
+  error?: string
+}
+
+/**
+ * Run git and return its trimmed stdout, throwing on failure so callers keep
+ * the try/catch control flow `execFileSync` gave them.
+ *
+ * `pi.exec` never rejects — it reports failure in the result — and a command
+ * killed by its timeout comes back as `killed` with an exit code of 0, so both
+ * have to be checked to reproduce `execFileSync`'s "throws on anything but a
+ * clean exit".
+ */
+async function git(
+  pi: ExtensionAPI,
+  cwd: string,
+  args: string[],
+  timeout: number,
+): Promise<string> {
+  const result = await pi.exec("git", args, { cwd, timeout })
+  if (result.killed || result.code !== 0) {
+    throw new Error(
+      result.stderr.trim() ||
+        `git ${args.join(" ")} failed (exit ${result.code})`,
+    )
+  }
+  return result.stdout.trim()
 }
 
 /**
  * Create a temporary git worktree for an agent.
  * Returns the worktree path, or undefined if not in a git repo.
  */
-export function createWorktree(
+export async function createWorktree(
+  pi: ExtensionAPI,
   cwd: string,
   agentId: string,
-): WorktreeInfo | undefined {
+): Promise<WorktreeInfo | undefined> {
   // Verify we're in a git repo with at least one commit (HEAD must exist)
   let baseSha: string
   let subdir: string
   try {
-    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
-      cwd,
-      stdio: "pipe",
-      timeout: 5000,
-    })
-    baseSha = execFileSync("git", ["rev-parse", "HEAD"], {
-      cwd,
-      stdio: "pipe",
-      timeout: 5000,
-    })
-      .toString()
-      .trim()
+    await git(pi, cwd, ["rev-parse", "--is-inside-work-tree"], 5000)
+    baseSha = await git(pi, cwd, ["rev-parse", "HEAD"], 5000)
     // Where cwd sits inside the repo ("" at the root): the agent must work at
     // the same subdirectory inside the copy, or a monorepo-package cwd would
     // silently widen to the whole repo. realpath both sides — git emits
     // resolved paths while cwd may arrive through a symlink (macOS /tmp).
-    const topLevel = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-      cwd,
-      stdio: "pipe",
-      timeout: 5000,
-    })
-      .toString()
-      .trim()
+    const topLevel = await git(pi, cwd, ["rev-parse", "--show-toplevel"], 5000)
     subdir = relative(realpathSync(topLevel), realpathSync(cwd))
   } catch {
     return undefined
@@ -103,11 +119,12 @@ export function createWorktree(
 
   try {
     // Create detached worktree at HEAD
-    execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
+    await git(
+      pi,
       cwd,
-      stdio: "pipe",
-      timeout: 30000,
-    })
+      ["worktree", "add", "--detach", worktreePath, "HEAD"],
+      30000,
+    )
     return {
       path: worktreePath,
       branch,
@@ -125,56 +142,49 @@ export function createWorktree(
  * - If no changes: remove worktree entirely.
  * - If changes exist: create a branch, commit changes, return branch info.
  */
-export function cleanupWorktree(
+export async function cleanupWorktree(
+  pi: ExtensionAPI,
   cwd: string,
   worktree: WorktreeInfo,
   agentDescription: string,
-): WorktreeCleanupResult {
+): Promise<WorktreeCleanupResult> {
   if (!existsSync(worktree.path)) {
     return { hasChanges: false }
   }
 
+  let preservedBranch: string | undefined
   try {
     // Check for uncommitted changes in the worktree
-    const status = execFileSync("git", ["status", "--porcelain"], {
-      cwd: worktree.path,
-      stdio: "pipe",
-      timeout: 30000,
-    })
-      .toString()
-      .trim()
+    const status = await git(
+      pi,
+      worktree.path,
+      ["status", "--porcelain"],
+      10000,
+    )
 
     if (status) {
       // Changes exist — stage, commit, and create a branch
-      execFileSync("git", ["add", "-A"], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 10000,
-      })
-      // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
+      await git(pi, worktree.path, ["add", "-A"], 10000)
+      // Truncate description for commit message (no shell sanitization needed — pi.exec uses argv)
       const safeDesc = agentDescription.slice(0, 200)
       const commitMsg = `pi-agent: ${safeDesc}`
-      execFileSync(
-        "git",
+      await git(
+        pi,
+        worktree.path,
         ["commit", "--no-verify", "--no-gpg-sign", "-m", commitMsg],
-        {
-          cwd: worktree.path,
-          stdio: "pipe",
-          timeout: 10000,
-        },
+        10000,
       )
     } else {
-      const currentSha = execFileSync("git", ["rev-parse", "HEAD"], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 5000,
-      })
-        .toString()
-        .trim()
+      const currentSha = await git(
+        pi,
+        worktree.path,
+        ["rev-parse", "HEAD"],
+        5000,
+      )
 
       if (currentSha === worktree.baseSha) {
         // No changes — remove worktree
-        removeWorktree(cwd, worktree.path)
+        await removeWorktree(pi, cwd, worktree.path)
         return { hasChanges: false }
       }
     }
@@ -183,76 +193,68 @@ export function cleanupWorktree(
     // If the branch already exists, append a suffix to avoid overwriting previous work.
     let branchName = worktree.branch
     try {
-      execFileSync("git", ["branch", branchName], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 5000,
-      })
+      await git(pi, worktree.path, ["branch", branchName], 5000)
     } catch {
       // Branch already exists — use a unique suffix
       branchName = `${worktree.branch}-${Date.now()}`
-      execFileSync("git", ["branch", branchName], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 5000,
-      })
+      await git(pi, worktree.path, ["branch", branchName], 5000)
     }
     // 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)
+    await removeWorktree(pi, cwd, worktree.path)
 
     return {
       hasChanges: true,
       branch: worktree.branch,
       path: worktree.path,
     }
-  } catch {
-    // Best effort cleanup on error
-    try {
-      removeWorktree(cwd, worktree.path)
-    } catch {
-      /* ignore */
+  } catch (error) {
+    // This may be the only copy of the agent's work. Keep it recoverable and
+    // report the path instead of turning a preservation failure into "no changes".
+    return {
+      hasChanges: true,
+      ...(preservedBranch ? { branch: preservedBranch } : {}),
+      path: worktree.path,
+      error: error instanceof Error ? error.message : String(error),
     }
-    return { hasChanges: false }
   }
 }
 
 /**
  * Force-remove a worktree.
  */
-function removeWorktree(cwd: string, worktreePath: string): void {
+async function removeWorktree(
+  pi: ExtensionAPI,
+  cwd: string,
+  worktreePath: string,
+): Promise<void> {
   try {
-    execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
-      cwd,
-      stdio: "pipe",
-      timeout: 10000,
-    })
-  } catch {
-    // If git worktree remove fails, try pruning
+    await git(pi, cwd, ["worktree", "remove", "--force", worktreePath], 10000)
+  } catch (removeError) {
+    // A concurrent remover may have deleted the directory while Git still
+    // returned an error. Prune stale metadata, but report failure if the copy
+    // still exists — callers must not mistake a leaked worktree for success.
     try {
-      execFileSync("git", ["worktree", "prune"], {
-        cwd,
-        stdio: "pipe",
-        timeout: 5000,
-      })
+      await git(pi, cwd, ["worktree", "prune"], 5000)
     } catch {
       /* ignore */
     }
+    if (existsSync(worktreePath)) throw removeError
   }
 }
 
 /**
  * Prune any orphaned worktrees (crash recovery).
  */
-export function pruneWorktrees(cwd: string): void {
+export async function pruneWorktrees(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<void> {
   try {
-    execFileSync("git", ["worktree", "prune"], {
-      cwd,
-      stdio: "pipe",
-      timeout: 5000,
-    })
+    await git(pi, cwd, ["worktree", "prune"], 5000)
   } catch {
     /* ignore */
   }

package/src/xml.ts

@@ -0,0 +1,13 @@
+/**
+ * xml.ts — escaping for the `<task-notification>` payloads.
+ *
+ * A module of its own because both notification builders need it and they sit
+ * on opposite sides of a dependency edge: the agent one lives in `index.ts`,
+ * which imports `workflow/task.ts`, so the workflow one cannot reach back for
+ * it without a cycle.
+ */
+
+/** Escape XML special characters to prevent injection in structured notifications. */
+export function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+}