pi-subagents 0.11.12 → 0.12.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-04-03
+
+### Changed
+- Updated session lifecycle handling for pi 0.65.0 by removing legacy post-transition resets and relying on `session_start` reinitialization, matching pi's removal of `session_switch` and `session_fork` extension events.
+
+## [0.12.0] - 2026-03-31
+
+### Added
+- Added git worktree isolation for parallel execution via `worktree: true`. Applies to top-level parallel `tasks`, chain steps with `{ parallel: [...] }`, and async/background chain execution. Each parallel task gets its own temporary git worktree, and the aggregated output now includes per-task diff stats plus the directory path containing full patch files.
+- Added `worktree.ts` to manage worktree lifecycle, diff capture, patch generation, and cleanup for isolated parallel runs.
+- Added `count: N` shorthand for top-level parallel `tasks` and chain `parallel` entries so one authored task can expand into repeated identical runs without manual duplication.
+- Added `subagent_status({ action: "list" })` to list active async runs with flattened step/member status summaries.
+- Added `/subagents-status`, a read-only overlay for active async runs plus recent completed/failed runs with per-run step details. The overlay auto-refreshes while open and preserves the selected run when possible.
+- Documented worktree isolation, async status surfaces, and the reorganized test layout in the README.
+
+### Changed
+- Consolidated tests under `test/unit`, `test/integration`, `test/e2e`, and `test/support`, replacing the old mixed root-level and `test/` layout. Test scripts now target those directories explicitly.
+- Integration tests now use a tiny local file-based mock `pi` harness instead of relying on the external subprocess harness for normal subagent execution.
+- Removed legacy extra session lifecycle resets and now rely on immutable-session `session_start` reinitialization, matching pi's removal of post-transition `session_switch`/`session_fork` events.
+
+### Fixed
+- Loader-based tests now resolve `.js` → `.ts` imports correctly when the repository path contains spaces or other URL-escaped characters. Added a focused regression test for the custom test loader.
+- Worktree-isolated parallel runs now reject task-level `cwd` overrides that differ from the shared batch/step `cwd`, instead of silently ignoring them. Applies to foreground parallel runs, chain parallel steps, and async/background execution.
+- Worktree diff capture now includes committed, modified, and newly created files without accidentally including the synthetic `node_modules` symlink used inside temporary worktrees.
+- Worktree setup now cleans up already-created worktrees if a later worktree in the same batch fails to initialize.
+- Prompt-template delegated parallel responses now preserve the aggregate worktree summary text instead of dropping it when rebuilding the final delegated output.
+- Async status and result JSON files are now written atomically so readers do not observe partial JSON during background updates.
+- `readStatus()` now returns `null` only for genuinely missing files and preserves real inspect/read/parse failures with context.
+- Async status polling and result watching now log status/result/watcher failures instead of silently swallowing them, making background completion/debugging failures visible.
+- Slash-command tests now match the current live snapshot contract instead of asserting the stale pre-finalized inline state.
+
 ## [0.11.12] - 2026-03-28
 
 ### Changed

package/README.md

@@ -34,7 +34,7 @@ Use url in the prompt to take screenshot: $@
 
 Then `/take-screenshot https://example.com` switches to Sonnet, delegates to the `browser-screenshoter` agent with `/tmp/screenshots` as the working directory, and restores your model when done. Runtime overrides like `--cwd=<path>` and `--subagent=<name>` work too.
 
-pi-prompt-template-model is entirely optional — pi-subagents works standalone through the `subagent` tool and slash commands.
+pi-prompt-template-model is entirely optional — pi-subagents works standalone through the `subagent` tool and slash commands. If you want reusable prompt-template workflows on top of subagents, including `/chain-prompts` and compare-style prompts like `pi-prompt-template-model`'s `/best-of-n` example, install [pi-prompt-template-model](https://github.com/nicobailon/pi-prompt-template-model) separately and copy any example prompts you want from its `examples/` directory into `~/.pi/agent/prompts/`.
 
 ## Agents
 
@@ -131,6 +131,7 @@ Subagents only get direct MCP tools when `mcp:` items are explicitly listed. Eve
 | `/run <agent> <task>` | Run a single agent with a task |
 | `/chain agent1 "task1" -> agent2 "task2"` | Run agents in sequence with per-step tasks |
 | `/parallel agent1 "task1" -> agent2 "task2"` | Run agents in parallel with per-step tasks |
+| `/subagents-status` | Open the async status overlay for active and recent runs |
 | `/agents` | Open the Agents Manager overlay |
 
 All commands validate agent names locally and tab-complete them, then route through the tool framework for full live progress rendering. Results are sent to the conversation for the LLM to discuss.
@@ -190,7 +191,7 @@ Add `--bg` at the end of any slash command to run in the background:
 /parallel scout "scan frontend" -> scout "scan backend" -> scout "scan infra" --bg
 ```
 
-Without `--bg`, the run is foreground: the tool call stays active and streams progress until completion. With `--bg`, the run is launched asynchronously: control returns immediately, and completion arrives later via notification. In both cases subagents run as separate processes. Check status with `subagent_status`.
+Without `--bg`, the run is foreground: the tool call stays active and streams progress until completion. With `--bg`, the run is launched asynchronously: control returns immediately, and completion arrives later via notification. In both cases subagents run as separate processes. Check status with the `subagent_status` tool, or open the `/subagents-status` slash command for a read-only overlay listing active runs and recent completions.
 
 ### Forked Context Execution
 
@@ -300,6 +301,7 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 - **Agent Templates**: Create agents from presets (Scout, Planner, Implementer, Code Reviewer, Blank Chain)
 - **Skill Injection**: Agents declare skills in frontmatter; skills get injected into system prompts
 - **Parallel-in-Chain**: Fan-out/fan-in patterns with `{ parallel: [...] }` steps within chains
+- **Worktree Isolation**: `worktree: true` gives each parallel agent its own git worktree, preventing filesystem conflicts during concurrent execution
 - **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
 - **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`, `skill`)
 - **Chain Artifacts**: Shared directory at `<tmpdir>/pi-chain-runs/{runId}/` for inter-step files
@@ -442,6 +444,9 @@ These are the parameters the **LLM agent** passes when it calls the `subagent` t
 // Parallel
 { tasks: [{ agent: "scout", task: "a" }, { agent: "scout", task: "b" }] }
 
+// Parallel with count shorthand (run the same task 3 times)
+{ tasks: [{ agent: "scout", task: "audit auth", count: 3 }] }
+
 // Parallel with forked context (each task gets its own isolated fork)
 { tasks: [{ agent: "scout", task: "audit frontend" }, { agent: "reviewer", task: "audit backend" }], context: "fork" }
 
@@ -472,7 +477,7 @@ These are the parameters the **LLM agent** passes when it calls the `subagent` t
 { chain: [
   { agent: "scout", task: "Gather context for the codebase" },
   { parallel: [
-    { agent: "worker", task: "Implement auth based on {previous}" },
+    { agent: "worker", task: "Implement auth based on {previous}", count: 2 },
     { agent: "worker", task: "Implement API based on {previous}" }
   ]},
   { agent: "reviewer", task: "Review all changes from {previous}" }
@@ -488,6 +493,22 @@ These are the parameters the **LLM agent** passes when it calls the `subagent` t
   ], concurrency: 2, failFast: true }  // limit concurrency, stop on first failure
 ]}
 
+// Worktree isolation — each parallel agent gets its own git worktree
+{ tasks: [
+  { agent: "worker", task: "Implement auth" },
+  { agent: "worker", task: "Implement API" }
+], worktree: true }
+
+// Worktree isolation in a chain (fan-out with isolation, fan-in for review)
+{ chain: [
+  { agent: "scout", task: "Gather context" },
+  { parallel: [
+    { agent: "worker", task: "Implement feature A based on {previous}" },
+    { agent: "worker", task: "Implement feature B based on {previous}" }
+  ], worktree: true },
+  { agent: "reviewer", task: "Review changes from {previous}" }
+]}
+
 // Async chain with parallel step (runs in background)
 { chain: [
   { agent: "scout", task: "Gather context" },
@@ -501,10 +522,15 @@ These are the parameters the **LLM agent** passes when it calls the `subagent` t
 
 **subagent_status tool:**
 ```typescript
-{ id: "a53ebe46" }
+{ action: "list" }                    // active async runs only
+{ id: "a53ebe46" }                    // inspect one run
 { dir: "<tmpdir>/pi-async-subagent-runs/a53ebe46-..." }
 ```
 
+**/subagents-status slash command:**
+
+Opens a small read-only overlay that shows active async runs plus recent completed/failed runs. It auto-refreshes every 2 seconds while open, keeps the current run selected when possible, and uses `↑↓` to select a run plus `Esc` to close.
+
 ## Management Actions
 
 Agent definitions are not loaded into LLM context by default. Management actions let the LLM discover, inspect, create, and modify agent and chain definitions at runtime through the `subagent` tool — no manual file editing or restart required. Newly created agents are immediately usable in the same session. Set `action` and omit execution payloads (`task`, `chain`, `tasks`).
@@ -578,7 +604,8 @@ Notes:
 | `output` | `string \| false` | agent default | Override output file for single agent (absolute path as-is, relative path resolved against cwd) |
 | `skill` | `string \| string[] \| false` | agent default | Override skills (comma-separated string, array, or false to disable) |
 | `model` | string | agent default | Override model for single agent |
-| `tasks` | `{agent, task, cwd?, skill?}[]` | - | Parallel tasks (sync only) |
+| `tasks` | `{agent, task, cwd?, count?, skill?}[]` | - | Parallel tasks. Foreground runs directly; background requests are converted to an equivalent chain. `count` repeats one task entry N times with the same settings. |
+| `worktree` | boolean | false | Create isolated git worktrees for each parallel task. Requires clean git state. Per-worktree diffs included in output. |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
 | `context` | `"fresh" \| "fork"` | `fresh` | Execution context mode. `fork` uses a real branched session from the parent's current leaf for each child run |
 | `chainDir` | string | `<tmpdir>/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
@@ -616,6 +643,7 @@ Notes:
 | `parallel` | ParallelTask[] | required | Array of tasks to run concurrently |
 | `concurrency` | number | 4 | Max concurrent tasks |
 | `failFast` | boolean | false | Stop remaining tasks on first failure |
+| `worktree` | boolean | false | Create isolated git worktrees for each parallel task |
 
 *ParallelTask fields:* (same as sequential step)
 
@@ -624,6 +652,7 @@ Notes:
 | `agent` | string | required | Agent name |
 | `task` | string | `{previous}` | Task template |
 | `cwd` | string | - | Override working directory |
+| `count` | number | 1 | Repeat this parallel task N times with the same settings |
 | `output` | `string \| false` | agent default | Override output (namespaced to parallel-N/M-agent/) |
 | `reads` | `string[] \| false` | agent default | Override files to read |
 | `progress` | boolean | agent default | Override progress tracking |
@@ -634,7 +663,48 @@ Status tool:
 
 | Tool | Description |
 |------|-------------|
-| `subagent_status` | Inspect async run status by id or dir |
+| `subagent_status` | List active async runs or inspect one run by id or dir |
+
+## Worktree Isolation
+
+When multiple agents run in parallel against the same repo, they can clobber each other's file changes. Pass `worktree: true` to give each parallel agent its own git worktree branched from HEAD.
+
+```typescript
+// Top-level parallel with worktree isolation
+{ tasks: [
+  { agent: "worker", task: "Implement auth", count: 2 },
+  { agent: "worker", task: "Implement API" }
+], worktree: true }
+
+// Chain with worktree-isolated parallel step
+{ chain: [
+  { agent: "scout", task: "Gather context" },
+  { parallel: [
+    { agent: "worker", task: "Implement feature A based on {previous}" },
+    { agent: "worker", task: "Implement feature B based on {previous}" }
+  ], worktree: true },
+  { agent: "reviewer", task: "Review all changes from {previous}" }
+]}
+```
+
+After the parallel step completes, per-agent diff stats are appended to the output (and become `{previous}` for the next chain step). Full patch files are written to disk. The caller or next step can decide what to keep.
+
+**Requirements:**
+
+- Must be inside a git repository
+- Working tree must be clean (no uncommitted changes) — commit or stash first
+- `node_modules/` is symlinked into each worktree to avoid reinstalling
+- Worktree runs use the shared parallel/step `cwd`. Task-level `cwd` overrides must be omitted or match that shared `cwd`; if you need different working directories, disable `worktree` or split the run.
+
+**What happens under the hood:**
+
+1. `git worktree add` creates a temporary worktree per agent in `<tmpdir>/pi-worktree-*`
+2. Each agent runs in its worktree's cwd (preserving subdirectory context)
+3. After execution, `git add -A && git diff --cached` captures all changes (committed, modified, and new files)
+4. Diff stats appear in the aggregated output; full `.patch` files are written to the artifacts directory
+5. Worktrees and temp branches are cleaned up in a `finally` block
+
+If you use [pi-prompt-template-model](https://github.com/nicobailon/pi-prompt-template-model), worktree isolation is also available via `worktree: true` in chain template frontmatter or the `--worktree` CLI flag on `chain-prompts`. `pi-prompt-template-model` compare-style prompts can route through the same worktree machinery too; see the `pi-prompt-template-model` README and `examples/` directory for the installable prompt templates.
 
 ## Chain Variables
 
@@ -772,14 +842,18 @@ Async runs write a dedicated observability folder:
   subagent-log-<id>.md
 ```
 
-`status.json` is the source of truth for async progress and powers the TUI widget. If you already use
-`/status <id>` you can keep doing that; otherwise use:
+`status.json` is the source of truth for async progress and powers both the TUI widget and `/subagents-status`. Async status and result files are written atomically, so readers do not observe partial JSON during background updates.
+
+For programmatic access:
 
 ```typescript
+subagent_status({ action: "list" })
 subagent_status({ id: "<id>" })
 subagent_status({ dir: "<tmpdir>/pi-async-subagent-runs/<id>" })
 ```
 
+For an interactive overview, run the `/subagents-status` slash command to open the overlay listing active runs and recent completed/failed runs. The overlay auto-refreshes every 2 seconds while it is open.
+
 ## Events
 
 Async events:
@@ -799,8 +873,10 @@ Async events:
 ├── chain-execution.ts            # Chain orchestration (sequential + parallel)
 ├── chain-serializer.ts           # Parse/serialize .chain.md files
 ├── async-execution.ts            # Async/background execution support
+├── async-status.ts               # Async run discovery, listing, and formatting
 ├── execution.ts                  # Core runSync, applyThinkingSuffix
 ├── render.ts                     # TUI rendering (widget, tool result display)
+├── subagents-status.ts           # Async status overlay component
 ├── artifacts.ts                  # Artifact management
 ├── formatters.ts                 # Output formatting utilities
 ├── schemas.ts                    # TypeBox parameter schemas
@@ -808,6 +884,7 @@ Async events:
 ├── types.ts                      # Shared types and constants
 ├── subagent-runner.ts            # Async runner (detached process)
 ├── parallel-utils.ts             # Parallel execution utilities for async runner
+├── worktree.ts                   # Git worktree isolation for parallel execution
 ├── pi-spawn.ts                   # Cross-platform pi CLI spawning
 ├── single-output.ts              # Solo agent output file handling
 ├── notify.ts                     # Async completion notifications
@@ -827,5 +904,9 @@ Async events:
 ├── agent-templates.ts            # Agent/chain creation templates
 ├── render-helpers.ts             # Shared pad/row/header/footer helpers
 ├── run-history.ts                # Per-agent run recording (JSONL)
+├── test/unit/                    # Fast unit tests for pure modules
+├── test/integration/             # Loader-based execution/integration tests
+├── test/e2e/                     # End-to-end sandbox tests
+├── test/support/                 # Shared test loader, helpers, and mock pi harness
 └── text-editor.ts                # Shared text editor (word nav, paste)
 ```

package/async-execution.ts

@@ -222,6 +222,7 @@ export function executeAsyncChain(
 				}, nextSessionFile())),
 				concurrency: s.concurrency,
 				failFast: s.failFast,
+				worktree: s.worktree,
 			};
 		}
 		return buildSeqStep(s as SequentialStep, nextSessionFile());

package/async-job-tracker.ts

@@ -30,24 +30,30 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 				if (job.status === "complete" || job.status === "failed") {
 					continue;
 				}
-				const status = readStatus(job.asyncDir);
-				if (status) {
-					job.status = status.state;
-					job.mode = status.mode;
-					job.currentStep = status.currentStep ?? job.currentStep;
-					job.stepsTotal = status.steps?.length ?? job.stepsTotal;
-					job.startedAt = status.startedAt ?? job.startedAt;
-					job.updatedAt = status.lastUpdate ?? Date.now();
-					if (status.steps?.length) {
-						job.agents = status.steps.map((step) => step.agent);
+				try {
+					const status = readStatus(job.asyncDir);
+					if (status) {
+						job.status = status.state;
+						job.mode = status.mode;
+						job.currentStep = status.currentStep ?? job.currentStep;
+						job.stepsTotal = status.steps?.length ?? job.stepsTotal;
+						job.startedAt = status.startedAt ?? job.startedAt;
+						job.updatedAt = status.lastUpdate ?? Date.now();
+						if (status.steps?.length) {
+							job.agents = status.steps.map((step) => step.agent);
+						}
+						job.sessionDir = status.sessionDir ?? job.sessionDir;
+						job.outputFile = status.outputFile ?? job.outputFile;
+						job.totalTokens = status.totalTokens ?? job.totalTokens;
+						job.sessionFile = status.sessionFile ?? job.sessionFile;
+						continue;
 					}
-					job.sessionDir = status.sessionDir ?? job.sessionDir;
-					job.outputFile = status.outputFile ?? job.outputFile;
-					job.totalTokens = status.totalTokens ?? job.totalTokens;
-					job.sessionFile = status.sessionFile ?? job.sessionFile;
-				} else {
 					job.status = job.status === "queued" ? "running" : job.status;
 					job.updatedAt = Date.now();
+				} catch (error) {
+					console.error(`Failed to read async status for '${job.asyncDir}':`, error);
+					job.status = "failed";
+					job.updatedAt = Date.now();
 				}
 			}
 

package/async-status.ts

@@ -0,0 +1,175 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatDuration, formatTokens, shortenPath } from "./formatters.js";
+import { type AsyncStatus, type TokenUsage } from "./types.js";
+import { readStatus } from "./utils.js";
+
+export interface AsyncRunStepSummary {
+	index: number;
+	agent: string;
+	status: string;
+	durationMs?: number;
+	tokens?: TokenUsage;
+	skills?: string[];
+}
+
+export interface AsyncRunSummary {
+	id: string;
+	asyncDir: string;
+	state: "queued" | "running" | "complete" | "failed";
+	mode: "single" | "chain";
+	cwd?: string;
+	startedAt: number;
+	lastUpdate?: number;
+	endedAt?: number;
+	currentStep?: number;
+	steps: AsyncRunStepSummary[];
+	sessionDir?: string;
+	outputFile?: string;
+	totalTokens?: TokenUsage;
+	sessionFile?: string;
+}
+
+export interface AsyncRunListOptions {
+	states?: Array<AsyncRunSummary["state"]>;
+	limit?: number;
+}
+
+export interface AsyncRunOverlayData {
+	active: AsyncRunSummary[];
+	recent: AsyncRunSummary[];
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isNotFoundError(error: unknown): boolean {
+	return typeof error === "object"
+		&& error !== null
+		&& "code" in error
+		&& (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function isAsyncRunDir(root: string, entry: string): boolean {
+	const entryPath = path.join(root, entry);
+	try {
+		return fs.statSync(entryPath).isDirectory();
+	} catch (error) {
+		if (isNotFoundError(error)) return false;
+		throw new Error(`Failed to inspect async run path '${entryPath}': ${getErrorMessage(error)}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+}
+
+function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string }): AsyncRunSummary {
+	return {
+		id: status.runId || path.basename(asyncDir),
+		asyncDir,
+		state: status.state,
+		mode: status.mode,
+		cwd: status.cwd,
+		startedAt: status.startedAt,
+		lastUpdate: status.lastUpdate,
+		endedAt: status.endedAt,
+		currentStep: status.currentStep,
+		steps: (status.steps ?? []).map((step, index) => ({
+			index,
+			agent: step.agent,
+			status: step.status,
+			...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
+			...(step.tokens ? { tokens: step.tokens } : {}),
+			...(step.skills ? { skills: step.skills } : {}),
+		})),
+		...(status.sessionDir ? { sessionDir: status.sessionDir } : {}),
+		...(status.outputFile ? { outputFile: status.outputFile } : {}),
+		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
+		...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
+	};
+}
+
+function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
+	const rank = (state: AsyncRunSummary["state"]): number => {
+		switch (state) {
+			case "running": return 0;
+			case "queued": return 1;
+			case "failed": return 2;
+			case "complete": return 3;
+		}
+	};
+	return [...runs].sort((a, b) => {
+		const byState = rank(a.state) - rank(b.state);
+		if (byState !== 0) return byState;
+		const aTime = a.lastUpdate ?? a.endedAt ?? a.startedAt;
+		const bTime = b.lastUpdate ?? b.endedAt ?? b.startedAt;
+		return bTime - aTime;
+	});
+}
+
+export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
+	} catch (error) {
+		if (isNotFoundError(error)) return [];
+		throw new Error(`Failed to list async runs in '${asyncDirRoot}': ${getErrorMessage(error)}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+
+	const allowedStates = options.states ? new Set(options.states) : undefined;
+	const runs: AsyncRunSummary[] = [];
+	for (const entry of entries) {
+		const asyncDir = path.join(asyncDirRoot, entry);
+		const status = readStatus(asyncDir) as (AsyncStatus & { cwd?: string }) | null;
+		if (!status) continue;
+		const summary = statusToSummary(asyncDir, status);
+		if (allowedStates && !allowedStates.has(summary.state)) continue;
+		runs.push(summary);
+	}
+
+	const sorted = sortRuns(runs);
+	return options.limit !== undefined ? sorted.slice(0, options.limit) : sorted;
+}
+
+export function listAsyncRunsForOverlay(asyncDirRoot: string, recentLimit = 5): AsyncRunOverlayData {
+	const all = listAsyncRuns(asyncDirRoot);
+	const recent = all
+		.filter((run) => run.state === "complete" || run.state === "failed")
+		.sort((a, b) => (b.lastUpdate ?? b.endedAt ?? b.startedAt) - (a.lastUpdate ?? a.endedAt ?? a.startedAt))
+		.slice(0, recentLimit);
+	return {
+		active: all.filter((run) => run.state === "queued" || run.state === "running"),
+		recent,
+	};
+}
+
+function formatStepLine(step: AsyncRunStepSummary): string {
+	const parts = [`${step.index + 1}. ${step.agent}`, step.status];
+	if (step.durationMs !== undefined) parts.push(formatDuration(step.durationMs));
+	if (step.tokens) parts.push(`${formatTokens(step.tokens.total)} tok`);
+	return parts.join(" | ");
+}
+
+function formatRunHeader(run: AsyncRunSummary): string {
+	const stepCount = run.steps.length || 1;
+	const stepLabel = run.currentStep !== undefined ? `step ${run.currentStep + 1}/${stepCount}` : `steps ${stepCount}`;
+	const cwd = run.cwd ? shortenPath(run.cwd) : shortenPath(run.asyncDir);
+	return `${run.id} | ${run.state} | ${run.mode} | ${stepLabel} | ${cwd}`;
+}
+
+export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active async runs"): string {
+	if (runs.length === 0) return `No ${heading.toLowerCase()}.`;
+
+	const lines = [`${heading}: ${runs.length}`, ""];
+	for (const run of runs) {
+		lines.push(`- ${formatRunHeader(run)}`);
+		for (const step of run.steps) {
+			lines.push(`  ${formatStepLine(step)}`);
+		}
+		if (run.sessionFile) lines.push(`  session: ${shortenPath(run.sessionFile)}`);
+		lines.push("");
+	}
+	return lines.join("\n").trimEnd();
+}