@gjczone/pi-swarm 0.3.5 → 0.5.0

package/README.md

@@ -1,32 +1,29 @@
-# @gjczone/pi-swarm
+# pi-swarm
 
-> **Early release — stability not guaranteed.** This is an initial version. Expect rough edges. Bug reports, feedback, feature requests, and PRs are very welcome.
+Agent Swarm & Team extension for pi-coding-agent. Run 1 to 128 parallel subagents or collaborative role-based teams — no preset configuration needed.
 
-Think of it as **kimi-code's AgentSwarm + Claude Code's agent teams** — inside pi. Parallel swarm agents and collaborative role-based teams, all dynamically spawned with no preset configuration.
-
-## What It Does
-
-**Swarm** — 1 to 128 parallel agents. Like kimi-code's AgentSwarm: one template, many items, running simultaneously. Also works for single subagent delegation. Each agent is an isolated `pi --print` child process with its own context window.
-
-**Team** — collaborative agents. Like Claude Code's agent teams or pi-crew: role-based agents (explorer, planner, coder, reviewer, tester) working in sequence. Each phase agent receives context from previous phases via a shared mailbox. Every agent runs as an independent child process. Optional per-role model tier routing: use a cheaper/faster model for exploration while keeping reasoning-heavy roles on the default model.
-
-All agents are created on-the-fly. No `agents/*.md` files. The main agent decides what to spawn based on the task.
-
-## Install
+## Installation
 
 ```bash
 pi install npm:@gjczone/pi-swarm@latest
 ```
 
-## How to Use
+## Core Features
 
-### Swarm — "Do this to all of these" (or just one)
+| Feature | When to Use | What It Does |
+|---------|-------------|--------------|
+| **AgentSwarm** | Run the same task across many items in parallel | Spawns 1-128 isolated subagents from an item template. Each runs in its own `pi --print` process. |
+| **SwarmTeam** | Execute multi-step workflows with specialized roles | Role-based agents (explorer, planner, coder, reviewer, tester) collaborate in phases with a shared mailbox. Each phase receives context from previous phases. |
+| **/swarm command** | Trigger a swarm from the chat | Shortcut for the AgentSwarm tool. `on` / `off` to toggle swarm mode. |
+| **/swarm-team command** | Trigger a team from the chat | Shortcut for the SwarmTeam tool. |
+| **Worktree Isolation** | Parallel agents modifying the same repo | Each subagent runs in a temporary git worktree. Changes commit to named branches for safe merging. Non-git repos fall back to regular directories. |
+| **Live TUI Progress** | Monitor long-running swarms or teams | Braille progress bars for swarm agents, phase dashboard for teams. Updates in real time. |
+| **Rate-Limit Retry** | Avoid API quota exhaustion | Auto-suspends on rate-limit errors and retries with exponential backoff (3s, 6s, 12s...). |
+| **Crash Recovery** | Survive unexpected termination | Durable file-based state. Resume incomplete runs automatically. Completed runs auto-clean after 7 days. |
 
-Use for 1 to 128 items — same interface, same isolation.
+## Usage Examples
 
-```
-Audit src/auth.ts for security issues — use a subagent
-```
+### Swarm — run the same task across many items
 
 ```
 Review every file in src/ for bugs — use a swarm
@@ -36,13 +33,7 @@ Review every file in src/ for bugs — use a swarm
 Run a security audit on these five packages in parallel: auth, api, db, cache, middleware
 ```
 
-Or the slash command:
-
-```
-/swarm Find deprecated API usage across the codebase
-```
-
-### Team — "Plan this, build it, review it"
+### Team — plan, build, and review in phases
 
 ```
 Implement user login with JWT — use a team with planner, coder, and reviewer
@@ -52,52 +43,21 @@ Implement user login with JWT — use a team with planner, coder, and reviewer
 Add Redis caching — explore the codebase first, then plan, implement, review, test
 ```
 
-Or:
-
-```
-/swarm-team Refactor the auth module end-to-end
-```
-
-### Resume Failed Work
+### Resume failed work
 
-If agents fail, the LLM gets `resume_agent_ids` and can retry:
+If agents fail, the LLM receives `resume_agent_ids` and can retry:
 
 ```
 Two of the five swarm reviews failed — retry those
 ```
 
-### Cancel Mid-Run
-
-Press `Ctrl+C` during a swarm or team run. Completed agents are preserved and results are final (no post-cancellation mutation). In-progress agents are cancelled gracefully and their partial work discarded. For teams, completed phases are saved and returned as partial results. Timeout errors are correctly surfaced instead of being lost in abort/exit races.
-
-## Runtime Files
-
-State is stored under `.pi/swarm/state/`. The extension auto-creates `.pi/` if it doesn't exist, and auto-appends `.pi/swarm/state/` to the project's `.gitignore`.
-
-```
-.pi/swarm/state/runs/{runId}/
-  manifest.json          # Run metadata, agent IDs, timestamps
-  tasks.json             # Task graph, per-phase status
-  events.jsonl           # Append-only event log
-  agents/{agentId}/
-    status.json          # Per-agent status snapshot
-    output.log           # Full agent session output (header, raw stdout, footer)
-  mailbox/               # Team inter-agent messages
-    inbox.jsonl
-    outbox.jsonl
-    delivery.json
-```
+### Cancel mid-run
 
-Runs auto-clean: completed runs deleted after 7 days, stale runs (30min no heartbeat) marked abandoned.
+Press `Ctrl+C` during a swarm or team run. Completed agents are preserved, in-progress agents are cancelled gracefully.
 
 ## Settings
 
-Default max concurrency is **5**. Recommended: **3-10**. Can be set to any positive integer.
-
-| Settings file               | Scope                       |
-| --------------------------- | --------------------------- |
-| `.pi/settings.json`         | Project (current directory) |
-| `~/.pi/agent/settings.json` | Global (all projects)       |
+Default max concurrency is **5**. Adjust in `.pi/settings.json` (project) or `~/.pi/agent/settings.json` (global):
 
 ```json
 {
@@ -107,13 +67,7 @@ Default max concurrency is **5**. Recommended: **3-10**. Can be set to any posit
 }
 ```
 
-Priority: project settings > global settings > `PI_SWARM_MAX_CONCURRENCY` env var.
-
-Lower values (3-5) are safer for API rate limits. Values above 10 work if your provider allows high concurrent requests. No hard upper limit.
-
-## Team Model Tier
-
-When using `SwarmTeam`, you can configure a lightweight model for exploration roles to reduce costs:
+For team mode, configure a lightweight model for exploration roles to reduce costs:
 
 ```json
 {
@@ -123,12 +77,20 @@ When using `SwarmTeam`, you can configure a lightweight model for exploration ro
 }
 ```
 
-The `explorer` and `tester` roles (when assigned to a phase) automatically use the small model. Other roles (`planner`, `coder`, `reviewer`, `fixer`) use the default model unless overridden. No preset agents — you define phases and assign roles via the tool schema. Per-phase overrides are available via `modelTier` and `model` fields.
+## Supported Platforms
+
+| Platform | Status |
+|----------|--------|
+| pi-coding-agent | Required runtime |
+| Node.js >= 18 | Required |
+| Linux / macOS / Windows | Supported |
 
 ## Credits
 
-100% vibe-coded with deepseek-v4-pro, doubao-seed-2.1-pro, and doubao-seed-2.1-turbo. Architecture ported from [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code). Code implementation patterns inspired by [pi-crew](https://github.com/baphuongna/pi-crew). Agent team workflow approach inspired by Claude Code. Thank you to all these projects for their excellent work.
+Architecture ported from [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code). Team communication patterns inspired by [pi-crew](https://github.com/baphuongna/pi-crew). Agent team workflow approach inspired by Claude Code.
 
 ## License
 
 [MIT](LICENSE)
+
+

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AA4FpE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAKxE;AAED,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,GAAG,IAAI,CAgH/C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AA6FpE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAKxE;AAED,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,GAAG,IAAI,CAuH/C"}

package/dist/index.js

@@ -14,6 +14,7 @@ import { registerSwarmTeamTool } from "./team/tool.js";
 import { registerTeamCommand } from "./team/command.js";
 import { recoverRuns } from "./state/recovery.js";
 import { SwarmModeMarkerComponent, } from "./tui/swarm-markers.js";
+import { pruneWorktrees } from "./shared/worktree.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 // ---------------------------------------------------------------------------
@@ -141,6 +142,13 @@ export default function (pi) {
         swarmMode = null;
         // Ensure .pi/swarm/state/ is gitignored
         ensureGitignore(process.cwd());
+        // Best-effort cleanup of orphaned worktrees from previous crashes
+        try {
+            pruneWorktrees(process.cwd());
+        }
+        catch {
+            // Non-git repos or worktree prune failures are non-fatal
+        }
         // Run recovery: detect stale/abandoned runs, clean up expired ones
         try {
             const result = recoverRuns(process.cwd());

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/shared/controller.d.ts

@@ -35,8 +35,12 @@ export declare class SubagentBatchController<T> {
     private reject;
     private finished;
     private started;
+    private startedAt;
     private startedSuccessCount;
     private readonly onProgress?;
+    private eventLog;
+    private nextEventId;
+    private completionTimesMs;
     constructor(launcher: SubagentBatchLauncher, tasks: readonly QueuedSubagentTask<T>[], options?: SubagentBatchOptions);
     /**
      * Run the batch.  Returns a promise that resolves when all tasks
@@ -59,6 +63,8 @@ export declare class SubagentBatchController<T> {
     private recoverRateLimitCapacity;
     private finishIfComplete;
     private emitProgress;
+    /** Add an event to the event log, keeping it bounded. */
+    private addEvent;
     private finish;
     private finishWithUserCancellation;
     private fail;
@@ -81,9 +87,9 @@ export declare class SubagentBatchController<T> {
  *   2. `~/.pi/agent/settings.json` → `pi-swarm.maxConcurrency` (global)
  *   3. `PI_SWARM_MAX_CONCURRENCY` env var
  *
- * Returns `undefined` when unset.  A present value must be a positive
- * integer; invalid input throws so a misconfigured cap never silently
- * reverts to uncapped.
+ * Falls back to DEFAULT_MAX_CONCURRENCY (5) when unset.  A present
+ * value must be a positive integer; invalid input throws so a
+ * misconfigured cap never silently reverts to uncapped.
  */
-export declare function resolveSwarmMaxConcurrency(cwd?: string): number | undefined;
+export declare function resolveSwarmMaxConcurrency(cwd?: string): number;
 //# sourceMappingURL=controller.d.ts.map

package/dist/shared/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/shared/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EAOtB,MAAM,YAAY,CAAC;AAyFpB,qBAAa,uBAAuB,CAAC,CAAC;IAiClC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAhC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,YAAY,CAAS;IAG7B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAA4C;IAGrE,OAAO,CAAC,oBAAoB,CAA4C;IACxE,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,sBAAsB,CAAqB;IACnD,OAAO,CAAC,qBAAqB,CAA4B;IACzD,OAAO,CAAC,qBAAqB,CAAK;IAGlC,OAAO,CAAC,OAAO,CAA4D;IAC3E,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA4C;gBAGrD,QAAQ,EAAE,qBAAqB,EAChD,KAAK,EAAE,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,EACvC,OAAO,GAAE,oBAAyB;IA8BpC;;;OAGG;IACH,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAmCxC,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,oBAAoB;IAwC5B,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,uBAAuB;IA2C/B,OAAO,CAAC,YAAY;YA0BN,UAAU;IA+ExB,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,oBAAoB;IAmC5B,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,uBAAuB;IAe/B,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,YAAY;IAuDpB,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,0BAA0B;IAoClC,OAAO,CAAC,IAAI;IAsBZ,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,+BAA+B;IAQvC,OAAO,CAAC,kBAAkB;CAsC3B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA4B3E"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/shared/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EAUtB,MAAM,YAAY,CAAC;AA+FpB,qBAAa,uBAAuB,CAAC,CAAC;IAyClC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAxC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,YAAY,CAAS;IAG7B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAA4C;IAGrE,OAAO,CAAC,oBAAoB,CAA4C;IACxE,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,sBAAsB,CAAqB;IACnD,OAAO,CAAC,qBAAqB,CAA4B;IACzD,OAAO,CAAC,qBAAqB,CAAK;IAGlC,OAAO,CAAC,OAAO,CAA4D;IAC3E,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA4C;IAGxE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,WAAW,CAAK;IAGxB,OAAO,CAAC,iBAAiB,CAAgB;gBAGtB,QAAQ,EAAE,qBAAqB,EAChD,KAAK,EAAE,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,EACvC,OAAO,GAAE,oBAAyB;IAqCpC;;;OAGG;IACH,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAoCxC,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,oBAAoB;IAwC5B,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,uBAAuB;IA2C/B,OAAO,CAAC,YAAY;YAyCN,UAAU;IAoHxB,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,oBAAoB;IAoC5B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,uBAAuB;IAe/B,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,YAAY;IA8FpB,yDAAyD;IACzD,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,0BAA0B;IAoClC,OAAO,CAAC,IAAI;IAsBZ,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,+BAA+B;IAQvC,OAAO,CAAC,kBAAkB;CAsC3B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA4B/D"}

package/dist/shared/controller.js

@@ -23,6 +23,7 @@ const RATE_LIMIT_CAPACITY_SHRINK_INTERVAL_MS = 2000;
 const RATE_LIMIT_CAPACITY_RECOVERY_INTERVAL_MS = 3 * 60 * 1000; // 3 minutes
 const AGENT_SWARM_MAX_CONCURRENCY_ENV = "PI_SWARM_MAX_CONCURRENCY";
 const DEFAULT_MAX_CONCURRENCY = 5;
+const RATE_LIMIT_SUSPENDED_REASON = "Rate limit reached — agent suspended";
 // ---------------------------------------------------------------------------
 // Abort helpers
 // ---------------------------------------------------------------------------
@@ -88,8 +89,14 @@ export class SubagentBatchController {
     reject;
     finished = false;
     started = false;
+    startedAt = 0;
     startedSuccessCount = 0;
     onProgress;
+    // Event log
+    eventLog = [];
+    nextEventId = 1;
+    // ETA tracking: track completion timestamps for average calculation
+    completionTimesMs = [];
     constructor(launcher, tasks, options = {}) {
         this.launcher = launcher;
         this.maxConcurrency = options.maxConcurrency;
@@ -100,6 +107,13 @@ export class SubagentBatchController {
             retryCount: 0,
             retryReadyAt: 0,
             started: false,
+            usage: {
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                totalTokens: 0,
+            },
         }));
         this.pending = [...this.states];
         this.results = Array.from({
@@ -126,6 +140,7 @@ export class SubagentBatchController {
             throw new Error("SubagentBatchController.run() can only be called once.");
         }
         this.started = true;
+        this.startedAt = Date.now();
         return new Promise((resolve, reject) => {
             this.resolve = resolve;
             this.reject = reject;
@@ -262,6 +277,21 @@ export class SubagentBatchController {
         attempt.cleanup = this.linkAttemptSignals(attempt, state.task);
         this.active.add(attempt);
         attempt.state.started = true;
+        attempt.state.startedAt = Date.now();
+        // Add event to log
+        this.addEvent({
+            id: this.nextEventId++,
+            agentId: undefined,
+            timestamp: Date.now(),
+            type: "started",
+            detail: state.task.swarmItem
+                ? `Started: ${state.task.swarmItem.slice(0, 60)}`
+                : `Started task ${state.index + 1}`,
+        });
+        // Trim event log to last 50 entries
+        if (this.eventLog.length > 50) {
+            this.eventLog = this.eventLog.slice(-50);
+        }
         // A task transitioned from queued to working
         this.emitProgress();
         this.runAttempt(attempt).then((outcome) => {
@@ -283,6 +313,16 @@ export class SubagentBatchController {
             onReady: () => {
                 this.markAttemptReady(attempt);
             },
+            onUsage: (usage) => {
+                attempt.state.usage = { ...usage };
+                this.emitProgress();
+            },
+            onActivity: (tool, activity) => {
+                attempt.state.currentTool = tool;
+                attempt.state.activity = activity;
+                this.emitProgress();
+            },
+            onMessage: task.onMessage,
             suppressRateLimitFailureEvent: true,
             timeout: task.timeout,
             swarmRoot: task.swarmRoot,
@@ -291,6 +331,9 @@ export class SubagentBatchController {
             model: task.model,
             tools: task.tools,
             cwd: task.cwd,
+            useWorktree: task.useWorktree,
+            mailboxPath: task.mailboxPath,
+            roleName: task.roleName,
         };
         let handle;
         try {
@@ -308,6 +351,10 @@ export class SubagentBatchController {
                     model: task.model,
                     tools: task.tools,
                     cwd: task.cwd,
+                    useWorktree: task.useWorktree,
+                    mailboxPath: task.mailboxPath,
+                    roleName: task.roleName,
+                    onMessage: task.onMessage,
                     ...runOptions,
                 };
                 handle = await this.launcher.spawn(spawnOptions);
@@ -319,11 +366,31 @@ export class SubagentBatchController {
         attempt.state.agentId = handle.agentId;
         try {
             const completion = await handle.completion;
+            if (completion.usage) {
+                attempt.state.usage = { ...completion.usage };
+            }
+            const completedAt = Date.now();
+            attempt.state.completedAt = completedAt;
+            if (attempt.state.startedAt) {
+                this.completionTimesMs.push(completedAt - attempt.state.startedAt);
+            }
+            // Add event to log
+            this.addEvent({
+                id: this.nextEventId++,
+                agentId: handle.agentId,
+                timestamp: completedAt,
+                type: "completed",
+                detail: attempt.state.task.swarmItem
+                    ? `Agent completed: ${attempt.state.task.swarmItem.slice(0, 60)}`
+                    : `Agent completed`,
+            });
             return {
                 task,
                 agentId: handle.agentId,
                 status: "completed",
                 result: completion.result,
+                usage: attempt.state.usage,
+                worktreeBranch: completion.worktreeBranch,
             };
         }
         catch (error) {
@@ -382,6 +449,13 @@ export class SubagentBatchController {
         // Save agent id for retry and requeue at front
         state.retryAgentId = state.agentId ?? state.retryAgentId;
         state.retryCount += 1;
+        // Notify external listeners that this agent was suspended
+        if (state.agentId) {
+            this.launcher.suspended?.({
+                agentId: state.agentId,
+                reason: RATE_LIMIT_SUSPENDED_REASON,
+            });
+        }
         // Exponential backoff
         const delay = RATE_LIMIT_RETRY_BASE_MS *
             Math.pow(RATE_LIMIT_RETRY_FACTOR, state.retryCount - 1);
@@ -419,6 +493,7 @@ export class SubagentBatchController {
             status,
             state: attempt.state.started ? "started" : "not_started",
             error: errorMessage,
+            usage: { ...attempt.state.usage },
         };
     }
     // -----------------------------------------------------------------------
@@ -427,7 +502,10 @@ export class SubagentBatchController {
     enterRateLimitPhase() {
         this.rateLimitMode = true;
         this.clearNormalTimer();
-        this.rateLimitCapacity = Math.max(1, this.countReadyActive());
+        // Use startedSuccessCount (count of agents that fully booted during
+        // the normal phase) so capacity reflects true past throughput rather
+        // than only currently-active attempts (which may already be finishing).
+        this.rateLimitCapacity = Math.max(1, this.startedSuccessCount);
         this.lastRateLimitAt = Date.now();
         this.globalRetryIntervalMs = RATE_LIMIT_RETRY_BASE_MS;
         this.nextRateLimitLaunchAt = Date.now() + RATE_LIMIT_RETRY_BASE_MS;
@@ -470,6 +548,13 @@ export class SubagentBatchController {
         let completed = 0;
         let failed = 0;
         let active = 0;
+        const totalUsage = {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+        };
         const members = [];
         const activeIndices = new Set(Array.from(this.active, (a) => a.state.index));
         for (const state of this.states) {
@@ -477,6 +562,15 @@ export class SubagentBatchController {
             const isActiveState = activeIndices.has(state.index);
             let phase = "queued";
             let error;
+            // Accumulate usage from live state or completed result
+            const memberUsage = result?.usage ?? state.usage;
+            if (memberUsage) {
+                totalUsage.input += memberUsage.input;
+                totalUsage.output += memberUsage.output;
+                totalUsage.cacheRead += memberUsage.cacheRead;
+                totalUsage.cacheWrite += memberUsage.cacheWrite;
+                totalUsage.totalTokens += memberUsage.totalTokens;
+            }
             if (result) {
                 if (result.status === "completed") {
                     phase = "completed";
@@ -500,9 +594,25 @@ export class SubagentBatchController {
                 phase,
                 item: state.task.swarmItem,
                 error,
+                usage: memberUsage,
+                currentTool: state.currentTool,
+                activity: state.activity,
             });
         }
         const queued = this.states.length - completed - failed - active;
+        // Calculate ETA based on average completion time
+        let estimatedRemainingMs;
+        const totalFinished = completed + failed;
+        const totalRemaining = queued + active;
+        if (totalFinished > 0 && totalRemaining > 0) {
+            const avgTimeMs = this.completionTimesMs.length > 0
+                ? this.completionTimesMs.reduce((a, b) => a + b, 0) /
+                    this.completionTimesMs.length
+                : 0;
+            if (avgTimeMs > 0) {
+                estimatedRemainingMs = avgTimeMs * totalRemaining;
+            }
+        }
         this.onProgress({
             total: this.states.length,
             completed,
@@ -510,8 +620,20 @@ export class SubagentBatchController {
             active,
             queued,
             members,
+            totalUsage,
+            startedAt: this.startedAt,
+            estimatedRemainingMs,
+            eventLog: [...this.eventLog],
         });
     }
+    /** Add an event to the event log, keeping it bounded. */
+    addEvent(event) {
+        this.eventLog.push(event);
+        // Keep max 100 events
+        if (this.eventLog.length > 100) {
+            this.eventLog = this.eventLog.slice(-100);
+        }
+    }
     finish(results) {
         if (this.finished)
             return;
@@ -609,6 +731,17 @@ export class SubagentBatchController {
             return;
         attempt.ready = true;
         this.startedSuccessCount += 1;
+        // If we are in rate-limit mode, reset the global retry interval
+        // so the next launch uses the base delay rather than an accumulated
+        // exponential backoff, and re-arm the scheduler immediately.
+        if (this.rateLimitMode) {
+            this.globalRetryIntervalMs = RATE_LIMIT_RETRY_BASE_MS;
+            this.nextRateLimitLaunchAt = Date.now() + this.globalRetryIntervalMs;
+            // Clear any pending rate-limit timer so schedule() re-computes
+            // the next wakeup from the new (shorter) interval.
+            this.clearRateLimitTimer();
+            this.schedule();
+        }
     }
     countReadyActive() {
         let count = 0;
@@ -682,9 +815,9 @@ export class SubagentBatchController {
  *   2. `~/.pi/agent/settings.json` → `pi-swarm.maxConcurrency` (global)
  *   3. `PI_SWARM_MAX_CONCURRENCY` env var
  *
- * Returns `undefined` when unset.  A present value must be a positive
- * integer; invalid input throws so a misconfigured cap never silently
- * reverts to uncapped.
+ * Falls back to DEFAULT_MAX_CONCURRENCY (5) when unset.  A present
+ * value must be a positive integer; invalid input throws so a
+ * misconfigured cap never silently reverts to uncapped.
  */
 export function resolveSwarmMaxConcurrency(cwd) {
     // 1. Project-local settings
@@ -705,12 +838,12 @@ export function resolveSwarmMaxConcurrency(cwd) {
     if (raw !== undefined && raw.trim() !== "") {
         return validateConcurrency(Number(raw), AGENT_SWARM_MAX_CONCURRENCY_ENV);
     }
-    // 4. Default
+    // 4. Default (always reached — value guaranteed)
     return DEFAULT_MAX_CONCURRENCY;
 }
 function validateConcurrency(value, source) {
     if (value === undefined || value === null)
-        return undefined;
+        return DEFAULT_MAX_CONCURRENCY;
     const num = Number(value);
     if (!Number.isInteger(num) || num <= 0) {
         throw new Error(`pi-swarm.maxConcurrency in ${source} must be a positive integer, got ${JSON.stringify(value)}.`);