pi-taskflow 0.0.1 → 0.0.3

package/DESIGN.md

@@ -288,12 +288,12 @@ export async function runTaskflow(def, args, ctx): Promise<TaskflowResult>
 
 ## 5. 路线图
 
-| 版本 | 范围 |
-|------|------|
-| **v0.1** | DSL + schema + runtime（agent/parallel/map/reduce）+ `taskflow` 工具 + `/tf run` + 内存隔离 + 流式进度 |
-| **v0.2** | 保存/动态命令注册 + 跨 session 恢复 + `gate` 阶段 + run 历史 TUI |
-| **v0.3** | examples + SKILL.md（教 LLM 写定义）+ YAML 支持 + 发布 npm |
-| **v0.4** | 真·后台执行（detached + 轮询）+ 成本预估/上限 + 内置 `deep-research` 工作流 |
+| 版本 | 范围 | 状态 |
+|------|------|------|
+| **v0.1** | DSL + schema + runtime（agent/parallel/map/reduce）+ `taskflow` 工具 + `/tf run` + 内存隔离 + 流式进度 | ✅ 已发布 (npm 0.0.1) |
+| **v0.2** | 保存/动态命令注册 + 跨 session 恢复 + `gate` 真门控 + run 历史交互 TUI | ✅ 已完成 (npm 0.0.3) |
+| **v0.3** | examples + SKILL.md（教 LLM 写定义）+ YAML 支持 + 发布 npm | 🚧 examples/SKILL/npm 已做；YAML 待办 |
+| **v0.4** | 真·后台执行（detached + 轮询）+ 成本预估/上限 + 内置 `deep-research` 工作流 | ⏳ 待办 |
 
 ---
 

package/extensions/index.ts

@@ -17,6 +17,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
+import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
 import { executeTaskflow, type RuntimeResult } from "./runtime.ts";
 import { finalPhase, type Taskflow, validateTaskflow } from "./schema.ts";
 import {
@@ -105,14 +106,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 +180,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'.",
 		],
 
@@ -278,15 +307,30 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (sub === "runs") {
-				const runs = listRuns(ctx.cwd);
+				const runs = listRuns(ctx.cwd, 50);
 				if (runs.length === 0) {
 					ctx.ui.notify("No taskflow runs yet.", "info");
 					return;
 				}
-				ctx.ui.notify(
-					runs.map((r) => `${r.runId} [${r.status}] ${r.flowName} — ${summarizeRun(r)}`).join("\n"),
-					"info",
-				);
+				if (!ctx.hasUI) {
+					ctx.ui.notify(
+						runs.map((r) => `${r.runId} [${r.status}] ${r.flowName} — ${summarizeRun(r)}`).join("\n"),
+						"info",
+					);
+					return;
+				}
+				const result = await ctx.ui.custom<RunHistoryResult | undefined>((_tui, theme, _kb, done) => {
+					return new RunHistoryComponent(runs, theme, (r) => done(r));
+				});
+				if (result?.action === "resume") {
+					if (ctx.isIdle()) {
+						pi.sendUserMessage(
+							`Resume the taskflow run "${result.runId}" using the taskflow tool with action="resume", runId="${result.runId}".`,
+						);
+					} else {
+						ctx.ui.notify("Agent is busy; try /tf resume when idle.", "warning");
+					}
+				}
 				return;
 			}
 

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,160 @@ 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") {
+		const reason = (ps.error ?? "upstream failed").replace(/\s+/g, " ");
+		const snip = reason.length > 52 ? `${reason.slice(0, 52)}…` : reason;
+		return theme.fg("muted", `skipped · ${snip}`);
+	}
+
+	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);
+	if (ps.gate) {
+		const badge =
+			ps.gate.verdict === "block" ? theme.fg("error", theme.bold("BLOCK")) : theme.fg("success", "PASS");
+		let g = badge;
+		if (ps.gate.reason) {
+			const r = ps.gate.reason.replace(/\s+/g, " ");
+			g += theme.fg("dim", ` ${r.length > 44 ? `${r.slice(0, 44)}…` : r}`);
+		}
+		if (model) g += `  ${theme.fg("dim", model)}`;
+		if (time) g += `  ${time}`;
+		return g;
+	}
+	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 === "blocked"
+					? 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}✗`);
+	if (state.status === "blocked") line += theme.fg("error", " · blocked");
+	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/runs-view.ts

@@ -0,0 +1,141 @@
+/**
+ * Interactive run-history view for `/tf runs` (ctx.ui.custom).
+ * List view: navigate runs; Enter → detail; r → resume; Esc/q → close.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { renderProgress, summarizeRun } from "./render.ts";
+import type { RunState } from "./store.ts";
+
+export interface RunHistoryResult {
+	action: "resume";
+	runId: string;
+}
+
+function statusBadge(status: RunState["status"], theme: Theme): string {
+	switch (status) {
+		case "completed":
+			return theme.fg("success", "✓ done");
+		case "failed":
+			return theme.fg("error", "✗ failed");
+		case "blocked":
+			return theme.fg("error", "⊗ blocked");
+		case "paused":
+			return theme.fg("warning", "‖ paused");
+		default:
+			return theme.fg("warning", "◐ running");
+	}
+}
+
+function timeAgo(ts: number): string {
+	const s = Math.floor((Date.now() - ts) / 1000);
+	if (s < 60) return `${s}s ago`;
+	if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+	if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+	return `${Math.floor(s / 86400)}d ago`;
+}
+
+function isResumable(r: RunState): boolean {
+	return r.status === "paused" || r.status === "failed" || r.status === "blocked";
+}
+
+export class RunHistoryComponent {
+	private runs: RunState[];
+	private theme: Theme;
+	private onDone: (result?: RunHistoryResult) => void;
+	private selected = 0;
+	private mode: "list" | "detail" = "list";
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(runs: RunState[], theme: Theme, onDone: (result?: RunHistoryResult) => void) {
+		this.runs = runs;
+		this.theme = theme;
+		this.onDone = onDone;
+	}
+
+	handleInput(data: string): void {
+		this.invalidate();
+		if (this.mode === "detail") {
+			if (matchesKey(data, "escape")) {
+				this.mode = "list";
+				return;
+			}
+			if (data === "r" && isResumable(this.runs[this.selected])) {
+				this.onDone({ action: "resume", runId: this.runs[this.selected].runId });
+			}
+			return;
+		}
+		// list mode
+		if (matchesKey(data, "escape") || data === "q" || matchesKey(data, "ctrl+c")) {
+			this.onDone();
+			return;
+		}
+		if (matchesKey(data, "up")) {
+			this.selected = (this.selected - 1 + this.runs.length) % this.runs.length;
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.selected = (this.selected + 1) % this.runs.length;
+			return;
+		}
+		if (matchesKey(data, "return")) {
+			this.mode = "detail";
+			return;
+		}
+		if (data === "r" && isResumable(this.runs[this.selected])) {
+			this.onDone({ action: "resume", runId: this.runs[this.selected].runId });
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const th = this.theme;
+		const lines: string[] = [""];
+
+		if (this.mode === "detail") {
+			const run = this.runs[this.selected];
+			lines.push(truncateToWidth(`  ${th.fg("accent", "Run ")}${th.fg("muted", run.runId)}`, width));
+			lines.push("");
+			for (const l of renderProgress(run, th).split("\n")) lines.push(truncateToWidth(l, width));
+			lines.push("");
+			const hint = isResumable(run) ? "Esc back · r resume" : "Esc back";
+			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}`, width));
+			lines.push("");
+			this.cachedWidth = width;
+			this.cachedLines = lines;
+			return lines;
+		}
+
+		// list mode
+		const header =
+			th.fg("borderMuted", "─".repeat(3)) +
+			th.fg("accent", " Taskflow runs ") +
+			th.fg("borderMuted", "─".repeat(Math.max(0, width - 18)));
+		lines.push(truncateToWidth(header, width));
+		lines.push("");
+
+		this.runs.forEach((run, i) => {
+			const sel = i === this.selected;
+			const marker = sel ? th.fg("accent", "❯ ") : "  ";
+			const badge = statusBadge(run.status, th);
+			const name = sel ? th.fg("text", run.flowName) : th.fg("muted", run.flowName);
+			const meta = th.fg("dim", `${summarizeRun(run)} · ${timeAgo(run.updatedAt)}`);
+			lines.push(truncateToWidth(`  ${marker}${badge}  ${name}  ${meta}`, width));
+		});
+
+		lines.push("");
+		lines.push(truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}`, width));
+		lines.push("");
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

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,8 +169,18 @@ async function executePhase(
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
-		const r = await runOne(phase.agent ?? defaultAgent(deps), text);
-		return resultToPhaseState(phase.id, r, inputHash, parseJson);
+		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();
+		});
+		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
+		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
+		return ps;
 	}
 
 	if (type === "parallel") {
@@ -141,7 +193,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 +224,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 +236,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);
 	}
 
@@ -227,6 +287,36 @@ function defaultAgent(deps: RuntimeDeps): string {
 	return deps.agents[0]?.name ?? "default";
 }
 
+/**
+ * Parse a gate phase's output into a verdict. Blocks the flow only on an
+ * explicit negative signal; ambiguous output passes (fail-open).
+ * Accepts JSON ({continue|pass: bool} or {verdict: "..."}) or a text marker
+ * `VERDICT: PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT` (last occurrence wins).
+ */
+export function parseGateVerdict(output: string): { verdict: "pass" | "block"; reason?: string } {
+	const json = safeParse(output);
+	if (json && typeof json === "object") {
+		const o = json as Record<string, unknown>;
+		if (typeof o.continue === "boolean") return { verdict: o.continue ? "pass" : "block", reason: asReason(o.reason) };
+		if (typeof o.pass === "boolean") return { verdict: o.pass ? "pass" : "block", reason: asReason(o.reason) };
+		if (typeof o.verdict === "string") {
+			const block = /block|fail|stop|reject|halt|\bno\b/i.test(o.verdict);
+			return { verdict: block ? "block" : "pass", reason: asReason(o.reason) };
+		}
+	}
+	const matches = [...output.matchAll(/VERDICT\s*[:=]\s*(PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT)/gi)];
+	if (matches.length) {
+		const v = matches[matches.length - 1][1].toUpperCase();
+		const pass = v === "PASS" || v === "OK";
+		return { verdict: pass ? "pass" : "block" };
+	}
+	return { verdict: "pass" };
+}
+
+function asReason(v: unknown): string | undefined {
+	return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+
 /**
  * Execute a full taskflow. Mutates and persists `state` as it progresses.
  */
@@ -239,6 +329,9 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 	deps.onProgress?.(state);
 
 	let aborted = false;
+	let gateBlocked = false;
+	let gateReason = "";
+	let gateOutput = "";
 
 	for (const layer of layers) {
 		if (deps.signal?.aborted) {
@@ -250,13 +343,13 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 		await mapWithConcurrencyLimit(layer, layerConcurrency, async (phase) => {
 			// Snapshot prior state BEFORE marking running, so resume cache checks work.
 			const prior = state.phases[phase.id];
-			// Skip if a dependency failed (unless this phase is optional).
+			// Skip if a dependency failed, or an upstream gate blocked the flow.
 			const failedDep = dependenciesOf(phase).some((d) => state.phases[d]?.status === "failed");
-			if (failedDep) {
+			if (gateBlocked || failedDep) {
 				state.phases[phase.id] = {
 					id: phase.id,
 					status: "skipped",
-					error: "Upstream dependency failed",
+					error: gateBlocked ? `Gate blocked${gateReason ? `: ${gateReason}` : ""}` : "Upstream dependency failed",
 					endedAt: Date.now(),
 					usage: emptyUsage(),
 				};
@@ -273,8 +366,13 @@ 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;
+			if ((phase.type ?? "agent") === "gate" && ps.gate?.verdict === "block") {
+				gateBlocked = true;
+				gateReason = ps.gate.reason ?? "";
+				gateOutput = ps.output ?? "";
+			}
 			deps.persist?.(state);
 			deps.onProgress?.(state);
 		});
@@ -284,14 +382,19 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 	const finalState = state.phases[fp.id];
 	const anyFailed = Object.values(state.phases).some((p) => p.status === "failed");
 
-	state.status = aborted ? "paused" : anyFailed ? "failed" : "completed";
+	state.status = aborted ? "paused" : gateBlocked ? "blocked" : anyFailed ? "failed" : "completed";
 	deps.persist?.(state);
 	deps.onProgress?.(state);
 
+	let finalOutput = finalState?.output ?? "(no output)";
+	if (gateBlocked && (!finalState || finalState.status === "skipped")) {
+		finalOutput = `Gate blocked the workflow.${gateReason ? `\nReason: ${gateReason}` : ""}${gateOutput ? `\n\n${gateOutput}` : ""}`;
+	}
+
 	const totalUsage = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
 	return {
 		state,
-		finalOutput: finalState?.output ?? "(no output)",
+		finalOutput,
 		ok: state.status === "completed",
 		totalUsage,
 	};

package/extensions/store.ts

@@ -33,6 +33,12 @@ 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;
+	/** Gate verdict (gate phases only). */
+	gate?: { verdict: "pass" | "block"; reason?: string };
 }
 
 export interface RunState {
@@ -40,7 +46,7 @@ export interface RunState {
 	flowName: string;
 	def: Taskflow;
 	args: Record<string, unknown>;
-	status: "running" | "completed" | "failed" | "paused";
+	status: "running" | "completed" | "failed" | "paused" | "blocked";
 	phases: Record<string, PhaseState>;
 	createdAt: number;
 	updatedAt: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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
@@ -55,9 +55,29 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 | `agent` | one subagent runs `task` |
 | `parallel` | run `branches[]` concurrently |
 | `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
-| `gate` | quality/review step (a focused agent pass) |
+| `gate` | quality/review step that can **halt the flow** (see below) |
 | `reduce` | aggregate `from[]` phases into one output |
 
+### Gate phases (quality control)
+
+A `gate` phase runs an agent to review upstream output and can **block the rest
+of the workflow**. End the gate task's instructions by asking the agent to emit a
+verdict the runtime can read:
+
+- a final line `VERDICT: PASS` or `VERDICT: BLOCK` (also accepts OK/FAIL/STOP/REJECT/HALT), or
+- JSON like `{"continue": false, "reason": "missing auth checks"}` / `{"verdict": "block", "reason": "..."}`
+
+On **BLOCK**, downstream phases are skipped and the run ends as `blocked` with the
+reason surfaced. Ambiguous output **fails open** (treated as PASS) so a gate never
+halts the flow by accident. Example gate task:
+
+```
+Review the audit results below. If any endpoint is missing auth, end with
+"VERDICT: BLOCK" and a one-line reason; otherwise end with "VERDICT: PASS".
+
+{steps.audit.output}
+```
+
 ### Interpolation
 
 - `{args.X}` — invocation argument