pi-subagents 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-02-23
+
+### Added
+- **Async parallel chain support**: Chains with `{ parallel: [...] }` steps now work in async mode. Previously they were rejected with "Async mode doesn't support chains with parallel steps." The async runner now spawns concurrent pi processes for parallel step groups with configurable `concurrency` and `failFast` options. Inspired by PR #31 from @marcfargas.
+- **Comprehensive test suite**: 85 integration tests and 12 E2E tests covering all execution modes (single, parallel, chain, async), error handling, template resolution, and tool validation. Uses `@marcfargas/pi-test-harness` for subprocess mocking and in-process session testing. Thanks @marcfargas for PR #32.
+- GitHub Actions CI workflow running tests on both Ubuntu and Windows with Node.js 24.
+
+### Changed
+- **BREAKING:** `share` parameter now defaults to `false`. Previously, sessions were silently uploaded to GitHub Gists without user consent. Users who want session sharing must now explicitly pass `share: true`. Added documentation explaining what the feature does and its privacy implications.
+
+### Fixed
+- `mapConcurrent` with `limit=0` returned array of undefined values instead of processing items sequentially. Now clamps limit to at least 1.
+- ANSI background color bleed in truncated text. The `truncLine` function now properly tracks and re-applies all active ANSI styles (bold, colors, etc.) before the ellipsis, preventing style leakage. Also uses `Intl.Segmenter` for correct Unicode/emoji handling. Thanks @monotykamary for identifying the issue.
+- `detectSubagentError` no longer produces false positives when the agent recovers from tool errors. Previously, any error in the last tool result would override exitCode 0→1, even if the agent had already produced complete output. Now only errors AFTER the agent's final text response are flagged. Thanks @marcfargas for the fix and comprehensive test coverage.
+- Parallel mode (`tasks: [...]`) now returns aggregated output from all tasks instead of just a success count. Previously only returned "3/3 succeeded" with actual task outputs lost.
+- Session sharing fallback no longer fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. The fallback now resolves the main entry point and walks up to find the package root instead of trying to resolve `package.json` directly.
+- Skills from globally-installed npm packages (via `pi install npm:...`) are now discoverable by subagents. Previously only scanned local `.pi/npm/node_modules/` paths, missing the global npm root where pi actually installs packages.
+- **Windows compatibility**: Fixed `ENAMETOOLONG` errors when tasks exceed command-line length limits by writing long tasks to temp files using pi's `@file` syntax. Thanks @marcfargas.
+- **Windows compatibility**: Suppressed flashing console windows when spawning async runner processes (`windowsHide: true`).
+- **Windows compatibility**: Fixed pi CLI resolution in async runner by passing `piPackageRoot` through to `getPiSpawnCommand`.
+- **Cross-platform paths**: Replaced `startsWith("/")` checks with `path.isAbsolute()` for correct Windows absolute path detection. Replaced template string path concatenation with `path.join()` for consistent path separators.
+- **Resilience**: Added error handling and auto-restart for the results directory watcher. Previously, if the directory was deleted or became inaccessible, the watcher would die silently.
+- **Resilience**: Added `ensureAccessibleDir` helper that verifies directory accessibility after creation and attempts recovery if the directory has broken ACLs (can happen on Windows with Azure AD/Entra ID after wake-from-sleep).
+
 ## [0.9.2] - 2026-02-19
 
 ### Fixed

package/README.md

@@ -270,10 +270,10 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 | Mode | Async Support | Notes |
 |------|---------------|-------|
 | Single | Yes | `{ agent, task }` - agents with `output` write to temp dir |
-| Chain | Yes* | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
+| Chain | Yes | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
 | Parallel | Sync only | `{ tasks: [{agent, task}...] }` - auto-downgrades if async requested |
 
-*Chain defaults to sync with TUI clarification. Use `clarify: false` to enable async (sequential-only chains; parallel-in-chain requires sync mode).
+Chain defaults to sync with TUI clarification. Use `clarify: false` to enable async. Chains with parallel steps (`{ parallel: [...] }`) are fully supported in async mode — parallel tasks run concurrently with configurable `concurrency` and `failFast` options.
 
 **Clarify TUI for single/parallel:**
 
@@ -423,6 +423,16 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
     { agent: "worker", task: "Refactor module C" }
   ], concurrency: 2, failFast: true }  // limit concurrency, stop on first failure
 ]}
+
+// Async chain with parallel step (runs in background)
+{ 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}" }
+  ]},
+  { agent: "reviewer", task: "Review all changes from {previous}" }
+], clarify: false, async: true }
 ```
 
 **subagent_status tool:**
@@ -514,7 +524,7 @@ Notes:
 | `maxOutput` | `{bytes?, lines?}` | 200KB, 5000 lines | Truncation limits for final output |
 | `artifacts` | boolean | true | Write debug artifacts |
 | `includeProgress` | boolean | false | Include full progress in result |
-| `share` | boolean | true | Create shareable session log |
+| `share` | boolean | false | Upload session to GitHub Gist (see [Session Sharing](#session-sharing)) |
 | `sessionDir` | string | temp | Directory to store session logs |
 
 **ChainItem** can be either a sequential step or a parallel step:
@@ -608,6 +618,25 @@ Files per task:
 
 Session files (JSONL) are stored under a per-run session dir (temp by default). The session file path is shown in output. Set `sessionDir` to keep session logs outside `<tmpdir>`.
 
+## Session Sharing
+
+When `share: true` is passed, the extension will:
+
+1. Export the full session (all tool calls, file contents, outputs) to an HTML file
+2. Upload it to a GitHub Gist using your `gh` CLI credentials
+3. Return a shareable URL (`https://shittycodingagent.ai/session/?<gistId>`)
+
+**This is disabled by default.** Session data may contain sensitive information like source code, file paths, environment variables, or credentials that appear in tool outputs.
+
+To enable sharing for a specific run:
+```typescript
+{ agent: "scout", task: "...", share: true }
+```
+
+Requirements:
+- GitHub CLI (`gh`) must be installed and authenticated (`gh auth login`)
+- Gists are created as "secret" (unlisted but accessible to anyone with the URL)
+
 ## Live progress (sync mode)
 
 During sync execution, the collapsed view shows real-time progress for single, chain, and parallel modes.
@@ -686,10 +715,16 @@ Async events:
 ├── artifacts.ts                  # Artifact management
 ├── formatters.ts                 # Output formatting utilities
 ├── schemas.ts                    # TypeBox parameter schemas
-├── utils.ts                      # Shared utility functions
+├── utils.ts                      # Shared utility functions (mapConcurrent, readStatus, etc.)
 ├── types.ts                      # Shared types and constants
 ├── subagent-runner.ts            # Async runner (detached process)
+├── parallel-utils.ts             # Parallel execution utilities for async runner
+├── pi-spawn.ts                   # Cross-platform pi CLI spawning
+├── single-output.ts              # Solo agent output file handling
 ├── notify.ts                     # Async completion notifications
+├── completion-dedupe.ts          # Completion deduplication for notifications
+├── file-coalescer.ts             # Debounced file write coalescing
+├── jsonl-writer.ts               # JSONL event stream writer
 ├── agent-manager.ts              # Overlay orchestrator, screen routing, CRUD
 ├── agent-manager-list.ts         # List screen (search, multi-select, progressive footer)
 ├── agent-manager-detail.ts       # Detail screen (resolved prompt, runs, fields)
@@ -698,6 +733,8 @@ Async events:
 ├── agent-manager-chain-detail.ts # Chain detail screen (flow visualization)
 ├── agent-management.ts           # Management action handlers (list, get, create, update, delete)
 ├── agent-serializer.ts           # Serialize agents to markdown frontmatter
+├── agent-scope.ts                # Agent scope resolution utilities
+├── agent-selection.ts            # Agent selection state management
 ├── agent-templates.ts            # Agent/chain creation templates
 ├── render-helpers.ts             # Shared pad/row/header/footer helpers
 ├── run-history.ts                # Per-agent run recording (JSONL)

package/async-execution.ts

@@ -12,7 +12,8 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
 import { applyThinkingSuffix } from "./execution.js";
 import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
-import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import { isParallelStep, resolveStepBehavior, type ChainStep, type ParallelStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import type { RunnerStep } from "./parallel-utils.js";
 import { resolvePiPackageRoot } from "./pi-spawn.js";
 import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
 import {
@@ -105,6 +106,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string): number | undefin
 		cwd,
 		detached: true,
 		stdio: "ignore",
+		windowsHide: true,
 	});
 	proc.unref();
 	return proc.pid;
@@ -119,28 +121,20 @@ export function executeAsyncChain(
 ): AsyncExecutionResult {
 	const { chain, agents, ctx, cwd, maxOutput, artifactsDir, artifactConfig, shareEnabled, sessionRoot } = params;
 	const chainSkills = params.chainSkills ?? [];
-	
-	// Async mode doesn't support parallel steps (v1 limitation)
-	const hasParallelInChain = chain.some(isParallelStep);
-	if (hasParallelInChain) {
-		return {
-			content: [{ type: "text", text: "Async mode doesn't support chains with parallel steps. Use clarify: true (sync mode) for parallel-in-chain." }],
-			isError: true,
-			details: { mode: "chain" as const, results: [] },
-		};
-	}
-
-	// At this point, all steps are sequential
-	const seqSteps = chain as SequentialStep[];
 
 	// Validate all agents exist before building steps
-	for (const s of seqSteps) {
-		if (!agents.find((x) => x.name === s.agent)) {
-			return {
-				content: [{ type: "text", text: `Unknown agent: ${s.agent}` }],
-				isError: true,
-				details: { mode: "chain" as const, results: [] },
-			};
+	for (const s of chain) {
+		const stepAgents = isParallelStep(s)
+			? s.parallel.map((t) => t.agent)
+			: [(s as SequentialStep).agent];
+		for (const agentName of stepAgents) {
+			if (!agents.find((x) => x.name === agentName)) {
+				return {
+					content: [{ type: "text", text: `Unknown agent: ${agentName}` }],
+					isError: true,
+					details: { mode: "chain" as const, results: [] },
+				};
+			}
 		}
 	}
 
@@ -149,7 +143,8 @@ export function executeAsyncChain(
 		fs.mkdirSync(asyncDir, { recursive: true });
 	} catch {}
 
-	const steps = seqSteps.map((s) => {
+	/** Build a resolved runner step from a SequentialStep */
+	const buildSeqStep = (s: SequentialStep) => {
 		const a = agents.find((x) => x.name === s.agent)!;
 		const stepSkillInput = normalizeSkillInput(s.skill);
 		const stepOverrides: StepOverrides = { skills: stepSkillInput };
@@ -162,9 +157,15 @@ export function executeAsyncChain(
 			const injection = buildSkillInjection(resolvedSkills);
 			systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
 		}
+
+		// Resolve output path and inject instruction into task
+		// Use step's cwd if specified, otherwise fall back to chain-level cwd
+		const outputPath = resolveSingleOutputPath(s.output, ctx.cwd, s.cwd ?? cwd);
+		const task = injectSingleOutputInstruction(s.task ?? "{previous}", outputPath);
+
 		return {
 			agent: s.agent,
-			task: s.task ?? "{previous}",
+			task,
 			cwd: s.cwd,
 			model: applyThinkingSuffix(s.model ?? a.model, a.thinking),
 			tools: a.tools,
@@ -172,7 +173,28 @@ export function executeAsyncChain(
 			mcpDirectTools: a.mcpDirectTools,
 			systemPrompt,
 			skills: resolvedSkills.map((r) => r.name),
+			outputPath,
 		};
+	};
+
+	// Build runner steps — sequential steps become flat objects,
+	// parallel steps become { parallel: [...], concurrency?, failFast? }
+	const steps: RunnerStep[] = chain.map((s) => {
+		if (isParallelStep(s)) {
+			return {
+				parallel: s.parallel.map((t) => buildSeqStep({
+					agent: t.agent,
+					task: t.task,
+					cwd: t.cwd,
+					skill: t.skill,
+					model: t.model,
+					output: t.output,
+				})),
+				concurrency: s.concurrency,
+				failFast: s.failFast,
+			};
+		}
+		return buildSeqStep(s as SequentialStep);
 	});
 
 	const runnerCwd = cwd ?? ctx.cwd;
@@ -197,22 +219,34 @@ export function executeAsyncChain(
 	);
 
 	if (pid) {
-		const firstAgent = chain[0] as SequentialStep;
+		const firstStep = chain[0];
+		const firstAgents = isParallelStep(firstStep)
+			? firstStep.parallel.map((t) => t.agent)
+			: [(firstStep as SequentialStep).agent];
 		ctx.pi.events.emit("subagent:started", {
 			id,
 			pid,
-			agent: firstAgent.agent,
-			task: firstAgent.task?.slice(0, 50),
-			chain: chain.map((s) => (s as SequentialStep).agent),
+			agent: firstAgents[0],
+			task: isParallelStep(firstStep)
+				? firstStep.parallel[0]?.task?.slice(0, 50)
+				: (firstStep as SequentialStep).task?.slice(0, 50),
+			chain: chain.map((s) =>
+				isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
+			),
 			cwd: runnerCwd,
 			asyncDir,
 		});
 	}
 
+	// Build chain description with parallel groups shown as [agent1+agent2]
+	const chainDesc = chain
+		.map((s) =>
+			isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
+		)
+		.join(" -> ");
+
 	return {
-		content: [
-			{ type: "text", text: `Async chain: ${chain.map((s) => (s as SequentialStep).agent).join(" -> ")} [${id}]` },
-		],
+		content: [{ type: "text", text: `Async chain: ${chainDesc} [${id}]` }],
 		details: { mode: "chain", results: [], asyncId: id, asyncDir },
 	};
 }

package/chain-execution.ts

@@ -493,7 +493,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			// Validate expected output file was created
 			if (behavior.output && r.exitCode === 0) {
 				try {
-					const expectedPath = behavior.output.startsWith("/") 
+					const expectedPath = path.isAbsolute(behavior.output)
 						? behavior.output 
 						: path.join(chainDir, behavior.output);
 					if (!fs.existsSync(expectedPath)) {

package/execution.ts

@@ -4,6 +4,8 @@
 
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { Message } from "@mariozechner/pi-ai";
 import type { AgentConfig } from "./agents.js";
 import {
@@ -123,7 +125,20 @@ export async function runSync(
 		tmpDir = tmp.dir;
 		args.push("--append-system-prompt", tmp.path);
 	}
-	args.push(`Task: ${task}`);
+
+	// When the task is too long for a CLI argument (Windows ENAMETOOLONG),
+	// write it to a temp file and use pi's @file syntax instead.
+	const TASK_ARG_LIMIT = 8000;
+	if (task.length > TASK_ARG_LIMIT) {
+		if (!tmpDir) {
+			tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+		}
+		const taskFilePath = path.join(tmpDir, "task.md");
+		fs.writeFileSync(taskFilePath, `Task: ${task}`, { mode: 0o600 });
+		args.push(`@${taskFilePath}`);
+	} else {
+		args.push(`Task: ${task}`);
+	}
 
 	const result: SingleResult = {
 		agent: agentName,

package/index.ts

@@ -67,9 +67,31 @@ function loadConfig(): ExtensionConfig {
 	return {};
 }
 
+/**
+ * Create a directory and verify it is actually accessible.
+ * On Windows with Azure AD/Entra ID, directories created shortly after
+ * wake-from-sleep can end up with broken NTFS ACLs (null DACL) when the
+ * cloud SID cannot be resolved without network connectivity. This leaves
+ * the directory completely inaccessible to the creating user.
+ */
+function ensureAccessibleDir(dirPath: string): void {
+	fs.mkdirSync(dirPath, { recursive: true });
+	try {
+		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+	} catch {
+		// Directory exists but is inaccessible — remove and recreate
+		try {
+			fs.rmSync(dirPath, { recursive: true, force: true });
+		} catch {}
+		fs.mkdirSync(dirPath, { recursive: true });
+		// Verify recovery succeeded
+		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+	}
+}
+
 export default function registerSubagentExtension(pi: ExtensionAPI): void {
-	fs.mkdirSync(RESULTS_DIR, { recursive: true });
-	fs.mkdirSync(ASYNC_DIR, { recursive: true });
+	ensureAccessibleDir(RESULTS_DIR);
+	ensureAccessibleDir(ASYNC_DIR);
 
 	// Cleanup old chain directories on startup (after 24h)
 	cleanupOldChainDirs();
@@ -152,13 +174,42 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 
 	const resultFileCoalescer = createFileCoalescer(handleResult, 50);
-	const watcher = fs.watch(RESULTS_DIR, (ev, file) => {
-		if (ev !== "rename" || !file) return;
-		const fileName = file.toString();
-		if (!fileName.endsWith(".json")) return;
-		resultFileCoalescer.schedule(fileName);
-	});
-	watcher.unref?.();
+	let watcher: fs.FSWatcher | null = null;
+	let watcherRestartTimer: ReturnType<typeof setTimeout> | null = null;
+
+	function startResultWatcher(): void {
+		watcherRestartTimer = null;
+		try {
+			watcher = fs.watch(RESULTS_DIR, (ev, file) => {
+				if (ev !== "rename" || !file) return;
+				const fileName = file.toString();
+				if (!fileName.endsWith(".json")) return;
+				resultFileCoalescer.schedule(fileName);
+			});
+			watcher.on("error", () => {
+				// Watcher died (directory deleted, ACL change, etc.) — restart after delay
+				watcher = null;
+				watcherRestartTimer = setTimeout(() => {
+					try {
+						fs.mkdirSync(RESULTS_DIR, { recursive: true });
+						startResultWatcher();
+					} catch {}
+				}, 3000);
+			});
+			watcher.unref?.();
+		} catch {
+			// fs.watch can throw if directory is inaccessible — retry after delay
+			watcher = null;
+			watcherRestartTimer = setTimeout(() => {
+				try {
+					fs.mkdirSync(RESULTS_DIR, { recursive: true });
+					startResultWatcher();
+				} catch {}
+			}, 3000);
+		}
+	}
+
+	startResultWatcher();
 	fs.readdirSync(RESULTS_DIR)
 		.filter((f) => f.endsWith(".json"))
 		.forEach((file) => resultFileCoalescer.schedule(file, 0));
@@ -229,7 +280,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 			const agents = discoverAgents(ctx.cwd, scope).agents;
 			const runId = randomUUID().slice(0, 8);
-			const shareEnabled = params.share !== false;
+			const shareEnabled = params.share === true;
 			const sessionEnabled = shareEnabled || Boolean(params.sessionDir);
 			const sessionRoot = sessionEnabled
 				? params.sessionDir
@@ -548,8 +599,32 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 
 				const ok = results.filter((r) => r.exitCode === 0).length;
 				const downgradeNote = parallelDowngraded ? " (async not supported for parallel)" : "";
+
+				// Aggregate outputs from all parallel tasks
+				const aggregatedOutput = results
+					.map((r, i) => {
+						const header = `=== Task ${i + 1}: ${r.agent} ===`;
+						const output = r.truncation?.text || getFinalOutput(r.messages);
+						const hasOutput = Boolean(output?.trim());
+						const status = r.exitCode !== 0
+							? `⚠️ FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
+							: r.error
+								? `⚠️ WARNING: ${r.error}`
+								: !hasOutput
+									? "⚠️ EMPTY OUTPUT"
+									: "";
+						const body = status
+							? (hasOutput ? `${status}\n${output}` : status)
+							: output;
+						return `${header}\n${body}`;
+					})
+					.join("\n\n");
+
+				const summary = `${ok}/${results.length} succeeded${downgradeNote}`;
+				const fullContent = `${summary}\n\n${aggregatedOutput}`;
+
 				return {
-					content: [{ type: "text", text: `${ok}/${results.length} succeeded${downgradeNote}` }],
+					content: [{ type: "text", text: fullContent }],
 					details: {
 						mode: "parallel",
 						results,
@@ -851,7 +926,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
 		return {
 			runId,
-			shareEnabled: true,
+			shareEnabled: false,
 			sessionDirForIndex: (idx?: number) => path.join(sessionRoot, `run-${idx ?? 0}`),
 			artifactsDir: getArtifactsDir(ctx.sessionManager.getSessionFile() ?? null),
 			artifactConfig: { ...DEFAULT_ARTIFACT_CONFIG } as ArtifactConfig,
@@ -1192,7 +1267,9 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		}
 	});
 	pi.on("session_shutdown", () => {
-		watcher.close();
+		watcher?.close();
+		if (watcherRestartTimer) clearTimeout(watcherRestartTimer);
+		watcherRestartTimer = null;
 		if (poller) clearInterval(poller);
 		poller = null;
 		// Clear all pending cleanup timers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -34,12 +34,21 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --experimental-strip-types --test *.test.ts"
+    "test": "node --experimental-strip-types --test *.test.ts",
+    "test:integration": "node --experimental-transform-types --import ./test/register-loader.mjs --test test/*.test.ts",
+    "test:e2e": "node --experimental-transform-types --import ./test/register-loader.mjs --test test/e2e-*.test.ts",
+    "test:all": "node --experimental-transform-types --import ./test/register-loader.mjs --test *.test.ts test/*.test.ts"
   },
   "pi": {
     "extensions": [
       "./index.ts",
       "./notify.ts"
     ]
+  },
+  "devDependencies": {
+    "@marcfargas/pi-test-harness": "^0.5.0",
+    "@mariozechner/pi-agent-core": "^0.54.0",
+    "@mariozechner/pi-ai": "^0.54.0",
+    "@mariozechner/pi-coding-agent": "^0.54.0"
   }
 }

package/parallel-utils.ts

@@ -0,0 +1,93 @@
+/**
+ * Parallel execution utilities for the async runner.
+ * Kept minimal and self-contained so the standalone runner can use them
+ * without pulling in the full extension dependency tree.
+ */
+
+/** A single agent step in the runner config */
+export interface RunnerSubagentStep {
+	agent: string;
+	task: string;
+	cwd?: string;
+	model?: string;
+	tools?: string[];
+	extensions?: string[];
+	mcpDirectTools?: string[];
+	systemPrompt?: string | null;
+	skills?: string[];
+	outputPath?: string;
+}
+
+/** Parallel step group — multiple agents running concurrently */
+export interface ParallelStepGroup {
+	parallel: RunnerSubagentStep[];
+	concurrency?: number;
+	failFast?: boolean;
+}
+
+export type RunnerStep = RunnerSubagentStep | ParallelStepGroup;
+
+export function isParallelGroup(step: RunnerStep): step is ParallelStepGroup {
+	return "parallel" in step && Array.isArray((step as ParallelStepGroup).parallel);
+}
+
+/** Flatten runner steps into individual SubagentSteps for status tracking */
+export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
+	const flat: RunnerSubagentStep[] = [];
+	for (const step of steps) {
+		if (isParallelGroup(step)) {
+			for (const task of step.parallel) flat.push(task);
+		} else {
+			flat.push(step);
+		}
+	}
+	return flat;
+}
+
+/** Run async tasks with bounded concurrency, preserving result order */
+export async function mapConcurrent<T, R>(
+	items: T[],
+	limit: number,
+	fn: (item: T, i: number) => Promise<R>,
+): Promise<R[]> {
+	// Clamp to at least 1; NaN/undefined/0/negative all become 1
+	const safeLimit = Math.max(1, Math.floor(limit) || 1);
+	const results: R[] = new Array(items.length);
+	let next = 0;
+
+	async function worker(): Promise<void> {
+		while (next < items.length) {
+			const i = next++;
+			results[i] = await fn(items[i], i);
+		}
+	}
+
+	await Promise.all(
+		Array.from({ length: Math.min(safeLimit, items.length) }, () => worker()),
+	);
+	return results;
+}
+
+/** Aggregate outputs from parallel tasks into a single string for {previous} */
+export function aggregateParallelOutputs(
+	results: Array<{ agent: string; output: string; exitCode: number | null; error?: string }>,
+): string {
+	return results
+		.map((r, i) => {
+			const header = `=== Parallel Task ${i + 1} (${r.agent}) ===`;
+			const hasOutput = Boolean(r.output?.trim());
+			const status =
+				r.exitCode === -1
+					? "⏭️ SKIPPED"
+					: r.exitCode !== 0
+						? `⚠️ FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
+						: !hasOutput
+							? "⚠️ EMPTY OUTPUT"
+							: "";
+			const body = status ? (hasOutput ? `${status}\n${r.output}` : status) : r.output;
+			return `${header}\n${body}`;
+		})
+		.join("\n\n");
+}
+
+export const MAX_PARALLEL_CONCURRENCY = 4;