@herbertgao/pi-extensions 2026.9.9 → 2026.9.11

package/node_modules/@herbertgao/pi-subagents/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/node_modules/@herbertgao/pi-subagents/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;")
+}

package/node_modules/@herbertgao/resume-from/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/resume-from",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Continue a coding session in a different agent, or a different profile.",
   "keywords": [
     "pi-package",

package/node_modules/@herbertgao/sol-pi/README.md

@@ -56,16 +56,16 @@ Read the [SoL-Pi blog](https://nvlabs.github.io/SoL-Pi/) for a deeper look at th
 
 ### Requirements
 
-- Node.js 22.19 or newer
+- Node.js 24 or newer
 - npm
-- `@earendil-works/pi-coding-agent` 0.84.2
+- `@earendil-works/pi-coding-agent` 0.85.1
 
 ### Install
 
 Install the tested Pi release:
 
 ```bash
-npm install --global @earendil-works/pi-coding-agent@0.84.2
+npm install --global @earendil-works/pi-coding-agent@0.85.1
 ```
 
 Then install SoL-Pi directly from [NVlabs/SoL-Pi](https://github.com/NVlabs/SoL-Pi):

package/node_modules/@herbertgao/sol-pi/THIRD_PARTY_NOTICES.md

@@ -8,10 +8,10 @@ The following packages are supplied by the user's Pi installation and retain the
 
 | Package | Development-tested version | License | Source |
 | --- | ---: | --- | --- |
-| `@earendil-works/pi-agent-core` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
-| `@earendil-works/pi-ai` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
-| `@earendil-works/pi-coding-agent` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
-| `@earendil-works/pi-tui` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-agent-core` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-ai` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-coding-agent` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-tui` | 0.85.1 | MIT | <https://github.com/earendil-works/pi> |
 | `typebox` | 1.3.7 | MIT | <https://github.com/sinclairzx81/typebox> |
 
 ## Development-only dependencies

package/node_modules/@herbertgao/sol-pi/agents-install.md

@@ -7,7 +7,7 @@ Installation and configuration are complete only when Pi remains unmodified, the
 ## Rules
 
 - Do not modify, patch, fork, or vendor upstream Pi. SoL-Pi must load as a standalone extension through Pi's public package interface.
-- Use Node.js 22.19 or newer and the tested Pi release `@earendil-works/pi-coding-agent@0.84.2`. Treat a different Pi version as a compatibility change and rerun the full suite before using it.
+- Use Node.js 24 or newer and the tested Pi release `@earendil-works/pi-coding-agent@0.85.1`. Treat a different Pi version as a compatibility change and rerun the full suite before using it.
 - Do not clean, reset, switch, or overwrite unrelated repository changes.
 - Do not print, log, commit, upload, or include any secret in a command line. Check only whether a credential is present.
 - Keep SoL-Pi settings in `sol-pi.json`. The Evidence-Preserving Reducer provider/model route is a SoL-Pi setting; provider URLs, credentials, the main agent model, and shell behavior remain Pi settings.
@@ -35,7 +35,7 @@ node --version
 npm --version
 ```
 
-Require Node.js 22.19 or newer. Install from the lockfile and run the source checks:
+Require Node.js 24 or newer. Install from the lockfile and run the source checks:
 
 ```bash
 npm ci --ignore-scripts
@@ -54,11 +54,11 @@ Stop if any command fails. Do not hide a failure with `|| true` or replace `npm
 Install the tested Pi release without changing its source:
 
 ```bash
-npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.84.2
+npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.85.1
 pi --version
 ```
 
-Require `pi --version` to report `0.84.2`.
+Require `pi --version` to report `0.85.1`.
 
 For a project-local registration, run this from `target_project` and substitute the resolved absolute `sol_pi_root`:
 

package/node_modules/@herbertgao/sol-pi/docs/compatibility.md

@@ -1,6 +1,6 @@
 # Pi Compatibility
 
-SoL-Pi is developed and tested against `@earendil-works/pi-coding-agent` 0.84.2. Its public API surface is also type-checked and exercised against Pi 0.81.1, the base used by the original Pi fork. The runtime range is deliberately expressed as a peer dependency because Pi owns installation and upgrade of its packages.
+SoL-Pi is developed and tested against `@earendil-works/pi-coding-agent` 0.85.1. Its public API surface is also type-checked and exercised against Pi 0.81.1, the base used by the original Pi fork. The runtime range is deliberately expressed as a peer dependency because Pi owns installation and upgrade of its packages.
 
 SoL-Pi imports only public package exports:
 
@@ -31,7 +31,7 @@ ObservationPack changes only the messages projected through the public `context`
 
 The reducer handles public `tool_result` events and resolves the configured reducer provider/model through Pi's model registry before calling `ExtensionContext.modelRegistry.complete()` when available. For the Pi 0.81.1 fork, which exposes no registry `complete()` method, it resolves authentication for that reducer model through `getApiKeyAndHeaders()` and calls the shared `@earendil-works/pi-ai/compat` completion API. The reducer preserves the original result whenever the configured reducer model is unavailable or eligibility, model-call, schema, source-hash, exact-quote, size, or likely-secret checks fail.
 
-All persistent paths use `SessionManager.getSessionDir()` and `getSessionId()`, which are present in both the fork and Pi 0.84.2. SoL-Pi creates no configurable storage-path surface.
+All persistent paths use `SessionManager.getSessionDir()` and `getSessionId()`, which are present in both the fork and Pi 0.85.1. SoL-Pi creates no configurable storage-path surface.
 
 The unpublished shared artifact layout is not read or migrated. Each session starts from its own `<sessionDir>/sol-pi/<sessionId>/` directory.
 
@@ -41,13 +41,13 @@ Online Context Compact uses ordinary public `context` and `before_provider_reque
 
 Before selecting or executing a boundary compaction, it also checks the optional `Symbol.for("pi-subagents:manager")` registry exposed by `pi-subagents`. A running top-level subagent, or an unreadable registry, suppresses that compaction rather than risking a context rewrite during delegated work. When the registry is absent, the check is a no-op.
 
-Pi does not expose its active retained-tail compaction setting through the public extension context. The standalone extension therefore uses the documented Pi 0.84.2 default of 20,000 tokens for its economic estimate. Its programmatic factory accepts an explicit matching value for a non-default Pi setting.
+Pi does not expose its active retained-tail compaction setting through the public extension context. The standalone extension therefore uses the documented Pi 0.85.1 default of 20,000 tokens for its economic estimate. Its programmatic factory accepts an explicit matching value for a non-default Pi setting.
 
-Pi 0.84.2's `ExtensionContext.compact()` aborts the active agent before it summarizes, and `agent_settled` fires only once a whole run has drained every turn, retry, auto-compaction, and queued continuation. A plan boundary that selects compaction therefore saves its plan and progress state, calls `ExtensionContext.abort()` to stop the run, and runs compaction from the `agent_settled` that stop produces. The handler awaits the compaction's own `onComplete`/`onError` callbacks. On success, the extension sends a hidden reminder through public `ExtensionAPI.sendMessage()` with `triggerTurn: true`, so Pi starts a new turn against the compacted context and rebuilds the plan even when the native summary omits that instruction.
+Pi 0.85.1's `ExtensionContext.compact()` aborts the active agent before it summarizes, and `agent_settled` fires only once a whole run has drained every turn, retry, auto-compaction, and queued continuation. A plan boundary that selects compaction therefore saves its plan and progress state, calls `ExtensionContext.abort()` to stop the run, and runs compaction from the `agent_settled` that stop produces. The handler awaits the compaction's own `onComplete`/`onError` callbacks. On success, the extension sends a hidden reminder through public `ExtensionAPI.sendMessage()` with `triggerTurn: true`, so Pi starts a new turn against the compacted context and rebuilds the plan even when the native summary omits that instruction.
 
 A settlement barrier keeps the original `agent_settled` dispatch open until the triggered continuation settles. Print- and JSON-mode processes therefore complete the compact-and-continue sequence within the same Pi invocation; an outer driver does not need to resume the session or send `Continue working`. This continuation is armed only by a successful boundary compaction. Cancelling or exiting does not schedule one. A Pi build that never emits `agent_settled` starts no boundary compaction.
 
-Pi 0.84.2 does not return a promise from `ExtensionAPI.sendMessage()`. The barrier is therefore verified for standalone SoL-Pi and depends on Pi starting the requested turn synchronously. A later-loaded third-party extension that performs long asynchronous work in its own `agent_settled` handler is outside this guarantee and needs an integration test with that extension set.
+Pi 0.85.1 does not return a promise from `ExtensionAPI.sendMessage()`. The barrier is therefore verified for standalone SoL-Pi and depends on Pi starting the requested turn synchronously. A later-loaded third-party extension that performs long asynchronous work in its own `agent_settled` handler is outside this guarantee and needs an integration test with that extension set.
 
 Pi reports the session as idle while an extension-requested manual compaction is running. SoL-Pi cancels `session_before_tree` during that interval to prevent tree navigation from moving the active leaf underneath the compaction. Navigation works normally after the compaction callback settles.
 
@@ -57,7 +57,7 @@ The standalone entry passes `cacheWriteReadRatio` from `sol-pi.json` directly in
 
 ## Interactive TUI
 
-The lightning savings treatment uses Pi 0.84.2's public `renderCall`,
+The lightning savings treatment uses Pi 0.85.1's public `renderCall`,
 `renderResult`, `ctx.ui.notify()`, and keyed `ctx.ui.setStatus()` APIs. It checks
 `ctx.mode === "tui"` rather than `ctx.hasUI`, because RPC mode also reports UI
 support. The renderer therefore changes only the interactive terminal display;

package/node_modules/@herbertgao/sol-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/sol-pi",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Token-efficient context and tool extensions for Pi, maintained from NVlabs/SoL-Pi.",
   "keywords": [
     "pi-package",
@@ -59,7 +59,7 @@
     "vitest": "^4.0.18"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24"
   },
   "pi": {
     "extensions": [