pi-taskflow 0.0.5 → 0.0.6

package/DESIGN.md

@@ -204,6 +204,19 @@ pi-taskflow/
 | `map` | 对上游数组**动态 fan-out**，每项一个 agent | ≤concurrency |
 | `gate` | 质量门 / 对抗 review（可决定是否继续） | 1+ |
 | `reduce` | 把多结果聚合为一（synthesize） | 1 |
+| `approval` | **人在环**：暂停等待 approve / reject / edit | 1 |
+| `flow` | 把一个**已保存的 taskflow** 当作单个 phase 运行（组合复用） | 子流程并发 |
+
+### 3.3b 控制流 / 可靠性字段（任意 phase）
+
+| 字段 | 语义 |
+|------|------|
+| `when` | 条件守卫：表达式为假则 skip 该 phase。支持 `{refs}`、`== != < > <= >=`、`&& \|\| !`、括号、字符串/数字字面量。解析失败 fail-open（仍运行） |
+| `join` | 依赖 join：`all`（默认，等全部 dep）/ `any`（OR-join，任一 dep 完成即运行） |
+| `retry` | `{max, backoffMs, factor}`：失败重试，延迟 = `backoffMs * factor^attempt` |
+| `use` / `with` | `flow` 子流程的名字与入参（入参字符串值会插值） |
+
+顶层 `budget: {maxUSD, maxTokens}`：累计成本/token 超限即停（剩余 phase skip，运行态 `blocked`）。
 
 ### 3.4 模板插值
 
@@ -293,7 +306,8 @@ export async function runTaskflow(def, args, ctx): Promise<TaskflowResult>
 | **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` 工作流 | ⏳ 待办 |
+| **v0.6** | 控制流 & 可靠性：`when` 条件分支 + `join:any` OR-join + 声明式 `retry` + `approval` 人在环 + `flow` 子流程组合 + `budget` 成本上限 | ✅ 已完成 |
+| **v0.7+** | 真·后台执行（detached + 轮询）+ 事件/cron 触发 + 成本**预估** + mermaid DAG 导出 + 内置 `deep-research` 工作流 | ⏳ 待办 |
 
 ---
 

package/README.md

@@ -1,8 +1,14 @@
-# pi-taskflow
+<div align="center">
 
-[![npm](https://img.shields.io/npm/v/pi-taskflow.svg)](https://www.npmjs.com/package/pi-taskflow)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-[![Pi coding agent](https://img.shields.io/badge/for-Pi%20coding%20agent-7c3aed.svg)](https://pi.dev)
+<img src="./assets/hero.png" alt="pi-taskflow — declarative, multi-phase subagent workflows" width="880">
+
+<p>
+  <a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/v/pi-taskflow?style=flat-square&color=B692FF&label=npm" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-43D9AD?style=flat-square" alt="MIT license"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-6E8BFF?style=flat-square" alt="for the Pi coding agent"></a>
+</p>
+
+</div>
 
 > Lightweight workflow orchestration for the [Pi coding agent](https://pi.dev).
 
@@ -172,9 +178,34 @@ writes and verifies its own test suites, caught here mid-block by a quality gate
 | `map` | fan out over an array — one subagent per item, `{item}` bound | `over`, `task` |
 | `gate` | quality/review step that can **halt the flow** | `task` |
 | `reduce` | aggregate `from[]` phase outputs into one | `from`, `task` |
+| `approval` | **human-in-the-loop** pause — approve / reject / edit before continuing | — |
+| `flow` | run a **saved sub-flow** as one phase (composition/reuse) | `use` |
 
 Every phase needs `id`. Optional fields: `agent`, `dependsOn`, `output`,
-`model`, `thinking`, `tools`, `cwd`, `concurrency`, `final`, `optional`.
+`model`, `thinking`, `tools`, `cwd`, `concurrency`, `final`, `optional`,
+`when` (conditional guard), `join` (`all`\|`any` dependency join), `retry`
+(`{max, backoffMs, factor}`), and `with` (args for a `flow` phase).
+Run-wide: `budget: {maxUSD, maxTokens}` halts the flow when exceeded.
+
+### Control flow & reliability
+
+- **`when`** — skip a phase unless an expression is truthy. Supports `{refs}`,
+  `== != < > <= >=`, `&& || !`, parentheses, and quoted strings/numbers, e.g.
+  `"when": "{steps.triage.json.route} == deep"`. Pair with `join: "any"` on the
+  merge phase to build real if/else routing. Parse errors **fail open**.
+- **`join: "any"`** — an OR-join: the phase runs as soon as *one* dependency
+  completes (default `"all"` waits for every dep).
+- **`retry`** — `{ "max": 2, "backoffMs": 500, "factor": 2 }` retries a failing
+  subagent with fixed (`factor:1`) or exponential backoff; usage is summed and
+  the attempt count shows as `↻N` in the TUI.
+- **`approval`** — pause for a human (`select`: Approve / Reject / Edit). Reject
+  halts the flow; Edit injects the typed note as the phase output for downstream
+  steps. Non-interactive runs auto-approve.
+- **`flow`** — `{ "type": "flow", "use": "deep-research", "with": { "topic": "{item}" } }`
+  runs a saved flow as a phase (recursion is detected and rejected).
+- **`budget`** — a run-wide `{maxUSD, maxTokens}` ceiling; once exceeded, pending
+  phases are skipped (and in-flight fan-out stops spawning) and the run is
+  `blocked`.
 
 ### `output` format
 
@@ -265,7 +296,10 @@ are honored, letting you tweak model, thinking, or tools per agent across all fl
 
 ## Status & limits
 
-- **v0.0.4** — DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`),
+- **v0.0.6** — control flow & reliability: conditional `when` guards, `join: any`
+  OR-joins, declarative `retry`/backoff, `approval` (human-in-the-loop) phases,
+  `flow` (saved sub-flow composition), and run-wide `budget` caps — on top of the
+  DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`),
   inline + saved flows, cross-session resume, live progress, isolated context.
   Default `concurrency` is 8 (set on the flow; per-phase `concurrency` overrides
   for that phase).
@@ -279,7 +313,8 @@ are honored, letting you tweak model, thinking, or tools per agent across all fl
 ### What it doesn't do (yet)
 
 - **No detached background execution.** A run needs the pi session to stay open.
-  True background execution is on the roadmap.
+  True background execution (and event/cron triggers on top of it) is on the
+  roadmap.
 - **No `output: "file"`.** Outputs are text/JSON only. Write files via agent
   tool calls if needed.
 - **`map` requires a JSON array.** The `over` field must resolve to
@@ -293,9 +328,9 @@ are honored, letting you tweak model, thinking, or tools per agent across all fl
 npm install
 npm run typecheck
 node --experimental-strip-types --test test/interpolate.test.ts \
-  test/schema.test.ts test/runtime.test.ts test/runner.test.ts \
-  test/store.test.ts test/agents.test.ts test/render.test.ts \
-  test/desugar.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
 
 # real end-to-end (spawns live subagents; needs model access)
 PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts

package/examples/conditional-research.json

@@ -0,0 +1,56 @@
+{
+  "name": "conditional-research",
+  "description": "Triage a topic, route to a deep or quick research branch (conditional `when` + OR-join), gate the result, and report.",
+  "version": 1,
+  "args": {
+    "topic": { "description": "The subject to research" }
+  },
+  "concurrency": 4,
+  "agentScope": "user",
+  "budget": { "maxUSD": 1.0 },
+  "phases": [
+    {
+      "id": "triage",
+      "type": "agent",
+      "agent": "analyst",
+      "task": "Decide how much research the topic \"{args.topic}\" needs. Output ONLY JSON: {\"route\": \"deep\"} for broad/ambiguous topics, or {\"route\": \"quick\"} for narrow/well-defined ones.",
+      "output": "json"
+    },
+    {
+      "id": "deep",
+      "type": "agent",
+      "agent": "explorer",
+      "when": "{steps.triage.json.route} == deep",
+      "dependsOn": ["triage"],
+      "task": "Do a thorough, multi-angle investigation of \"{args.topic}\". Cover background, key players, trade-offs, and open questions.",
+      "retry": { "max": 2, "backoffMs": 500, "factor": 2 }
+    },
+    {
+      "id": "quick",
+      "type": "agent",
+      "agent": "explorer",
+      "when": "{steps.triage.json.route} == quick",
+      "dependsOn": ["triage"],
+      "task": "Give a concise, focused answer on \"{args.topic}\" with the 3 most important points.",
+      "retry": { "max": 2, "backoffMs": 500, "factor": 2 }
+    },
+    {
+      "id": "review",
+      "type": "gate",
+      "agent": "critic",
+      "join": "any",
+      "from": ["deep", "quick"],
+      "dependsOn": ["deep", "quick"],
+      "task": "Review the research below for unsupported claims. If it is solid, end with 'VERDICT: PASS'; if it is too thin, end with 'VERDICT: BLOCK' and one reason.\n\n{steps.deep.output}{steps.quick.output}"
+    },
+    {
+      "id": "report",
+      "type": "reduce",
+      "from": ["review"],
+      "dependsOn": ["review"],
+      "agent": "doc-writer",
+      "task": "Write a clean markdown brief on \"{args.topic}\" from the validated research:\n\n{steps.deep.output}{steps.quick.output}",
+      "final": true
+    }
+  ]
+}

package/examples/guarded-refactor.json

@@ -0,0 +1,50 @@
+{
+  "name": "guarded-refactor",
+  "description": "Plan a change, pause for human approval before touching code (HITL), then implement with retries and a final review gate. Budget-capped.",
+  "version": 1,
+  "args": {
+    "target": { "default": "src", "description": "Directory or module to refactor" },
+    "goal": { "description": "What the refactor should achieve" }
+  },
+  "concurrency": 4,
+  "agentScope": "user",
+  "budget": { "maxUSD": 2.0 },
+  "phases": [
+    {
+      "id": "plan",
+      "type": "agent",
+      "agent": "planner",
+      "task": "Produce a concrete, step-by-step refactor plan for {args.target} to achieve: {args.goal}. List the files you would change and the risks."
+    },
+    {
+      "id": "approve",
+      "type": "approval",
+      "dependsOn": ["plan"],
+      "task": "Review the refactor plan above. Approve to proceed, reject to abort, or edit to add constraints the implementer must follow."
+    },
+    {
+      "id": "implement",
+      "type": "agent",
+      "agent": "executor_code",
+      "dependsOn": ["approve"],
+      "task": "Implement the approved plan for {args.target}.\nPlan:\n{steps.plan.output}\nExtra human guidance (if any):\n{steps.approve.output}",
+      "retry": { "max": 1, "backoffMs": 1000 }
+    },
+    {
+      "id": "review",
+      "type": "gate",
+      "agent": "reviewer",
+      "dependsOn": ["implement"],
+      "task": "Review the implementation report below. If it is correct and complete, end with 'VERDICT: PASS'; otherwise 'VERDICT: BLOCK' with reasons.\n\n{steps.implement.output}"
+    },
+    {
+      "id": "summary",
+      "type": "reduce",
+      "from": ["review"],
+      "dependsOn": ["review"],
+      "agent": "doc-writer",
+      "task": "Write a short changelog entry summarizing what was done:\n\n{steps.implement.output}",
+      "final": true
+    }
+  ]
+}

package/extensions/agents.ts

@@ -55,7 +55,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = (() => {
+			try {
+				return parseFrontmatter<Record<string, string>>(content);
+			} catch {
+				// A single malformed agent file must not break discovery for every flow.
+				return { frontmatter: {} as Record<string, string>, body: "" };
+			}
+		})();
 		if (!frontmatter.name || !frontmatter.description) continue;
 
 		const tools = frontmatter.tools

package/extensions/index.ts

@@ -18,8 +18,8 @@ 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, desugar, isShorthand } from "./schema.ts";
+import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
+import { finalPhase, resolveArgs, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
 import {
 	getFlow,
 	listFlows,
@@ -86,17 +86,6 @@ const TaskflowParams = Type.Object({
 	),
 });
 
-function resolveArgs(def: Taskflow, provided: Record<string, unknown> | undefined): Record<string, unknown> {
-	const args: Record<string, unknown> = {};
-	for (const [key, spec] of Object.entries(def.args ?? {})) {
-		if (provided && key in provided) args[key] = provided[key];
-		else if (spec.default !== undefined) args[key] = spec.default;
-	}
-	// also pass through any extra provided args
-	if (provided) for (const [k, v] of Object.entries(provided)) if (!(k in args)) args[k] = v;
-	return args;
-}
-
 function makeRunState(def: Taskflow, args: Record<string, unknown>, cwd: string): RunState {
 	return {
 		runId: newRunId(def.name),
@@ -153,6 +142,29 @@ async function runFlow(
 		(heartbeat as { unref?: () => void }).unref?.();
 	}
 
+	// Human-in-the-loop approver — only when an interactive UI is available.
+	const requestApproval = ctx.hasUI
+		? async (req: ApprovalRequest): Promise<ApprovalDecision> => {
+				if (req.upstream?.trim()) {
+					const snip = req.upstream.replace(/\s+/g, " ").trim();
+					ctx.ui.notify(`[${def.name}/${req.phaseId}] ${snip.length > 280 ? `${snip.slice(0, 280)}…` : snip}`, "info");
+				}
+				const choice = await ctx.ui.select(
+					`Taskflow approval — ${req.phaseId}: ${req.message}`,
+					["Approve", "Reject", "Edit / add guidance"],
+					{ signal },
+				);
+				if (!choice || choice === "Reject") return { decision: "reject" };
+				if (choice.startsWith("Edit")) {
+					const note = await ctx.ui.input("Guidance passed downstream as this phase's output", "type guidance…", {
+						signal,
+					});
+					return { decision: "edit", note: note ?? "" };
+				}
+				return { decision: "approve" };
+			}
+		: undefined;
+
 	try {
 		const result = await executeTaskflow(state, {
 			cwd: ctx.cwd,
@@ -160,6 +172,8 @@ async function runFlow(
 			globalThinking: settings.globalThinking,
 			signal,
 			persist: persistThrottled,
+			requestApproval,
+			loadFlow: (name: string) => getFlow(ctx.cwd, name)?.def,
 		});
 		return result;
 	} finally {
@@ -199,11 +213,12 @@ export default function (pi: ExtensionAPI) {
 		label: "Taskflow",
 		description: [
 			"Orchestrate a multi-phase workflow of subagents from a declarative definition.",
-			"Phases (agent, parallel, map, gate, reduce) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
+			"Phases (agent, parallel, map, gate, reduce, approval, flow) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
 			"Use action=run with an inline `define` (you write the DSL) or a saved `name`.",
 			"For simple non-DAG delegations (like the subagent tool) skip the DSL: pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` to run in parallel, or `chain:[{task,agent?}]` to run sequentially (reference the prior step with {previous.output}).",
 			"Use action=save to persist a definition as a reusable /tf:<name> command. action=resume continues a paused run. action=list shows saved flows.",
-			"DSL: {name, args?, concurrency?, phases:[{id, type, agent, task, dependsOn?, over?(map), as?(map), branches?(parallel), from?(reduce), output?:'json', final?}]}.",
+			"DSL: {name, args?, concurrency?, budget?:{maxUSD,maxTokens}, phases:[{id, type, agent, task, dependsOn?, join?:'all'|'any', when?, retry?:{max,backoffMs,factor}, over?(map), as?(map), branches?(parallel), from?(reduce), use?(flow), with?(flow), output?:'json', final?}]}.",
+			"Phase types: agent (one subagent), parallel (static branches), map (dynamic fan-out over an array), gate (VERDICT: PASS/BLOCK quality gate), reduce (aggregate from N phases), approval (human-in-the-loop pause), flow (run a saved sub-flow). join:'any' is an OR-join; when is a conditional guard; retry adds backoff; budget caps run cost.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,

package/extensions/interpolate.ts

@@ -149,3 +149,234 @@ export function coerceArray(value: unknown): unknown[] | null {
 	}
 	return null;
 }
+
+// ---------------------------------------------------------------------------
+// Conditional expressions (phase.when)
+// ---------------------------------------------------------------------------
+//
+// A tiny, safe boolean expression language — NO eval / Function. Operands are
+// either interpolation placeholders `{...}` (resolved to their raw value) or
+// literals (quoted string, number, true/false/null, or a bare word treated as
+// a string). Operators, by precedence (low → high):
+//
+//   ||   logical or
+//   &&   logical and
+//   ==  != == >= <= > <   comparison
+//   !    logical not / unary
+//   ( )  grouping
+//
+// A bare operand is evaluated for truthiness. Parse errors fail OPEN (return
+// true) so a malformed guard never silently drops a phase.
+
+type Tok =
+	| { t: "ref"; v: string }
+	| { t: "str"; v: string }
+	| { t: "num"; v: number }
+	| { t: "bool"; v: boolean }
+	| { t: "null" }
+	| { t: "op"; v: string };
+
+const OPS = ["&&", "||", "==", "!=", ">=", "<=", ">", "<", "!", "(", ")"];
+
+function tokenize(input: string): Tok[] {
+	const toks: Tok[] = [];
+	let i = 0;
+	const n = input.length;
+	while (i < n) {
+		const c = input[i];
+		if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+			i++;
+			continue;
+		}
+		// placeholder {path.to.value}
+		if (c === "{") {
+			const end = input.indexOf("}", i);
+			if (end === -1) throw new Error("unterminated placeholder");
+			toks.push({ t: "ref", v: input.slice(i + 1, end).trim() });
+			i = end + 1;
+			continue;
+		}
+		// quoted string
+		if (c === '"' || c === "'") {
+			const end = input.indexOf(c, i + 1);
+			if (end === -1) throw new Error("unterminated string");
+			toks.push({ t: "str", v: input.slice(i + 1, end) });
+			i = end + 1;
+			continue;
+		}
+		// multi/single char operators
+		const op = OPS.find((o) => input.startsWith(o, i));
+		if (op) {
+			toks.push({ t: "op", v: op });
+			i += op.length;
+			continue;
+		}
+		// number
+		const numMatch = /^-?\d+(?:\.\d+)?/.exec(input.slice(i));
+		if (numMatch) {
+			toks.push({ t: "num", v: Number(numMatch[0]) });
+			i += numMatch[0].length;
+			continue;
+		}
+		// bareword → literal (true/false/null keywords, else string)
+		const word = /^[^\s&|!=<>()"'{}]+/.exec(input.slice(i));
+		if (word) {
+			const w = word[0];
+			if (w === "true") toks.push({ t: "bool", v: true });
+			else if (w === "false") toks.push({ t: "bool", v: false });
+			else if (w === "null") toks.push({ t: "null" });
+			else toks.push({ t: "str", v: w });
+			i += w.length;
+			continue;
+		}
+		throw new Error(`unexpected char '${c}'`);
+	}
+	return toks;
+}
+
+function isNumeric(v: unknown): boolean {
+	if (typeof v === "number") return Number.isFinite(v);
+	if (typeof v === "string" && v.trim() !== "") return Number.isFinite(Number(v));
+	return false;
+}
+
+function truthy(v: unknown): boolean {
+	if (v === undefined || v === null) return false;
+	if (typeof v === "boolean") return v;
+	if (typeof v === "number") return v !== 0;
+	if (typeof v === "string") {
+		const s = v.trim().toLowerCase();
+		return !(s === "" || s === "false" || s === "0" || s === "no" || s === "off" || s === "null");
+	}
+	if (Array.isArray(v)) return v.length > 0;
+	if (typeof v === "object") return Object.keys(v as object).length > 0;
+	return Boolean(v);
+}
+
+function compare(a: unknown, op: string, b: unknown): boolean {
+	if (isNumeric(a) && isNumeric(b)) {
+		const x = Number(a);
+		const y = Number(b);
+		switch (op) {
+			case "==": return x === y;
+			case "!=": return x !== y;
+			case ">": return x > y;
+			case "<": return x < y;
+			case ">=": return x >= y;
+			case "<=": return x <= y;
+		}
+	}
+	const sa = a === undefined || a === null ? "" : String(a);
+	const sb = b === undefined || b === null ? "" : String(b);
+	switch (op) {
+		case "==": return sa === sb;
+		case "!=": return sa !== sb;
+		case ">": return sa > sb;
+		case "<": return sa < sb;
+		case ">=": return sa >= sb;
+		case "<=": return sa <= sb;
+	}
+	return false;
+}
+
+/** Recursive-descent parser/evaluator over the token stream. */
+class CondParser {
+	private pos = 0;
+	private readonly toks: Tok[];
+	private readonly ctx: InterpolationContext;
+	constructor(toks: Tok[], ctx: InterpolationContext) {
+		this.toks = toks;
+		this.ctx = ctx;
+	}
+
+	parse(): unknown {
+		const v = this.parseOr();
+		if (this.pos < this.toks.length) throw new Error("trailing tokens");
+		return v;
+	}
+	private peek(): Tok | undefined {
+		return this.toks[this.pos];
+	}
+	private eat(op: string): boolean {
+		const t = this.peek();
+		if (t && t.t === "op" && t.v === op) {
+			this.pos++;
+			return true;
+		}
+		return false;
+	}
+	private parseOr(): unknown {
+		let left = this.parseAnd();
+		while (this.eat("||")) {
+			const right = this.parseAnd();
+			left = truthy(left) || truthy(right);
+		}
+		return left;
+	}
+	private parseAnd(): unknown {
+		let left = this.parseNot();
+		while (this.eat("&&")) {
+			const right = this.parseNot();
+			left = truthy(left) && truthy(right);
+		}
+		return left;
+	}
+	private parseNot(): unknown {
+		if (this.eat("!")) return !truthy(this.parseNot());
+		return this.parseComparison();
+	}
+	private parseComparison(): unknown {
+		const left = this.parsePrimary();
+		const t = this.peek();
+		if (t && t.t === "op" && ["==", "!=", ">", "<", ">=", "<="].includes(t.v)) {
+			this.pos++;
+			const right = this.parsePrimary();
+			return compare(left, t.v, right);
+		}
+		return left;
+	}
+	private parsePrimary(): unknown {
+		if (this.eat("(")) {
+			const v = this.parseOr();
+			if (!this.eat(")")) throw new Error("missing )");
+			return v;
+		}
+		const t = this.peek();
+		if (!t) throw new Error("unexpected end");
+		this.pos++;
+		switch (t.t) {
+			case "ref": return resolvePath(t.v, this.ctx);
+			case "str": return t.v;
+			case "num": return t.v;
+			case "bool": return t.v;
+			case "null": return null;
+			default: throw new Error(`unexpected operator '${(t as { v: string }).v}'`);
+		}
+	}
+}
+
+/**
+ * Evaluate a `when` expression to a boolean. Returns `{ value, error }`.
+ * Parse errors set `error` and fail OPEN (`value: true`) so a broken guard
+ * never silently drops a phase.
+ */
+export function tryEvaluateCondition(
+	expr: string,
+	ctx: InterpolationContext,
+): { value: boolean; error?: string } {
+	const trimmed = (expr ?? "").trim();
+	if (!trimmed) return { value: true };
+	try {
+		const toks = tokenize(trimmed);
+		if (toks.length === 0) return { value: true };
+		const result = new CondParser(toks, ctx).parse();
+		return { value: truthy(result) };
+	} catch (e) {
+		return { value: true, error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+/** Boolean convenience wrapper over {@link tryEvaluateCondition}. */
+export function evaluateCondition(expr: string, ctx: InterpolationContext): boolean {
+	return tryEvaluateCondition(expr, ctx).value;
+}

package/extensions/render.ts

@@ -7,7 +7,7 @@
 
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import { formatTokens, type UsageStats } from "./runner.ts";
+import { formatTokens, type UsageStats } from "./usage.ts";
 import type { PhaseState, RunState } from "./store.ts";
 import { dependenciesOf, type Phase, topoLayers } from "./schema.ts";
 
@@ -121,7 +121,7 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 		return theme.fg("muted", `skipped · ${snip}`);
 	}
 
-	const isFanout = type === "map" || type === "parallel";
+	const isFanout = type === "map" || type === "parallel" || type === "flow";
 
 	if (ps.status === "failed") {
 		const e = (ps.error ?? "failed").replace(/\s+/g, " ");
@@ -171,6 +171,14 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	// single-agent done
 	const model = shortModel(ps.model);
 	const u = compactUsage(ps.usage, theme);
+	if (ps.approval) {
+		const d = ps.approval.decision;
+		const color = d === "reject" ? "error" : d === "edit" ? "warning" : "success";
+		let a = theme.fg(color as Parameters<typeof theme.fg>[0], theme.bold(d.toUpperCase()));
+		if (ps.approval.auto) a += theme.fg("dim", " auto");
+		if (time) a += `  ${time}`;
+		return a;
+	}
 	if (ps.gate) {
 		const badge =
 			ps.gate.verdict === "block" ? theme.fg("error", theme.bold("BLOCK")) : theme.fg("success", "PASS");
@@ -186,6 +194,7 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	let s = "";
 	if (model) s += theme.fg("accent", model);
 	if (u) s += (s ? "  " : "") + u;
+	if (ps.attempts && ps.attempts > 1) s += theme.fg("warning", `  ↻${ps.attempts - 1}`);
 	if (time) s += `  ${time}`;
 	return s || theme.fg("dim", "done");
 }
@@ -217,7 +226,9 @@ function headerLine(state: RunState, theme: Theme): string {
 	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 budget = state.def.budget;
+	if (budget?.maxUSD !== undefined) line += theme.fg("muted", ` · $${cost.toFixed(3)}/$${budget.maxUSD}`);
+	else if (cost) line += theme.fg("muted", ` · $${cost.toFixed(3)}`);
 	const el = runElapsed(state);
 	if (el) line += theme.fg("dim", ` · ${elapsed(el)}`);
 	return line;