@gotgenes/pi-subagents 1.0.0

package/docs/decisions/0001-deferred-patches.md

@@ -0,0 +1,75 @@
+---
+status: accepted
+date: 2026-05-11
+---
+
+# 0001 — Deferred fork patches and upstream-PR strategy
+
+## Status
+
+Accepted
+
+## Context
+
+This fork was created to land three pieces of work identified during RepOne issue [#442](https://github.com/Tiny-IG-Software/repone/issues/442):
+
+1. **Peer-dep rename** — `@mariozechner/pi-*` → `@earendil-works/pi-*`.
+2. **Patch 2 — Re-activate extension tools post-`bindExtensions`** (Spike 3 finding).
+3. **Patch 3 — Inject `<active_agent>` tag** (Spike 4 finding).
+
+A fourth piece of work was scoped during the same spike round but deferred:
+
+- **Patch 1 — Mirror parent's `additionalExtensionPaths` (and siblings) into the child's `DefaultResourceLoader`** (Spike 2 finding).
+
+This ADR records why Patch 1 was deferred and the strategy for upstream PRs back to [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
+
+## Decision
+
+### Patch 1 is deferred
+
+The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`. The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
+
+During planning for this fork, two implementation constraints surfaced:
+
+1. The parent's `DefaultResourceLoader.additionalExtensionPaths` is **private** — no public getter on `ExtensionContext`.
+2. The parent's CLI flags (e.g., `pi -e <path>`) are parsed in `main.js` and not surfaced through any extension API.
+
+A working patch would have to either:
+
+- Accept new fields in `RunOptions` so callers supply the paths explicitly, **or**
+- Reach into `process.argv` to re-resolve `-e`/`--extensions` flags from the child's perspective.
+
+Neither matches the production need. For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration. The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
+
+We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream. A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
+
+### Upstream PRs are deferred
+
+Patches 2 and 3 are both clearly upstream-mergeable bug fixes — they finish a mirror the upstream fork already started (carrying the parent's session configuration through to the child). The natural place for them is in `tintinweb/pi-subagents` itself.
+
+We defer opening the PRs until **Patches 2 and 3 have been validated end-to-end in production** through at least one milestone of RepOne usage. The reasoning:
+
+1. Production validation is stronger evidence for the upstream maintainer than the spike findings alone.
+2. The patch shapes (especially Patch 2's helper-extraction refactor and Patch 3's exact prepend point) may need adjustment based on real-world behavior; opening PRs prematurely risks needing to amend them under review.
+3. Carrying the fork is low-cost while we iterate; the publishing infrastructure mirrors the other Pi siblings.
+
+A follow-up issue on the RepOne board (linked from #443) tracks the upstream-PR work and the criterion for proceeding.
+
+## Consequences
+
+### Positive
+
+- The fork's diff against upstream stays minimal — three patches plus tooling alignment.
+- We avoid landing a speculative Patch 1 that would need rework if upstream's `ExtensionContext` API changes.
+- We get production evidence before asking the upstream maintainer to review.
+
+### Negative
+
+- The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands. We accept this because no consumer in scope uses that pattern.
+- Patches 2 and 3 stay carried in `@gotgenes/pi-subagents` rather than upstream. Consumers must use this fork (not the upstream package) to get the patches.
+
+### Operational
+
+- A follow-up issue on the RepOne board (linked from this fork's `README.md` "Deviations from upstream" section and from RepOne issue #443) records both deferrals.
+- When upstream PRs are eventually opened, they should be opened separately for Patches 2 and 3 to keep review simple.
+- When Patch 1 is eventually added, it should be a separate ADR in `docs/decisions/` with its own follow-up.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@gotgenes/pi-subagents",
+  "version": "1.0.0",
+  "description": "A pi extension that brings Claude Code-style autonomous sub-agents to pi. Friendly fork of @tintinweb/pi-subagents.",
+  "author": {
+    "name": "Chris Lasher"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gotgenes/pi-subagents.git"
+  },
+  "homepage": "https://github.com/gotgenes/pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/gotgenes/pi-subagents/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": ">=0.74.0"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "croner": "^10.0.1",
+    "nanoid": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.5.0",
+    "markdownlint-cli2": "^0.22.1",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "video": "https://github.com/gotgenes/pi-subagents/raw/main/media/demo.mp4",
+    "image": "https://github.com/gotgenes/pi-subagents/raw/main/media/screenshot.png"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --fix src/ test/",
+    "lint:md": "markdownlint-cli2 '*.md' 'docs/**/*.md'",
+    "lint:md:fix": "markdownlint-cli2 --fix '*.md' 'docs/**/*.md'",
+    "lint:all": "pnpm run lint && pnpm run lint:md",
+    "format": "biome format --write src/ test/",
+    "check": "pnpm run build && pnpm run lint:all && pnpm run test"
+  }
+}

package/prek.toml

@@ -0,0 +1,24 @@
+# Configuration file for `prek`, a git hook framework written in Rust.
+# See https://prek.j178.dev for more information.
+#:schema https://www.schemastore.org/prek.json
+
+[[repos]]
+repo = "builtin"
+hooks = [
+    { id = "trailing-whitespace" },
+    { id = "end-of-file-fixer" },
+    { id = "check-added-large-files" },
+]
+
+[[repos]]
+repo = "local"
+hooks = [
+    { id = "biome", name = "biome", entry = "pnpm exec biome check --files-ignore-unknown=true --no-errors-on-unmatched", language = "system", types_or = ["javascript", "jsx", "ts", "tsx", "json"] },
+]
+
+[[repos]]
+repo = "https://github.com/DavidAnson/markdownlint-cli2"
+rev = "v0.22.1"
+hooks = [
+    { id = "markdownlint-cli2" },
+]

package/release-please-config.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {}
+  },
+  "include-v-in-tag": true,
+  "include-component-in-tag": false,
+  "release-type": "node",
+  "changelog-sections": [
+    { "type": "feat", "section": "Features" },
+    { "type": "fix", "section": "Bug Fixes" },
+    { "type": "perf", "section": "Performance Improvements" },
+    { "type": "revert", "section": "Reverts" },
+    { "type": "docs", "section": "Documentation" },
+    { "type": "style", "section": "Styles", "hidden": true },
+    { "type": "chore", "section": "Miscellaneous Chores" },
+    { "type": "refactor", "section": "Code Refactoring", "hidden": true },
+    { "type": "test", "section": "Tests", "hidden": true },
+    { "type": "build", "section": "Build System", "hidden": true },
+    { "type": "ci", "section": "Continuous Integration", "hidden": true }
+  ]
+}

package/src/agent-manager.ts

@@ -0,0 +1,482 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import { addUsage } from "./usage.js";
+import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
+
+export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentStart = (record: AgentRecord) => void;
+export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
+
+/** Default max concurrent background agents. */
+const DEFAULT_MAX_CONCURRENT = 4;
+
+interface SpawnArgs {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  type: SubagentType;
+  prompt: string;
+  options: SpawnOptions;
+}
+
+interface SpawnOptions {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  /**
+   * Skip the maxConcurrent queue check for this spawn — start immediately even
+   * if the configured concurrency limit would otherwise queue it. Used by the
+   * scheduler so a fired job can't be deferred past its trigger window.
+   */
+  bypassQueue?: boolean;
+  /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+  isolation?: IsolationMode;
+  /** Resolved invocation snapshot captured for UI display. */
+  invocation?: AgentInvocation;
+  /** Parent abort signal — when aborted, the subagent is also stopped. */
+  signal?: AbortSignal;
+  /** Called on tool start/end with activity info (for streaming progress to UI). */
+  onToolActivity?: (activity: ToolActivity) => void;
+  /** Called on streaming text deltas from the assistant response. */
+  onTextDelta?: (delta: string, fullText: string) => void;
+  /** Called when the agent session is created (for accessing session stats). */
+  onSessionCreated?: (session: AgentSession) => void;
+  /** Called at the end of each agentic turn with the cumulative count. */
+  onTurnEnd?: (turnCount: number) => void;
+  /** Called once per assistant message_end with that message's usage delta. */
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  /** Called when the session successfully compacts. */
+  onCompaction?: (info: CompactionInfo) => void;
+}
+
+export class AgentManager {
+  private agents = new Map<string, AgentRecord>();
+  private cleanupInterval: ReturnType<typeof setInterval>;
+  private onComplete?: OnAgentComplete;
+  private onStart?: OnAgentStart;
+  private onCompact?: OnAgentCompact;
+  private maxConcurrent: number;
+
+  /** Queue of background agents waiting to start. */
+  private queue: { id: string; args: SpawnArgs }[] = [];
+  /** Number of currently running background agents. */
+  private runningBackground = 0;
+
+  constructor(
+    onComplete?: OnAgentComplete,
+    maxConcurrent = DEFAULT_MAX_CONCURRENT,
+    onStart?: OnAgentStart,
+    onCompact?: OnAgentCompact,
+  ) {
+    this.onComplete = onComplete;
+    this.onStart = onStart;
+    this.onCompact = onCompact;
+    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: number) {
+    this.maxConcurrent = Math.max(1, n);
+    // Start queued agents if the new limit allows
+    this.drainQueue();
+  }
+
+  getMaxConcurrent(): number {
+    return this.maxConcurrent;
+  }
+
+  /**
+   * Spawn an agent and return its ID immediately (for background use).
+   * If the concurrency limit is reached, the agent is queued.
+   */
+  spawn(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: SubagentType,
+    prompt: string,
+    options: SpawnOptions,
+  ): string {
+    const id = randomUUID().slice(0, 17);
+    const abortController = new AbortController();
+    const record: AgentRecord = {
+      id,
+      type,
+      description: options.description,
+      status: options.isBackground ? "queued" : "running",
+      toolUses: 0,
+      startedAt: Date.now(),
+      abortController,
+      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+      compactionCount: 0,
+      invocation: options.invocation,
+    };
+    this.agents.set(id, record);
+
+    const args: SpawnArgs = { pi, ctx, type, prompt, options };
+
+    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+      // Queue it — will be started when a running agent completes
+      this.queue.push({ id, args });
+      return id;
+    }
+
+    // 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++;
+    this.onStart?.(record);
+
+    // Wire parent abort signal to stop the subagent when the parent is interrupted
+    let detachParentSignal: (() => void) | undefined;
+    if (options.signal) {
+      const onParentAbort = () => this.abort(id);
+      options.signal.addEventListener("abort", onParentAbort, { once: true });
+      detachParentSignal = () => options.signal!.removeEventListener("abort", onParentAbort);
+    }
+    const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
+
+    const promise = runAgent(ctx, type, prompt, {
+      pi,
+      model: options.model,
+      maxTurns: options.maxTurns,
+      isolated: options.isolated,
+      inheritContext: options.inheritContext,
+      thinkingLevel: options.thinkingLevel,
+      cwd: worktreeCwd,
+      signal: record.abortController!.signal,
+      onToolActivity: (activity) => {
+        if (activity.type === "end") record.toolUses++;
+        options.onToolActivity?.(activity);
+      },
+      onTurnEnd: options.onTurnEnd,
+      onTextDelta: options.onTextDelta,
+      onAssistantUsage: (usage) => {
+        addUsage(record.lifetimeUsage, usage);
+        options.onAssistantUsage?.(usage);
+      },
+      onCompaction: (info) => {
+        record.compactionCount++;
+        this.onCompact?.(record, info);
+        options.onCompaction?.(info);
+      },
+      onSessionCreated: (session) => {
+        record.session = session;
+        // Flush any steers that arrived before the session was ready
+        if (record.pendingSteers?.length) {
+          for (const msg of record.pendingSteers) {
+            session.steer(msg).catch(() => {});
+          }
+          record.pendingSteers = undefined;
+        }
+        options.onSessionCreated?.(session);
+      },
+    })
+      .then(({ responseText, session, aborted, steered }) => {
+        // Don't overwrite status if externally stopped via abort()
+        if (record.status !== "stopped") {
+          record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+        }
+        record.result = responseText;
+        record.session = session;
+        record.completedAt ??= Date.now();
+
+        detach();
+
+        // Final flush of streaming output file
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
+        // Clean up worktree if used
+        if (record.worktree) {
+          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          record.worktreeResult = wtResult;
+          if (wtResult.hasChanges && wtResult.branch) {
+            record.result = (record.result ?? "") +
+              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+          }
+        }
+
+        if (options.isBackground) {
+          this.runningBackground--;
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+          this.drainQueue();
+        }
+        return responseText;
+      })
+      .catch((err) => {
+        // Don't overwrite status if externally stopped via abort()
+        if (record.status !== "stopped") {
+          record.status = "error";
+        }
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt ??= Date.now();
+
+        detach();
+
+        // Final flush of streaming output file on error
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
+        // Best-effort worktree cleanup on error
+        if (record.worktree) {
+          try {
+            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            record.worktreeResult = wtResult;
+          } catch { /* ignore cleanup errors */ }
+        }
+
+        if (options.isBackground) {
+          this.runningBackground--;
+          this.onComplete?.(record);
+          this.drainQueue();
+        }
+        return "";
+      });
+
+    record.promise = promise;
+  }
+
+  /** Start queued agents up to the concurrency limit. */
+  private drainQueue() {
+    while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+      const next = this.queue.shift()!;
+      const record = this.agents.get(next.id);
+      if (!record || record.status !== "queued") continue;
+      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);
+      }
+    }
+  }
+
+  /**
+   * Spawn an agent and wait for completion (foreground use).
+   * Foreground agents bypass the concurrency queue.
+   */
+  async spawnAndWait(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: SubagentType,
+    prompt: string,
+    options: Omit<SpawnOptions, "isBackground">,
+  ): Promise<AgentRecord> {
+    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+    const record = this.agents.get(id)!;
+    await record.promise;
+    return record;
+  }
+
+  /**
+   * Resume an existing agent session with a new prompt.
+   */
+  async resume(
+    id: string,
+    prompt: string,
+    signal?: AbortSignal,
+  ): Promise<AgentRecord | undefined> {
+    const record = this.agents.get(id);
+    if (!record?.session) return undefined;
+
+    record.status = "running";
+    record.startedAt = Date.now();
+    record.completedAt = undefined;
+    record.result = undefined;
+    record.error = undefined;
+
+    try {
+      const responseText = await resumeAgent(record.session, prompt, {
+        onToolActivity: (activity) => {
+          if (activity.type === "end") record.toolUses++;
+        },
+        onAssistantUsage: (usage) => {
+          addUsage(record.lifetimeUsage, usage);
+        },
+        onCompaction: (info) => {
+          record.compactionCount++;
+          this.onCompact?.(record, info);
+        },
+        signal,
+      });
+      record.status = "completed";
+      record.result = responseText;
+      record.completedAt = Date.now();
+    } catch (err) {
+      record.status = "error";
+      record.error = err instanceof Error ? err.message : String(err);
+      record.completedAt = Date.now();
+    }
+
+    return record;
+  }
+
+  getRecord(id: string): AgentRecord | undefined {
+    return this.agents.get(id);
+  }
+
+  listAgents(): AgentRecord[] {
+    return [...this.agents.values()].sort(
+      (a, b) => b.startedAt - a.startedAt,
+    );
+  }
+
+  abort(id: string): boolean {
+    const record = this.agents.get(id);
+    if (!record) return false;
+
+    // Remove from queue if queued
+    if (record.status === "queued") {
+      this.queue = this.queue.filter(q => q.id !== id);
+      record.status = "stopped";
+      record.completedAt = Date.now();
+      return true;
+    }
+
+    if (record.status !== "running") return false;
+    record.abortController?.abort();
+    record.status = "stopped";
+    record.completedAt = Date.now();
+    return true;
+  }
+
+  /** Dispose a record's session and remove it from the map. */
+  private removeRecord(id: string, record: AgentRecord): void {
+    record.session?.dispose?.();
+    record.session = undefined;
+    this.agents.delete(id);
+  }
+
+  private cleanup() {
+    const cutoff = Date.now() - 10 * 60_000;
+    for (const [id, record] of this.agents) {
+      if (record.status === "running" || record.status === "queued") continue;
+      if ((record.completedAt ?? 0) >= cutoff) continue;
+      this.removeRecord(id, record);
+    }
+  }
+
+  /**
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   */
+  clearCompleted(): void {
+    for (const [id, record] of this.agents) {
+      if (record.status === "running" || record.status === "queued") continue;
+      this.removeRecord(id, record);
+    }
+  }
+
+  /** Whether any agents are still running or queued. */
+  hasRunning(): boolean {
+    return [...this.agents.values()].some(
+      r => r.status === "running" || r.status === "queued",
+    );
+  }
+
+  /** Abort all running and queued agents immediately. */
+  abortAll(): number {
+    let count = 0;
+    // Clear queued agents first
+    for (const queued of this.queue) {
+      const record = this.agents.get(queued.id);
+      if (record) {
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        count++;
+      }
+    }
+    this.queue = [];
+    // Abort running agents
+    for (const record of this.agents.values()) {
+      if (record.status === "running") {
+        record.abortController?.abort();
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /** Wait for all running and queued agents to complete (including queued ones). */
+  async waitForAll(): Promise<void> {
+    // Loop because drainQueue respects the concurrency limit — as running
+    // agents finish they start queued ones, which need awaiting too.
+    while (true) {
+      this.drainQueue();
+      const pending = [...this.agents.values()]
+        .filter(r => r.status === "running" || r.status === "queued")
+        .map(r => r.promise)
+        .filter(Boolean);
+      if (pending.length === 0) break;
+      await Promise.allSettled(pending);
+    }
+  }
+
+  dispose() {
+    clearInterval(this.cleanupInterval);
+    // Clear queue
+    this.queue = [];
+    for (const record of this.agents.values()) {
+      record.session?.dispose();
+    }
+    this.agents.clear();
+    // Prune any orphaned git worktrees (crash recovery)
+    try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+  }
+}