pi-taskflow 0.0.1 → 0.0.2

package/extensions/index.ts

@@ -105,14 +105,41 @@ async function runFlow(
 		});
 	};
 
-	return executeTaskflow(state, {
-		cwd: ctx.cwd,
-		agents,
-		globalThinking: settings.globalThinking,
-		signal,
-		persist: (s) => saveRun(s),
-		onProgress: (s) => emit(s),
-	});
+	// Throttled persistence: avoid disk writes on every sub-item event.
+	let lastPersist = 0;
+	const persistThrottled = (s: RunState) => {
+		const now = Date.now();
+		if (now - lastPersist >= 1000) {
+			lastPersist = now;
+			saveRun(s);
+		}
+	};
+
+	// ~8fps heartbeat drives all rendering: it naturally caps the frame rate
+	// (no event bursts) while keeping the spinner, elapsed timers, live tokens
+	// and the latest message current. Phase events only mutate `state`.
+	let heartbeat: ReturnType<typeof setInterval> | undefined;
+	if (onUpdate) {
+		heartbeat = setInterval(() => {
+			if (state.status === "running") emit(state);
+		}, 120);
+		(heartbeat as { unref?: () => void }).unref?.();
+	}
+
+	try {
+		const result = await executeTaskflow(state, {
+			cwd: ctx.cwd,
+			agents,
+			globalThinking: settings.globalThinking,
+			signal,
+			persist: persistThrottled,
+		});
+		return result;
+	} finally {
+		if (heartbeat) clearInterval(heartbeat);
+		saveRun(state); // force-persist terminal state
+		emit(state); // final render reflecting terminal state
+	}
 }
 
 export default function (pi: ExtensionAPI) {
@@ -152,9 +179,10 @@ export default function (pi: ExtensionAPI) {
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
-		promptSnippet: "Run a multi-phase subagent workflow (declarative DAG with map fan-out)",
+		promptSnippet: "Orchestrate many subagents over a whole codebase/many items (declarative DAG with map fan-out)",
 		promptGuidelines: [
-			"Use taskflow when a task needs several coordinated subagent steps, fan-out over many items, or a repeatable orchestration — not for a single delegated task (use subagent for that).",
+			"Prefer taskflow whenever a request spans a whole project/codebase or many items — e.g. 'explore / 探索 / 审计 / analyze the project', auditing endpoints, reviewing or migrating many files/modules, or cross-checked research. It fans out to many subagents across phases and aggregates the result, keeping intermediate work out of your context.",
+			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. Use the plain subagent tool only for a single delegated task.",
 			"For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 		],
 

package/extensions/render.ts

@@ -1,22 +1,101 @@
 /**
  * TUI rendering for the taskflow tool and commands.
+ *
+ * Design goals: high information density, column alignment, and width-safe
+ * single-cell status glyphs (no double-width emoji that break alignment).
  */
 
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import { formatUsage } from "./runner.ts";
+import { formatTokens, type UsageStats } from "./runner.ts";
 import type { PhaseState, RunState } from "./store.ts";
+import type { Phase } from "./schema.ts";
 
-const STATUS_ICON: Record<PhaseState["status"], (t: Theme) => string> = {
-	pending: (t) => t.fg("dim", "○"),
-	running: (t) => t.fg("warning", "⏳"),
-	done: (t) => t.fg("success", "✓"),
-	failed: (t) => t.fg("error", "✗"),
-	skipped: (t) => t.fg("muted", "⊘"),
+// Single-width glyphs (Geometric Shapes / check marks) — keep columns aligned.
+const ICON: Record<PhaseState["status"], { ch: string; color: string }> = {
+	done: { ch: "✓", color: "success" },
+	running: { ch: "◐", color: "warning" },
+	failed: { ch: "✗", color: "error" },
+	skipped: { ch: "⊘", color: "muted" },
+	pending: { ch: "○", color: "dim" },
 };
 
-export function phaseIcon(status: PhaseState["status"], theme: Theme): string {
-	return (STATUS_ICON[status] ?? STATUS_ICON.pending)(theme);
+function icon(status: PhaseState["status"], theme: Theme): string {
+	if (status === "running") return theme.fg("warning", spinnerFrame());
+	const i = ICON[status] ?? ICON.pending;
+	return theme.fg(i.color as any, i.ch);
+}
+
+function shortModel(model?: string): string {
+	if (!model) return "";
+	return model.split("/").pop() ?? model;
+}
+
+// Braille dots spinner (ora classic) — smooth, clockwise, single-width.
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function spinnerFrame(): string {
+	return SPINNER[Math.floor(Date.now() / 120) % SPINNER.length];
+}
+
+// Elapsed as 5s / 3m30s / 1h05m
+function elapsed(ms: number): string {
+	const s = Math.floor(ms / 1000);
+	if (s < 60) return `${s}s`;
+	if (s < 3600) {
+		const m = Math.floor(s / 60);
+		const ss = s % 60;
+		return `${m}m${ss.toString().padStart(2, "0")}s`;
+	}
+	const h = Math.floor(s / 3600);
+	const mm = Math.floor((s % 3600) / 60);
+	return `${h}h${mm.toString().padStart(2, "0")}m`;
+}
+
+function phaseElapsed(ps: PhaseState): number {
+	if (!ps.startedAt) return 0;
+	return (ps.endedAt ?? Date.now()) - ps.startedAt;
+}
+
+function miniBar(done: number, total: number, theme: Theme, width = 8): string {
+	if (total <= 0) return "";
+	const filled = Math.max(0, Math.min(width, Math.round((done / total) * width)));
+	return theme.fg("accent", "━".repeat(filled)) + theme.fg("dim", "─".repeat(width - filled));
+}
+
+function compactUsage(usage: UsageStats | undefined, theme: Theme): string {
+	if (!usage) return "";
+	const parts: string[] = [];
+	if (usage.turns) parts.push(theme.fg("dim", `${usage.turns}t`));
+	if (usage.input) parts.push(theme.fg("dim", `↑${formatTokens(usage.input)}`));
+	if (usage.output) parts.push(theme.fg("dim", `↓${formatTokens(usage.output)}`));
+	if (usage.cost) parts.push(theme.fg("muted", `$${usage.cost.toFixed(3)}`));
+	return parts.join(" ");
+}
+
+function liveUsageStr(usage: UsageStats | undefined, theme: Theme): string {
+	if (!usage) return "";
+	const parts: string[] = [];
+	if (usage.input) parts.push(theme.fg("dim", `↑${formatTokens(usage.input)}`));
+	if (usage.output) parts.push(theme.fg("dim", `↓${formatTokens(usage.output)}`));
+	if (usage.cost) parts.push(theme.fg("muted", `$${usage.cost.toFixed(3)}`));
+	return parts.join(" ");
+}
+
+function aggregateCost(state: RunState): number {
+	let c = 0;
+	for (const p of Object.values(state.phases)) c += p.usage?.cost ?? 0;
+	return c;
+}
+
+function runElapsed(state: RunState): number {
+	const starts = Object.values(state.phases)
+		.map((p) => p.startedAt)
+		.filter((x): x is number => !!x);
+	if (starts.length === 0) return 0;
+	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;
 }
 
 export function summarizeRun(state: RunState): string {
@@ -31,39 +110,141 @@ export function summarizeRun(state: RunState): string {
 	return bits.join(", ");
 }
 
-/** Compact one-line-per-phase progress block. */
-export function renderProgress(state: RunState, theme: Theme): string {
-	let text =
-		theme.fg("toolTitle", theme.bold("taskflow ")) +
+/** Build the detail column for a phase (the right-hand info). */
+function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): string {
+	const type = phase.type ?? "agent";
+	if (!ps || ps.status === "pending") return theme.fg("dim", "—");
+
+	if (ps.status === "skipped") return theme.fg("muted", "skipped · upstream failed");
+
+	const isFanout = type === "map" || type === "parallel";
+
+	if (ps.status === "failed") {
+		const e = (ps.error ?? "failed").replace(/\s+/g, " ");
+		const snip = e.length > 56 ? `${e.slice(0, 56)}…` : e;
+		if (isFanout && ps.subProgress) {
+			const { done, total, failed } = ps.subProgress;
+			return (
+				theme.fg("toolOutput", `${done - failed}/${total}`) +
+				theme.fg("error", ` ${failed}✗`) +
+				(snip ? theme.fg("error", `  ${snip}`) : "")
+			);
+		}
+		return theme.fg("error", snip);
+	}
+
+	const t = phaseElapsed(ps);
+	const time = t ? theme.fg("dim", elapsed(t)) : "";
+
+	if (ps.status === "running") {
+		const model = shortModel(ps.model);
+		const tokens = liveUsageStr(ps.usage, theme);
+		if (isFanout && ps.subProgress) {
+			const { done, total, running, failed } = ps.subProgress;
+			let s = `${miniBar(done, total, theme)} ${theme.fg("toolOutput", `${done}/${total}`)}`;
+			if (running) s += theme.fg("dim", ` · ${running} run`);
+			if (failed) s += theme.fg("error", ` · ${failed}✗`);
+			if (tokens) s += `  ${tokens}`;
+			if (time) s += `  ${time}`;
+			return s;
+		}
+		let s = model ? theme.fg("accent", model) : theme.fg("warning", "running…");
+		if (tokens) s += `  ${tokens}`;
+		if (time) s += `  ${time}`;
+		return s;
+	}
+
+	// done
+	if (isFanout) {
+		const { done = 0, total = 0, failed = 0 } = ps.subProgress ?? {};
+		let s = theme.fg("success", `${total}✓`);
+		if (failed) s = theme.fg("toolOutput", `${done - failed}/${total}`) + theme.fg("error", ` ${failed}✗`);
+		const u = compactUsage(ps.usage, theme);
+		if (u) s += `  ${u}`;
+		if (time) s += `  ${time}`;
+		return s;
+	}
+	// single-agent done
+	const model = shortModel(ps.model);
+	const u = compactUsage(ps.usage, theme);
+	let s = "";
+	if (model) s += theme.fg("accent", model);
+	if (u) s += (s ? "  " : "") + u;
+	if (time) s += `  ${time}`;
+	return s || theme.fg("dim", "done");
+}
+
+/** Header line: status glyph + name + compact totals. */
+function headerLine(state: RunState, theme: Theme): string {
+	const phases = Object.values(state.phases);
+	const done = phases.filter((p) => p.status === "done").length;
+	const failed = phases.filter((p) => p.status === "failed").length;
+	const running = phases.filter((p) => p.status === "running").length;
+	const total = state.def.phases.length;
+
+	const head =
+		state.status === "completed"
+			? theme.fg("success", "✓")
+			: state.status === "failed"
+				? theme.fg("error", "✗")
+				: state.status === "paused"
+					? theme.fg("warning", "‖")
+					: theme.fg("warning", spinnerFrame());
+
+	let line =
+		`${head} ${theme.fg("toolTitle", theme.bold("taskflow"))} ` +
 		theme.fg("accent", state.flowName) +
-		theme.fg("muted", `  ${summarizeRun(state)}`);
-
-	for (const phase of state.def.phases) {
-		const ps = state.phases[phase.id] ?? { id: phase.id, status: "pending" as const };
-		const icon = phaseIcon(ps.status, theme);
-		const type = theme.fg("dim", `[${phase.type ?? "agent"}]`);
-		let line = `\n  ${icon} ${theme.fg("accent", phase.id)} ${type}`;
-		if (ps.status === "running") line += theme.fg("warning", " …");
-		if (ps.usage?.cost) line += theme.fg("dim", `  ${formatUsage(ps.usage, ps.model)}`);
-		if (ps.status === "failed" && ps.error) {
-			const e = ps.error.length > 60 ? `${ps.error.slice(0, 60)}…` : ps.error;
-			line += theme.fg("error", `  ${e}`);
+		theme.fg("muted", `  ${done}/${total}`);
+	if (running) line += theme.fg("warning", ` · ${running}▸`);
+	if (failed) line += theme.fg("error", ` · ${failed}✗`);
+	const cost = aggregateCost(state);
+	if (cost) line += theme.fg("muted", ` · $${cost.toFixed(3)}`);
+	const el = runElapsed(state);
+	if (el) line += theme.fg("dim", ` · ${elapsed(el)}`);
+	return line;
+}
+
+/** The full dense progress block (header + aligned phase rows). */
+export function renderProgress(state: RunState, theme: Theme): string {
+	const phases = state.def.phases;
+	const idW = Math.max(...phases.map((p) => p.id.length), 2);
+	const typeW = Math.max(...phases.map((p) => (p.type ?? "agent").length), 4);
+
+	let text = headerLine(state, theme);
+	for (const phase of phases) {
+		const ps = state.phases[phase.id];
+		const status = ps?.status ?? "pending";
+		const id = phase.id.padEnd(idW);
+		const type = (phase.type ?? "agent").padEnd(typeW);
+		const detail = phaseDetail(phase, ps, theme);
+		text +=
+			`\n  ${icon(status, theme)} ` +
+			theme.fg(status === "pending" ? "dim" : "text", id) +
+			"  " +
+			theme.fg("dim", type) +
+			"  " +
+			detail;
+
+		// Live activity sub-line (only while running, only if we have a message).
+		if (status === "running" && ps?.liveText) {
+			const indent = " ".repeat(2 + 2 + idW + 2);
+			const msg = ps.liveText.replace(/\s+/g, " ").trim();
+			const snip = msg.length > 88 ? `${msg.slice(0, 88)}…` : msg;
+			text += `\n${indent}${theme.fg("dim", "› ")}${theme.fg("muted", snip)}`;
 		}
-		text += line;
 	}
 	return text;
 }
 
-export function renderRunResult(state: RunState, finalOutput: string, theme: Theme, expanded: boolean): Container | Text {
+export function renderRunResult(
+	state: RunState,
+	finalOutput: string,
+	theme: Theme,
+	expanded: boolean,
+): Container | Text {
 	if (!expanded) {
-		const icon =
-			state.status === "completed"
-				? theme.fg("success", "✓")
-				: state.status === "failed"
-					? theme.fg("error", "✗")
-					: theme.fg("warning", "⏸");
-		let text = `${icon} ${renderProgress(state, theme)}`;
-		text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+		let text = renderProgress(state, theme);
+		text += `\n  ${theme.fg("dim", "Ctrl+O to expand")}`;
 		return new Text(text, 0, 0);
 	}
 

package/extensions/runner.ts

@@ -38,13 +38,21 @@ export interface RunResult {
 	errorMessage?: string;
 }
 
+export interface LiveUpdate {
+	/** Latest assistant text or tool activity (single-line, truncated upstream). */
+	text: string;
+	usage: UsageStats;
+	model?: string;
+}
+
 export interface RunOptions {
 	model?: string;
 	thinking?: string;
 	tools?: string[];
 	cwd?: string;
 	signal?: AbortSignal;
-	onText?: (text: string) => void;
+	/** Fires on each assistant turn with the latest activity + accumulated usage. */
+	onLive?: (live: LiveUpdate) => void;
 }
 
 export function isFailed(r: RunResult): boolean {
@@ -63,6 +71,44 @@ function getFinalOutput(messages: Message[]): string {
 	return "";
 }
 
+/** One-line description of the most recent assistant activity (text or tool call). */
+function describeActivity(msg: Message): string {
+	if (msg.role !== "assistant") return "";
+	let lastText = "";
+	let lastTool = "";
+	for (const part of (msg as any).content ?? []) {
+		if (part.type === "text" && part.text?.trim()) lastText = part.text.trim();
+		else if (part.type === "toolCall") lastTool = summarizeToolCall(part.name, part.arguments ?? {});
+	}
+	const chosen = lastText || lastTool;
+	return chosen.replace(/\s+/g, " ").trim();
+}
+
+function summarizeToolCall(name: string, args: Record<string, unknown>): string {
+	const short = (p: unknown) => {
+		const s = String(p ?? "");
+		return s.length > 48 ? `${s.slice(0, 48)}…` : s;
+	};
+	switch (name) {
+		case "bash":
+			return `$ ${short(args.command)}`;
+		case "read":
+			return `read ${short(args.path ?? args.file_path)}`;
+		case "write":
+			return `write ${short(args.path ?? args.file_path)}`;
+		case "edit":
+			return `edit ${short(args.path ?? args.file_path)}`;
+		case "grep":
+			return `grep ${short(args.pattern)}`;
+		case "find":
+			return `find ${short(args.pattern)}`;
+		case "ls":
+			return `ls ${short(args.path)}`;
+		default:
+			return `${name}`;
+	}
+}
+
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
 	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-taskflow-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
@@ -132,6 +178,7 @@ export async function runAgentTask(
 	let tmpPromptPath: string | null = null;
 
 	const messages: Message[] = [];
+	let lastActivity = "";
 	const result: RunResult = {
 		agent: agentName,
 		task,
@@ -186,8 +233,10 @@ export async function runAgentTask(
 						if (!result.model && (msg as any).model) result.model = (msg as any).model;
 						if ((msg as any).stopReason) result.stopReason = (msg as any).stopReason;
 						if ((msg as any).errorMessage) result.errorMessage = (msg as any).errorMessage;
-						const text = getFinalOutput([msg]);
-						if (text && opts.onText) opts.onText(text);
+						const activity = describeActivity(msg);
+						if (activity) lastActivity = activity;
+						if (opts.onLive)
+							opts.onLive({ text: lastActivity, usage: { ...result.usage }, model: result.model });
 					}
 				}
 			};

package/extensions/runtime.ts

@@ -12,7 +12,7 @@
 
 import type { AgentConfig } from "./agents.ts";
 import { coerceArray, interpolate, type InterpolationContext, safeParse } from "./interpolate.ts";
-import { aggregateUsage, emptyUsage, isFailed, mapWithConcurrencyLimit, runAgentTask, type RunResult, type UsageStats } from "./runner.ts";
+import { aggregateUsage, emptyUsage, isFailed, type LiveUpdate, mapWithConcurrencyLimit, runAgentTask, type RunResult, type UsageStats } from "./runner.ts";
 import { dependenciesOf, finalPhase, type Phase, type Taskflow, topoLayers } from "./schema.ts";
 import { hashInput, type PhaseState, type RunState } from "./store.ts";
 
@@ -79,12 +79,14 @@ function mergePhaseState(
 		.map((r, i) => `### [${i + 1}/${results.length}] ${r.agent}${isFailed(r) ? " (failed)" : ""}\n\n${r.output}`)
 		.join("\n\n---\n\n");
 	const jsonArray = parseJson ? results.map((r) => safeParse(r.output) ?? r.output) : undefined;
+	const failedCount = results.filter(isFailed).length;
 	return {
 		id,
 		status: anyFailed ? "failed" : "done",
 		output: combinedText,
 		json: jsonArray,
 		usage,
+		subProgress: { done: results.length, total: results.length, running: 0, failed: failedCount },
 		error: anyFailed ? results.filter(isFailed).map((r) => `${r.agent}: ${r.errorMessage ?? r.stderr}`).join("; ") : undefined,
 		inputHash,
 		endedAt: Date.now(),
@@ -96,13 +98,14 @@ async function executePhase(
 	state: RunState,
 	deps: RuntimeDeps,
 	prior: PhaseState | undefined,
+	emitProgress: () => void,
 ): Promise<PhaseState> {
 	const type = phase.type ?? "agent";
 	const concurrency = phase.concurrency ?? state.def.concurrency ?? 8;
 	const previousOutput = lastCompletedOutput(state, phase);
 	const run = deps.runTask ?? runAgentTask;
 
-	const runOne = (agentName: string, task: string, _locals?: Record<string, unknown>) =>
+	const runOne = (agentName: string, task: string, onLive?: (l: LiveUpdate) => void) =>
 		run(
 			deps.cwd,
 			deps.agents,
@@ -114,12 +117,51 @@ async function executePhase(
 				tools: phase.tools,
 				cwd: phase.cwd,
 				signal: deps.signal,
+				onLive,
 			},
 			deps.globalThinking,
 		);
 
 	const parseJson = phase.output === "json";
 
+	// Runs a list of sub-tasks with live fan-out progress + aggregate live usage/activity.
+	const runFanout = async (items: Array<{ agent: string; task: string }>): Promise<RunResult[]> => {
+		let done = 0;
+		let running = 0;
+		let failed = 0;
+		const total = items.length;
+		const live = state.phases[phase.id];
+		const liveUsages: UsageStats[] = items.map(() => emptyUsage());
+		let latestText = "";
+		let latestModel: string | undefined;
+		const refresh = () => {
+			if (live) {
+				live.subProgress = { done, total, running, failed };
+				live.usage = aggregateUsage(liveUsages);
+				live.liveText = latestText;
+				live.model = latestModel;
+			}
+			emitProgress();
+		};
+		refresh();
+		return mapWithConcurrencyLimit(items, concurrency, async (it, idx) => {
+			running++;
+			refresh();
+			const r = await runOne(it.agent, it.task, (l) => {
+				liveUsages[idx] = l.usage;
+				if (l.text) latestText = l.text;
+				if (l.model) latestModel = l.model;
+				refresh();
+			});
+			running--;
+			done++;
+			if (isFailed(r)) failed++;
+			liveUsages[idx] = r.usage;
+			refresh();
+			return r;
+		});
+	};
+
 	if (type === "agent" || type === "gate") {
 		const ctx = buildInterpolationContext(state, previousOutput);
 		const { text } = interpolate(phase.task ?? "", ctx);
@@ -127,7 +169,15 @@ async function executePhase(
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
-		const r = await runOne(phase.agent ?? defaultAgent(deps), text);
+		const live = state.phases[phase.id];
+		const r = await runOne(phase.agent ?? defaultAgent(deps), text, (l) => {
+			if (live) {
+				live.liveText = l.text;
+				live.usage = l.usage;
+				live.model = l.model;
+			}
+			emitProgress();
+		});
 		return resultToPhaseState(phase.id, r, inputHash, parseJson);
 	}
 
@@ -141,7 +191,7 @@ async function executePhase(
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
-		const results = await mapWithConcurrencyLimit(branches, concurrency, (b) => runOne(b.agent, b.task));
+		const results = await runFanout(branches);
 		return mergePhaseState(phase.id, results, inputHash, parseJson);
 	}
 
@@ -172,7 +222,7 @@ async function executePhase(
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
-		const results = await mapWithConcurrencyLimit(tasks, concurrency, (t) => runOne(t.agent, t.task));
+		const results = await runFanout(tasks);
 		return mergePhaseState(phase.id, results, inputHash, parseJson);
 	}
 
@@ -184,7 +234,15 @@ async function executePhase(
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
-		const r = await runOne(phase.agent ?? defaultAgent(deps), text);
+		const live = state.phases[phase.id];
+		const r = await runOne(phase.agent ?? defaultAgent(deps), text, (l) => {
+			if (live) {
+				live.liveText = l.text;
+				live.usage = l.usage;
+				live.model = l.model;
+			}
+			emitProgress();
+		});
 		return resultToPhaseState(phase.id, r, inputHash, parseJson);
 	}
 
@@ -273,7 +331,7 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 			};
 			deps.onProgress?.(state);
 
-			const ps = await executePhase(phase, state, deps, prior);
+			const ps = await executePhase(phase, state, deps, prior, () => deps.onProgress?.(state));
 			state.phases[phase.id] = ps;
 			deps.persist?.(state);
 			deps.onProgress?.(state);

package/extensions/store.ts

@@ -33,6 +33,10 @@ export interface PhaseState {
 	inputHash?: string;
 	startedAt?: number;
 	endedAt?: number;
+	/** Live fan-out progress for map/parallel phases. */
+	subProgress?: { done: number; total: number; running: number; failed: number };
+	/** Latest activity line from the running subagent(s). */
+	liveText?: string;
 }
 
 export interface RunState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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",

package/skills/taskflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskflow
-description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use when a task needs several coordinated subagent steps, fan-out over many items (files, endpoints, modules), cross-checked/adversarial review, or a repeatable orchestration you want to save and rerun. Not for a single delegated task — use the subagent tool for that.
+description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use whenever a request spans a whole project or many items — deeply exploring / 探索 / auditing / 审计 / analyzing a codebase, reviewing or migrating many files or modules in parallel, cross-checked/adversarial review, codebase-wide research, or any repeatable orchestration you want to save and rerun. Prefer this over ad-hoc parallel subagents when the work has multiple phases or dynamic fan-out over a discovered list. Not for a single delegated task — use the subagent tool for that.
 ---
 
 # Taskflow