@tintinweb/pi-subagents 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-05-07
+
+> **Heads-up — behavior change:**
+> - `isolation: "worktree"` now fails loud (returns an error) instead of silently falling back to the main tree. Affects users running pi in a non-git directory or a fresh repo with no commits.
+
+### Changed
+- **`isolation: "worktree"` now fails loud instead of silently falling back.** Previously when `createWorktree` returned undefined (not a git repo, no commits yet, or `git worktree add` failed), the agent ran in the main `cwd` with a `[WARNING: ...]` block prepended to its prompt — visible only to the LLM, never surfaced to the caller. Now the failure throws a structured error that propagates back to the `Agent` tool response; no agent record is created. Failed scheduled fires are recorded as `lastStatus: "error"` with the reason in the `subagents:scheduled` error event. Queued background spawns whose worktree creation fails when they dequeue are marked terminal-error and don't block the rest of the queue.
+
+### Fixed
+
+- **Headless `pi --print` runs no longer hang or crash after background
+subagents complete.** Cleanup timers no longer keep the process alive, and
+stale completion notifications are treated as best-effort shutdown side
+effects.
+
 ## [0.7.0] - 2026-05-04
 
 > **Heads-up — behavior changes:**

package/README.md

@@ -453,7 +453,7 @@ The agent gets a full, isolated copy of the repository. On completion:
 - **No changes:** worktree is cleaned up automatically
 - **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
 
-If the worktree cannot be created (not a git repo, no commits), the agent falls back to the main working directory with a warning.
+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`.
 
 ## Skill Preloading
 

package/dist/agent-manager.js

@@ -29,6 +29,7 @@ export class AgentManager {
         this.maxConcurrent = maxConcurrent;
         // Cleanup completed agents after 10 minutes (but keep sessions for resume)
         this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+        this.cleanupInterval.unref();
     }
     /** Update the max concurrent background agents limit. */
     setMaxConcurrent(n) {
@@ -64,11 +65,32 @@ export class AgentManager {
             this.queue.push({ id, args });
             return id;
         }
-        this.startAgent(id, record, args);
+        // startAgent can throw (e.g. strict worktree-isolation failure) — clean
+        // up the record so callers don't see an orphan in `listAgents()`.
+        try {
+            this.startAgent(id, record, args);
+        }
+        catch (err) {
+            this.agents.delete(id);
+            throw err;
+        }
         return id;
     }
     /** Actually start an agent (called immediately or from queue drain). */
     startAgent(id, record, { pi, ctx, type, prompt, options }) {
+        // Worktree isolation: try to create a temporary git worktree. Strict —
+        // fail loud if not possible (no silent fallback to main tree). Done
+        // BEFORE state mutation so a throw doesn't leave the record half-running.
+        let worktreeCwd;
+        if (options.isolation === "worktree") {
+            const wt = createWorktree(ctx.cwd, id);
+            if (!wt) {
+                throw new Error('Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+                    'Initialize git and commit at least once, or omit `isolation`.');
+            }
+            record.worktree = wt;
+            worktreeCwd = wt.path;
+        }
         record.status = "running";
         record.startedAt = Date.now();
         if (options.isBackground)
@@ -82,22 +104,7 @@ export class AgentManager {
             detachParentSignal = () => options.signal.removeEventListener("abort", onParentAbort);
         }
         const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
-        // Worktree isolation: create a temporary git worktree if requested
-        let worktreeCwd;
-        let worktreeWarning = "";
-        if (options.isolation === "worktree") {
-            const wt = createWorktree(ctx.cwd, id);
-            if (wt) {
-                record.worktree = wt;
-                worktreeCwd = wt.path;
-            }
-            else {
-                worktreeWarning = "\n\n[WARNING: Worktree isolation was requested but failed (not a git repo, or no commits yet). Running in the main working directory instead.]";
-            }
-        }
-        // Prepend worktree warning to prompt if isolation failed
-        const effectivePrompt = worktreeWarning ? worktreeWarning + "\n\n" + prompt : prompt;
-        const promise = runAgent(ctx, type, effectivePrompt, {
+        const promise = runAgent(ctx, type, prompt, {
             pi,
             model: options.model,
             maxTurns: options.maxTurns,
@@ -162,7 +169,10 @@ export class AgentManager {
             }
             if (options.isBackground) {
                 this.runningBackground--;
-                this.onComplete?.(record);
+                try {
+                    this.onComplete?.(record);
+                }
+                catch { /* ignore completion side-effect errors */ }
                 this.drainQueue();
             }
             return responseText;
@@ -207,7 +217,17 @@ export class AgentManager {
             const record = this.agents.get(next.id);
             if (!record || record.status !== "queued")
                 continue;
-            this.startAgent(next.id, record, next.args);
+            try {
+                this.startAgent(next.id, record, next.args);
+            }
+            catch (err) {
+                // Late failure (e.g. strict worktree-isolation) — surface on the record
+                // so the user/agent can see it via /agents, then keep draining.
+                record.status = "error";
+                record.error = err instanceof Error ? err.message : String(err);
+                record.completedAt = Date.now();
+                this.onComplete?.(record);
+            }
         }
     }
     /**

package/dist/index.js

@@ -235,7 +235,10 @@ export default function (pi) {
         cancelNudge(key);
         pendingNudges.set(key, setTimeout(() => {
             pendingNudges.delete(key);
-            send();
+            try {
+                send();
+            }
+            catch { /* ignore stale completion side-effect errors */ }
         }, delay));
     }
     function cancelNudge(key) {
@@ -830,17 +833,22 @@ Guidelines:
                         rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
                     }
                 };
-                id = manager.spawn(pi, ctx, subagentType, params.prompt, {
-                    description: params.description,
-                    model,
-                    maxTurns: effectiveMaxTurns,
-                    isolated,
-                    inheritContext,
-                    thinkingLevel: thinking,
-                    isBackground: true,
-                    isolation,
-                    ...bgCallbacks,
-                });
+                try {
+                    id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+                        description: params.description,
+                        model,
+                        maxTurns: effectiveMaxTurns,
+                        isolated,
+                        inheritContext,
+                        thinkingLevel: thinking,
+                        isBackground: true,
+                        isolation,
+                        ...bgCallbacks,
+                    });
+                }
+                catch (err) {
+                    return textResult(err instanceof Error ? err.message : String(err));
+                }
                 // Set output file + join mode synchronously after spawn, before the
                 // event loop yields — onSessionCreated is async so this is safe.
                 const joinMode = resolveJoinMode(defaultJoinMode, true);
@@ -925,17 +933,24 @@ Guidelines:
                 streamUpdate();
             }, 80);
             streamUpdate();
-            const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
-                description: params.description,
-                model,
-                maxTurns: effectiveMaxTurns,
-                isolated,
-                inheritContext,
-                thinkingLevel: thinking,
-                isolation,
-                signal,
-                ...fgCallbacks,
-            });
+            let record;
+            try {
+                record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+                    description: params.description,
+                    model,
+                    maxTurns: effectiveMaxTurns,
+                    isolated,
+                    inheritContext,
+                    thinkingLevel: thinking,
+                    isolation,
+                    signal,
+                    ...fgCallbacks,
+                });
+            }
+            catch (err) {
+                clearInterval(spinnerInterval);
+                return textResult(err instanceof Error ? err.message : String(err));
+            }
             clearInterval(spinnerInterval);
             // Clean up foreground agent from widget
             if (fgId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -87,6 +87,7 @@ export class AgentManager {
     this.maxConcurrent = maxConcurrent;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    this.cleanupInterval.unref();
   }
 
   /** Update the max concurrent background agents limit. */
@@ -134,12 +135,35 @@ export class AgentManager {
       return id;
     }
 
-    this.startAgent(id, record, args);
+    // startAgent can throw (e.g. strict worktree-isolation failure) — clean
+    // up the record so callers don't see an orphan in `listAgents()`.
+    try {
+      this.startAgent(id, record, args);
+    } catch (err) {
+      this.agents.delete(id);
+      throw err;
+    }
     return id;
   }
 
   /** Actually start an agent (called immediately or from queue drain). */
   private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
+    // Worktree isolation: try to create a temporary git worktree. Strict —
+    // fail loud if not possible (no silent fallback to main tree). Done
+    // BEFORE state mutation so a throw doesn't leave the record half-running.
+    let worktreeCwd: string | undefined;
+    if (options.isolation === "worktree") {
+      const wt = createWorktree(ctx.cwd, id);
+      if (!wt) {
+        throw new Error(
+          'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+          'Initialize git and commit at least once, or omit `isolation`.',
+        );
+      }
+      record.worktree = wt;
+      worktreeCwd = wt.path;
+    }
+
     record.status = "running";
     record.startedAt = Date.now();
     if (options.isBackground) this.runningBackground++;
@@ -154,23 +178,7 @@ export class AgentManager {
     }
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
-    // Worktree isolation: create a temporary git worktree if requested
-    let worktreeCwd: string | undefined;
-    let worktreeWarning = "";
-    if (options.isolation === "worktree") {
-      const wt = createWorktree(ctx.cwd, id);
-      if (wt) {
-        record.worktree = wt;
-        worktreeCwd = wt.path;
-      } else {
-        worktreeWarning = "\n\n[WARNING: Worktree isolation was requested but failed (not a git repo, or no commits yet). Running in the main working directory instead.]";
-      }
-    }
-
-    // Prepend worktree warning to prompt if isolation failed
-    const effectivePrompt = worktreeWarning ? worktreeWarning + "\n\n" + prompt : prompt;
-
-    const promise = runAgent(ctx, type, effectivePrompt, {
+    const promise = runAgent(ctx, type, prompt, {
       pi,
       model: options.model,
       maxTurns: options.maxTurns,
@@ -235,7 +243,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          this.onComplete?.(record);
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
           this.drainQueue();
         }
         return responseText;
@@ -281,7 +289,16 @@ export class AgentManager {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
       if (!record || record.status !== "queued") continue;
-      this.startAgent(next.id, record, next.args);
+      try {
+        this.startAgent(next.id, record, next.args);
+      } catch (err) {
+        // Late failure (e.g. strict worktree-isolation) — surface on the record
+        // so the user/agent can see it via /agents, then keep draining.
+        record.status = "error";
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt = Date.now();
+        this.onComplete?.(record);
+      }
     }
   }
 

package/src/index.ts

@@ -275,7 +275,7 @@ export default function (pi: ExtensionAPI) {
     cancelNudge(key);
     pendingNudges.set(key, setTimeout(() => {
       pendingNudges.delete(key);
-      send();
+      try { send(); } catch { /* ignore stale completion side-effect errors */ }
     }, delay));
   }
 
@@ -946,17 +946,21 @@ Guidelines:
           }
         };
 
-        id = manager.spawn(pi, ctx, subagentType, params.prompt, {
-          description: params.description,
-          model,
-          maxTurns: effectiveMaxTurns,
-          isolated,
-          inheritContext,
-          thinkingLevel: thinking,
-          isBackground: true,
-          isolation,
-          ...bgCallbacks,
-        });
+        try {
+          id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+            description: params.description,
+            model,
+            maxTurns: effectiveMaxTurns,
+            isolated,
+            inheritContext,
+            thinkingLevel: thinking,
+            isBackground: true,
+            isolation,
+            ...bgCallbacks,
+          });
+        } catch (err) {
+          return textResult(err instanceof Error ? err.message : String(err));
+        }
 
         // Set output file + join mode synchronously after spawn, before the
         // event loop yields — onSessionCreated is async so this is safe.
@@ -1054,17 +1058,23 @@ Guidelines:
 
       streamUpdate();
 
-      const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
-        description: params.description,
-        model,
-        maxTurns: effectiveMaxTurns,
-        isolated,
-        inheritContext,
-        thinkingLevel: thinking,
-        isolation,
-        signal,
-        ...fgCallbacks,
-      });
+      let record: AgentRecord;
+      try {
+        record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+          description: params.description,
+          model,
+          maxTurns: effectiveMaxTurns,
+          isolated,
+          inheritContext,
+          thinkingLevel: thinking,
+          isolation,
+          signal,
+          ...fgCallbacks,
+        });
+      } catch (err) {
+        clearInterval(spinnerInterval);
+        return textResult(err instanceof Error ? err.message : String(err));
+      }
 
       clearInterval(spinnerInterval);