pi-taskflow 0.0.10 → 0.0.12

package/extensions/agents.ts

@@ -23,7 +23,7 @@ export interface AgentConfig {
 	model?: string;
 	thinking?: string;
 	systemPrompt: string;
-	source: "user" | "project";
+	source: "user" | "project" | "built-in";
 	filePath: string;
 }
 
@@ -32,7 +32,7 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: "user" | "project" | "built-in"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 	if (!fs.existsSync(dir)) return agents;
 
@@ -121,14 +121,23 @@ export function discoverAgents(
 	cwd: string,
 	scope: AgentScope,
 	overrides?: Record<string, AgentOverride>,
+	modelRoles?: Record<string, string>,
 ): AgentDiscoveryResult {
+	// Built-in agents ship with the package (extensions/agents/*.md)
+	// PI_TASKFLOW_BUILTIN_AGENTS_DIR allows tests to override or disable (empty = skip)
+	const builtInDirEnv = process.env.PI_TASKFLOW_BUILTIN_AGENTS_DIR;
+	const builtInDir = builtInDirEnv ? builtInDirEnv : builtInDirEnv === undefined ? path.resolve(import.meta.dirname, "agents") : "";
+	const builtInAgents = builtInDir ? loadAgentsFromDir(builtInDir, "built-in") : [];
+
 	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
 
+	// Layer order: built-in → user → project (later layers override earlier)
 	const agentMap = new Map<string, AgentConfig>();
+	for (const a of builtInAgents) agentMap.set(a.name, a);
 	if (scope === "both") {
 		for (const a of userAgents) agentMap.set(a.name, a);
 		for (const a of projectAgents) agentMap.set(a.name, a);
@@ -155,12 +164,33 @@ export function discoverAgents(
 		}
 	}
 
+	// Resolve {{role}} model references (e.g. {{fast}} → openrouter/deepseek/v4-flash)
+	if (modelRoles) {
+		for (const agent of agentMap.values()) {
+			const resolved = resolveModelRole(agent.model, modelRoles);
+			if (resolved !== agent.model) agent.model = resolved;
+		}
+	}
+
 	return { agents: Array.from(agentMap.values()), projectAgentsDir };
 }
 
 export interface SubagentSettings {
 	agentOverrides?: Record<string, AgentOverride>;
 	globalThinking?: string;
+	modelRoles?: Record<string, string>;
+}
+
+/**
+ * Resolve `{{roleName}}` model references against a role→model mapping.
+ * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
+ * Returns undefined if the value is not a role reference or the role is unmapped.
+ */
+export function resolveModelRole(model: string | undefined, roles?: Record<string, string>): string | undefined {
+	if (!model || !roles) return model;
+	const match = model.match(/^\{\{(\w+)\}\}$/);
+	if (!match) return model;
+	return roles[match[1]] ?? undefined;
 }
 
 /** Read subagent overrides from ~/.pi/agent/settings.json (shared with the subagent extension). */
@@ -172,6 +202,7 @@ export function readSubagentSettings(): SubagentSettings {
 		return {
 			agentOverrides: raw.subagents?.agentOverrides,
 			globalThinking: raw.subagents?.globalThinking ?? raw.defaultThinkingLevel,
+			modelRoles: raw.modelRoles,
 		};
 	} catch {
 		return {};

package/extensions/index.ts

@@ -10,9 +10,12 @@
  * host conversation context — only the final phase output is returned.
  */
 
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
@@ -50,8 +53,8 @@ const ShorthandStep = Type.Object(
 );
 
 const TaskflowParams = Type.Object({
-	action: StringEnum(["run", "save", "resume", "list", "agents"] as const, {
-		description: "What to do: run a flow, save a definition, resume a paused run, list saved flows, or list available agents you can use in phases",
+	action: StringEnum(["run", "save", "resume", "list", "agents", "init"] as const, {
+		description: "What to do: run a flow, save a definition, resume a paused run, list saved flows, list available agents, or init model role configuration",
 		default: "run",
 	}),
 	name: Type.Optional(Type.String({ description: "Name of a saved flow (for run/save without inline define)" })),
@@ -167,7 +170,28 @@ async function runFlow(
 		// the heartbeat timer is cleared by the finally block below.
 		const settings = readSubagentSettings();
 		const scope: AgentScope = def.agentScope ?? "user";
-		const { agents } = discoverAgents(ctx.cwd, scope, settings.agentOverrides);
+		const { agents } = discoverAgents(ctx.cwd, scope, settings.agentOverrides, settings.modelRoles);
+
+		// Hint: if any agent still has unresolved {{role}} references, suggest configuring modelRoles
+		const unresolvedRoles = agents
+			.filter(a => a.model && /^\{\{\w+\}\}$/.test(a.model))
+			.map(a => a.model!.match(/^\{\{(\w+)\}\}$/)![1]);
+		if (unresolvedRoles.length > 0) {
+			const unique = [...new Set(unresolvedRoles)];
+			console.warn(
+				`[taskflow] Hint: ${unique.length} model role(s) not configured: ${unique.join(", ")}. ` +
+				`Agents will use the default model (slower / less optimal). ` +
+				`Run /tf init to auto-generate modelRoles config.`
+			);
+		}
+
+		// Pre-flight: warn if any phase references an agent not in the registry
+		const agentNames = new Set(agents.map(a => a.name));
+		for (const p of def.phases ?? []) {
+			if (p.agent && !agentNames.has(p.agent)) {
+				console.warn(`[taskflow] Warning: phase '${p.id}' references agent '${p.agent}' which was not found. Available: ${[...agentNames].join(", ")}`);
+			}
+		}
 
 		const result = await executeTaskflow(state, {
 			cwd: ctx.cwd,
@@ -208,7 +232,20 @@ export default function (pi: ExtensionAPI) {
 		}
 	};
 
-	pi.on("session_start", async (_e, ctx) => registerSavedFlowCommands(ctx));
+	pi.on("session_start", async (_e, ctx) => {
+		registerSavedFlowCommands(ctx);
+
+		// Hint: prompt to configure model roles if not set
+		try {
+			const settings = readSubagentSettings();
+			if (!settings.modelRoles) {
+				console.warn(
+					`[taskflow] Model roles not configured — agents will use the default model. ` +
+					`Run /tf init to generate a recommended modelRoles config.`
+				);
+			}
+		} catch {}
+	});
 
 	// ---- The LLM-callable tool ----
 	pi.registerTool({
@@ -235,10 +272,59 @@ export default function (pi: ExtensionAPI) {
 		async execute(_id, params, signal, onUpdate, ctx) {
 			const action = params.action ?? "run";
 
-			// agents — list available agents the LLM can use in phase definitions
+			// init — configure model roles
+	if (action === "init") {
+		const settingsPath = path.join(getAgentDir(), "settings.json");
+		let existing: Record<string, unknown> = {};
+		try { existing = JSON.parse(fs.readFileSync(settingsPath, "utf-8")); } catch {}
+
+		const roleDescs: Record<string, string> = {
+			fast: "cheap & quick (executor, scout, recover, verifier, doc-writer, test-engineer)",
+			strong: "balanced (planner, reviewer, executor-code)",
+			thinker: "deep analysis (analyst, critic)",
+			arbiter: "final judgment (plan-arbiter, final-arbiter)",
+			vision: "multimodal (executor-ui, visual-explorer)",
+			reasoner: "cautious reasoning (risk-reviewer, security-reviewer)",
+		};
+
+		if (existing.modelRoles) {
+			const roles = existing.modelRoles as Record<string, string>;
+			const text = [
+				`Model roles already configured in ${settingsPath}:`,
+				...Object.entries(roles).map(([k, v]) => `  ${k.padEnd(10)} → ${v}  (${roleDescs[k] ?? ""})`),
+				``,
+				`To reconfigure, run /tf init interactively or edit settings.json directly.`,
+			].join("\n");
+			return { content: [{ type: "text", text }], details: { action } satisfies TaskflowDetails };
+		}
+
+		const defaults: Record<string, string> = {
+			fast: "openrouter/deepseek/deepseek-v4-flash",
+			strong: "openrouter/xiaomi/mimo-v2.5-pro",
+			thinker: "openrouter/deepseek/deepseek-v4-pro",
+			arbiter: "openrouter/qwen/qwen3.7-max",
+			vision: "minimax/MiniMax-M3",
+			reasoner: "z-ai/glm-5.1",
+		};
+
+		const newSettings = { ...existing, modelRoles: defaults };
+		fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+		fs.writeFileSync(settingsPath, JSON.stringify(newSettings, null, 2) + "\n", "utf-8");
+
+		const text = [
+			`Wrote default model roles to ${settingsPath}:`,
+			...Object.entries(defaults).map(([k, v]) => `  ${k.padEnd(10)} → ${v}  (${roleDescs[k]})`),
+			``,
+			`These models require provider-specific API keys. Edit settings.json or run /tf init interactively.`,
+		].join("\n");
+		return { content: [{ type: "text", text }], details: { action } satisfies TaskflowDetails };
+	}
+
+	// agents — list available agents the LLM can use in phase definitions
 			if (action === "agents") {
 				const scope = params.scope ?? "both";
-				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, undefined);
+				const settings2 = readSubagentSettings();
+				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, undefined, settings2.modelRoles);
 				const text = agents.length
 					? agents
 							.map(
@@ -378,9 +464,9 @@ export default function (pi: ExtensionAPI) {
 
 	// ---- The /tf user command ----
 	pi.registerCommand("tf", {
-		description: "Taskflow: list | run <name> | show <name> | runs",
+		description: "Taskflow: list | run <name> | show <name> | runs | init",
 		getArgumentCompletions: (prefix) => {
-			const subs = ["list", "run", "show", "runs", "resume"];
+			const subs = ["list", "run", "show", "runs", "resume", "init"];
 			const items = subs.map((s) => ({ value: s, label: s }));
 			const filtered = items.filter((i) => i.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -472,6 +558,90 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			if (sub === "init") {
+				const settingsPath = path.join(getAgentDir(), "settings.json");
+				let existing: Record<string, unknown> = {};
+				try { existing = JSON.parse(fs.readFileSync(settingsPath, "utf-8")); } catch {}
+				const currentRoles = (existing.modelRoles ?? {}) as Record<string, string>;
+
+				// Role definitions: name → { description, recommended models }
+				// Role definitions: name → description (no per-role filtering)
+				const roleDefs: Array<{ role: string; desc: string }> = [
+					{ role: "fast",     desc: "Cheap & quick — high-volume, low-stakes tasks (executor, scout, recover, verifier, doc-writer, test-engineer)" },
+					{ role: "strong",   desc: "Balanced — planning, review, moderate complexity (planner, reviewer, executor-code)" },
+					{ role: "thinker",  desc: "Deep analysis — requirements, ambiguity detection, critique (analyst, critic)" },
+					{ role: "arbiter",  desc: "Final judgment — tiebreak, plan quality gates (plan-arbiter, final-arbiter)" },
+					{ role: "vision",   desc: "Multimodal — UI work, design reading, Figma analysis (executor-ui, visual-explorer)" },
+					{ role: "reasoner", desc: "Cautious reasoning — security, risk review, sensitive changes (risk-reviewer, security-reviewer)" },
+				];
+
+				if (!ctx.hasUI) {
+					if (Object.keys(currentRoles).length > 0) {
+						ctx.ui.notify(
+							`Current model roles:\n` +
+							Object.entries(currentRoles).map(([k, v]) => `  ${k.padEnd(10)} → ${v}`).join("\n"),
+						"info"
+						);
+					} else {
+						ctx.ui.notify(
+							`No modelRoles configured. Run /tf init in an interactive session to select models.`,
+						"warning"
+						);
+					}
+					return;
+				}
+
+				// Use the user's scoped/enabled models (same list as /model command).
+				// Fall back to all auth-configured models if none are scoped.
+				const enabledModels = (existing.enabledModels as string[] | undefined) ?? [];
+				const modelList = enabledModels.length > 0
+					? enabledModels
+					: ctx.modelRegistry.getAvailable().map(m => `${m.provider}/${m.id}`);
+
+				// Interactive: walk through each role using the same model list
+				const chosen: Record<string, string> = {};
+				for (const rd of roleDefs) {
+					const current = currentRoles[rd.role];
+
+					const seen = new Set<string>();
+					const options: string[] = [];
+					for (const m of modelList) {
+						if (seen.has(m)) continue;
+						seen.add(m);
+						options.push(m === current ? `${m} (current)` : m);
+					}
+					options.push("───────────────");
+					options.push("Custom (type your own)");
+
+					const title = `Model for '${rd.role}' — ${rd.desc}` + (current ? `\nCurrent: ${current}` : "");
+					const pick = await ctx.ui.select(title, options, { signal: ctx.signal });
+
+					if (!pick || pick.startsWith("───")) {
+						chosen[rd.role] = current ?? modelList[0] ?? "";
+						continue;
+					}
+
+					if (pick === "Custom (type your own)") {
+						const custom = await ctx.ui.input(`Enter model identifier for '${rd.role}'`, "provider/model-id", { signal: ctx.signal });
+						chosen[rd.role] = custom?.trim() || current || "";
+					} else {
+						chosen[rd.role] = pick.replace(" (current)", "");
+					}
+				}
+
+				// Save
+				const newSettings = { ...existing, modelRoles: chosen };
+				fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+				fs.writeFileSync(settingsPath, JSON.stringify(newSettings, null, 2) + "\n", "utf-8");
+
+				ctx.ui.notify(
+					`Saved model roles to ${settingsPath}:\n` +
+					Object.entries(chosen).map(([k, v]) => `  ${k.padEnd(10)} → ${v}`).join("\n"),
+				"info"
+				);
+				return;
+			}
+
 			ctx.ui.notify(`Unknown subcommand: ${sub}`, "warning");
 		},
 	});

package/extensions/render.ts

@@ -53,7 +53,12 @@ function elapsed(ms: number): string {
 
 function phaseElapsed(ps: PhaseState): number {
 	if (!ps.startedAt) return 0;
-	return (ps.endedAt ?? Date.now()) - ps.startedAt;
+	// Guard against a stale/clock-skewed endedAt that precedes startedAt (e.g. a
+	// resumed phase that still carries a previous attempt's endedAt): treat such
+	// an end time as absent and fall back to now. Finally clamp to >= 0 so the
+	// TUI never shows a negative (and frozen) elapsed time.
+	const end = ps.endedAt && ps.endedAt >= ps.startedAt ? ps.endedAt : Date.now();
+	return Math.max(0, end - ps.startedAt);
 }
 
 function miniBar(done: number, total: number, theme: Theme, width = 8): string {
@@ -91,7 +96,7 @@ function runElapsed(state: RunState): number {
 	const min = Math.min(...starts);
 	const ends = Object.values(state.phases).map((p) => p.endedAt ?? Date.now());
 	const max = ends.length ? Math.max(...ends) : Date.now();
-	return max - min;
+	return Math.max(0, max - min);
 }
 
 export function summarizeRun(state: RunState): string {

package/extensions/runner.ts

@@ -42,8 +42,24 @@ export interface RunOptions {
 	signal?: AbortSignal;
 	/** Fires on each assistant turn with the latest activity + accumulated usage. */
 	onLive?: (live: LiveUpdate) => void;
+	/**
+	 * Idle watchdog: if the subagent produces no stdout for this many ms, it is
+	 * considered stalled (hung stream / provider stall / tool deadlock) and is
+	 * killed (SIGTERM → SIGKILL). Resets on every stdout chunk. 0/undefined keeps
+	 * the prior behaviour (no idle timeout). Defaults to DEFAULT_IDLE_TIMEOUT_MS.
+	 */
+	idleTimeoutMs?: number;
 }
 
+/**
+ * Default idle-watchdog window. A subagent that emits nothing on stdout for this
+ * long is treated as wedged and killed so a single stalled child cannot hang the
+ * entire taskflow forever (the only previous escape was a manual user abort).
+ * 5 minutes is generous enough for slow reasoning/long tool calls while still
+ * bounding a true hang.
+ */
+export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
+
 export function isFailed(r: RunResult): boolean {
 	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
 }
@@ -306,6 +322,7 @@ export async function runAgentTask(
 		args.push(`Task: ${task}`);
 
 		let wasAborted = false;
+		let idleTimedOut = false;
 		const exitCode = await new Promise<number>((resolve) => {
 			const invocation = getPiInvocation(args);
 			const proc = spawn(invocation.command, invocation.args, {
@@ -315,12 +332,40 @@ export async function runAgentTask(
 			});
 			let buffer = "";
 
+			// Idle watchdog: a subagent that goes silent on stdout for too long is
+			// treated as wedged and killed, so one stalled child cannot hang the
+			// whole taskflow forever. The timer is reset on every stdout chunk and
+			// torn down on close/error.
+			const idleMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+			let idleTimer: ReturnType<typeof setTimeout> | undefined;
+			let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+			const clearTimers = () => {
+				if (idleTimer) clearTimeout(idleTimer);
+				if (forceKillTimer) clearTimeout(forceKillTimer);
+			};
+			const hardKill = () => {
+				proc.kill("SIGTERM");
+				forceKillTimer = setTimeout(() => proc.kill("SIGKILL"), 5000);
+				forceKillTimer.unref();
+			};
+			const armIdle = () => {
+				if (idleTimer) clearTimeout(idleTimer);
+				if (idleMs <= 0) return; // disabled
+				idleTimer = setTimeout(() => {
+					idleTimedOut = true;
+					hardKill();
+				}, idleMs);
+				idleTimer.unref();
+			};
+			armIdle();
+
 			const processLine = (line: string) => {
 				const live = foldEventLine(acc, line);
 				if (live && opts.onLive) opts.onLive(live);
 			};
 
 			proc.stdout.on("data", (data) => {
+				armIdle(); // progress observed — reset the idle watchdog
 				buffer += data.toString();
 				const lines = buffer.split("\n");
 				buffer = lines.pop() || "";
@@ -330,10 +375,12 @@ export async function runAgentTask(
 				result.stderr += data.toString();
 			});
 			proc.on("close", (code) => {
+				clearTimers();
 				if (buffer.trim()) processLine(buffer);
 				resolve(code ?? 0);
 			});
 			proc.on("error", (err) => {
+				clearTimers();
 				if (!result.stderr) result.stderr = err.message;
 				if (!result.errorMessage) result.errorMessage = err.message;
 				resolve(1);
@@ -364,7 +411,13 @@ export async function runAgentTask(
 		result.stopReason = acc.stopReason;
 		result.errorMessage = acc.errorMessage;
 		result.output = getFinalOutput(acc.messages);
-		if (wasAborted) {
+		if (idleTimedOut) {
+			// Distinct, actionable signal: the child was killed for being idle, not
+			// a user abort. stopReason "error" keeps it in the failed bucket so the
+			// runtime's retry/fail handling treats it as a real failure.
+			result.stopReason = "error";
+			result.errorMessage = `Subagent stalled: no output for ${Math.round((opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS) / 1000)}s (idle timeout) — killed`;
+		} else if (wasAborted) {
 			result.stopReason = "aborted";
 			result.errorMessage = "Subagent was aborted";
 		}

package/extensions/runtime.ts

@@ -437,7 +437,7 @@ async function executePhase(
 		const { text } = interpolate(phase.task ?? "", ctx);
 		const fullTask = preRead + text;
 		const agentName = resolveAgent(phase.agent, deps, state);
-		const inputHash = hashInput(phase.id, agentName, fullTask);
+		const inputHash = hashInput(phase.id, agentName, phase.model ?? "", fullTask);
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
@@ -455,7 +455,7 @@ async function executePhase(
 				task: preRead + r.text,
 			};
 		});
-		const inputHash = hashInput(phase.id, JSON.stringify(branches));
+		const inputHash = hashInput(phase.id, phase.model ?? "", JSON.stringify(branches));
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
@@ -485,7 +485,7 @@ async function executePhase(
 				task: preRead + interpolate(phase.task ?? "", localCtx).text,
 			};
 		});
-		const inputHash = hashInput(phase.id, JSON.stringify(tasks));
+		const inputHash = hashInput(phase.id, phase.model ?? "", JSON.stringify(tasks));
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
@@ -496,7 +496,7 @@ async function executePhase(
 	if (type === "approval") {
 		const ctx = buildInterpolationContext(state, previousOutput);
 		const message = interpolate(phase.task ?? "Approve to continue?", ctx).text;
-		const inputHash = hashInput(phase.id, "approval", message);
+		const inputHash = hashInput(phase.id, phase.model ?? "", "approval", message);
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
@@ -853,11 +853,19 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 			}
 
 			const startedAt = Date.now();
+			// Re-running a phase (resume after a previous failed/done attempt) must
+			// start from a clean "running" state. Spreading the prior PhaseState
+			// would carry over its terminal `endedAt` (and `error`/`gate`/`output`),
+			// leaving a running phase with an old endedAt < new startedAt — which
+			// renders as a frozen NEGATIVE elapsed time in the TUI. Keep only the
+			// fields that are still meaningful across attempts (model, attempts).
+			const priorPs = state.phases[phase.id];
 			state.phases[phase.id] = {
-				...(state.phases[phase.id] ?? { id: phase.id }),
 				id: phase.id,
 				status: "running",
 				startedAt,
+				...(priorPs?.model ? { model: priorPs.model } : {}),
+				...(priorPs?.attempts ? { attempts: priorPs.attempts } : {}),
 			};
 			safeProgress(deps, state);
 

package/extensions/schema.ts

@@ -342,9 +342,9 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 			errors.push(`Phase '${p.id}': agent name '${p.agent}' uses underscores — use hyphens (e.g. 'executor-code' not 'executor_code')`);
 		}
 
-		// Phase id convention: hyphens only (consistent with agent naming)
+		// Phase id convention: hyphens only (consistent with interpolation placeholders like {steps.audit-each.output})
 		if (p.id && p.id.includes("_")) {
-			errors.push(`Phase '${p.id}': id uses underscores — use hyphens for consistency with agent naming convention`);
+			errors.push(`Phase '${p.id}': id uses underscores — use hyphens for consistency with interpolation placeholders (e.g. {steps.audit-each.output})`);
 		}
 	}
 
@@ -363,7 +363,7 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 	const VALID_AGENT_RE = /^[a-z][a-z0-9-]*$/;
 	for (const p of flow.phases) {
 		if (!p?.id) continue;
-		if (p.agent && !VALID_AGENT_RE.test(p.agent)) {
+		if (p.agent && !p.agent.includes("_") && !VALID_AGENT_RE.test(p.agent)) {
 			errors.push(`Phase '${p.id}': agent '${p.agent}' has invalid name format (expected lowercase alphanumeric with hyphens)`);
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Lightweight workflow orchestration for the Pi coding agent — declarative multi-phase taskflows with dynamic fan-out, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",
@@ -36,7 +36,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/render.test.ts test/desugar.test.ts",
+    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/render.test.ts test/desugar.test.ts",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts"
   },
   "pi": {