pi-taskflow 0.0.5 → 0.0.7

package/extensions/schema.ts

@@ -5,6 +5,7 @@
  * to a subagent (an isolated `pi` process). Phases form a DAG via `dependsOn`.
  */
 
+import * as path from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 
@@ -12,10 +13,11 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce"] as const;
+export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow"] as const;
 export type PhaseType = (typeof PHASE_TYPES)[number];
 
 export const OUTPUT_FORMATS = ["text", "json"] as const;
+export const JOIN_MODES = ["all", "any"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -25,6 +27,29 @@ const ParallelTaskSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/** Declarative retry policy for a phase's subagent call(s). */
+const RetrySchema = Type.Object(
+	{
+		max: Type.Number({ description: "Max retry attempts after the first try (>= 0)" }),
+		backoffMs: Type.Optional(Type.Number({ description: "Base delay between attempts, in ms", default: 0 })),
+		factor: Type.Optional(
+			Type.Number({ description: "Backoff multiplier per attempt (1 = fixed, 2 = exponential)", default: 1 }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+/** Run-wide cost / token ceiling. Exceeding it halts the run (remaining phases skipped). */
+const BudgetSchema = Type.Object(
+	{
+		maxUSD: Type.Optional(Type.Number({ description: "Halt the run once accumulated cost exceeds this many USD" })),
+		maxTokens: Type.Optional(
+			Type.Number({ description: "Halt the run once accumulated input+output tokens exceed this" }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 const PhaseSchema = Type.Object(
 	{
 		id: Type.String({ description: "Unique phase identifier (referenced via {steps.<id>.output})" }),
@@ -46,7 +71,28 @@ const PhaseSchema = Type.Object(
 			Type.Array(Type.String(), { description: "[reduce] Phase ids whose outputs are aggregated" }),
 		),
 
+		// sub-workflow (flow)
+		use: Type.Optional(Type.String({ description: "[flow] Name of a saved taskflow to run as this phase" })),
+		with: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description: "[flow] Args passed to the sub-flow (string values support interpolation)",
+			}),
+		),
+
 		dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Phase ids this phase depends on" })),
+		join: Type.Optional(
+			StringEnum(JOIN_MODES, {
+				description: "Dependency join: 'all' (default) waits for every dep; 'any' runs as soon as one dep completes",
+				default: "all",
+			}),
+		),
+		when: Type.Optional(
+			Type.String({
+				description:
+					"Conditional guard: skip this phase unless the expression is truthy. Supports {refs} and == != < > <= >= && || ! ()",
+			}),
+		),
+		retry: Type.Optional(RetrySchema),
 		output: Type.Optional(StringEnum(OUTPUT_FORMATS, { description: "Parse output as text or json", default: "text" })),
 		model: Type.Optional(Type.String({ description: "Model override for this phase" })),
 		thinking: Type.Optional(Type.String({ description: "Thinking level override for this phase" })),
@@ -57,6 +103,18 @@ const PhaseSchema = Type.Object(
 			Type.Boolean({ description: "If true, a failure does not abort the run", default: false }),
 		),
 		concurrency: Type.Optional(Type.Number({ description: "Override max concurrency for map/parallel" })),
+		context: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"File paths or {steps.X} refs to pre-read and inject before the task. Resolves interpolated refs first, then reads each file (capped per-file). Eliminates O(N²) turn-cost exploration.",
+			}),
+		),
+		contextLimit: Type.Optional(
+			Type.Number({
+				description: "Max characters to read per file referenced in context (default 8000).",
+				default: 8000,
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -77,9 +135,17 @@ export const TaskflowSchema = Type.Object(
 		version: Type.Optional(Type.Number({ default: 1 })),
 		args: Type.Optional(Type.Record(Type.String(), ArgSpecSchema, { description: "Declared invocation arguments" })),
 		concurrency: Type.Optional(Type.Number({ description: "Default max concurrent subagents", default: 8 })),
+		budget: Type.Optional(BudgetSchema),
 		agentScope: Type.Optional(
 			StringEnum(["user", "project", "both"] as const, { description: "Agent discovery scope", default: "user" }),
 		),
+		strictInterpolation: Type.Optional(
+			Type.Boolean({
+				description:
+					"When true, unresolved interpolation placeholders and validation warnings about missing deps/args become hard errors",
+				default: false,
+			}),
+		),
 		phases: Type.Array(PhaseSchema, { minItems: 1, description: "Ordered phase definitions (DAG via dependsOn)" }),
 	},
 	{ additionalProperties: false },
@@ -89,6 +155,9 @@ export type ParallelTask = Static<typeof ParallelTaskSchema>;
 export type Phase = Static<typeof PhaseSchema>;
 export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
+export type RetryPolicy = Static<typeof RetrySchema>;
+export type Budget = Static<typeof BudgetSchema>;
+export type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
 // Shorthand (non-DAG) specs — subagent-style ergonomics
@@ -141,6 +210,8 @@ export function desugar(def: unknown): Taskflow {
 	if (typeof d.concurrency === "number") meta.concurrency = d.concurrency;
 	if (d.agentScope === "user" || d.agentScope === "project" || d.agentScope === "both") meta.agentScope = d.agentScope;
 	if (d.args && typeof d.args === "object") meta.args = d.args as Taskflow["args"];
+	if (d.budget) meta.budget = d.budget;
+	if (typeof d.strictInterpolation === "boolean") meta.strictInterpolation = d.strictInterpolation;
 	const nameOf = (fallback: string) => (typeof d.name === "string" && d.name.trim() ? d.name.trim() : fallback);
 
 	// chain → sequential agent phases
@@ -179,20 +250,35 @@ export function desugar(def: unknown): Taskflow {
 export interface ValidationResult {
 	ok: boolean;
 	errors: string[];
+	/** Non-fatal issues the user should fix; e.g. `{steps.X}` references that
+	 *  aren't declared in `dependsOn` (the phase will run in parallel with its
+	 *  producer and see the literal placeholder). */
+	warnings: string[];
 }
 
-export function validateTaskflow(def: unknown): ValidationResult {
+export interface ValidationOptions {
+	/** Resolved invocation args, used for runtime checks like missing `{args.X}`. */
+	args?: Record<string, unknown>;
+	/** Runtime working directory, used for mismatch warnings (e.g. cwd vs args.codebase). */
+	cwd?: string;
+	/** Override the flow's own `strictInterpolation` flag for this validation call. */
+	strict?: boolean;
+}
+
+export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): ValidationResult {
 	const errors: string[] = [];
+	const warnings: string[] = [];
 
 	if (typeof def !== "object" || def === null) {
-		return { ok: false, errors: ["Taskflow must be an object"] };
+		return { ok: false, errors: ["Taskflow must be an object"], warnings };
 	}
 	const flow = def as Partial<Taskflow>;
+	const strict = opts.strict ?? flow.strictInterpolation === true;
 
 	if (!flow.name || typeof flow.name !== "string") errors.push("Missing or invalid 'name'");
 	if (!Array.isArray(flow.phases) || flow.phases.length === 0) {
 		errors.push("Taskflow must have at least one phase");
-		return { ok: false, errors };
+		return { ok: false, errors, warnings };
 	}
 
 	const ids = new Set<string>();
@@ -227,6 +313,25 @@ export function validateTaskflow(def: unknown): ValidationResult {
 			if (!p.from || p.from.length === 0) errors.push(`Phase '${p.id}' (reduce) requires 'from'`);
 			if (!p.task) errors.push(`Phase '${p.id}' (reduce) requires 'task'`);
 		}
+		if (type === "flow") {
+			if (!p.use) errors.push(`Phase '${p.id}' (flow) requires 'use' (a saved flow name)`);
+		}
+		if (p.retry) {
+			if (typeof p.retry.max !== "number" || p.retry.max < 0) {
+				errors.push(`Phase '${p.id}': retry.max must be a number >= 0`);
+			} else if (p.retry.max > 20) {
+				errors.push(`Phase '${p.id}': retry.max must be <= 20`);
+			}
+			if (p.retry.backoffMs !== undefined && (p.retry.backoffMs < 0 || p.retry.backoffMs > 60000)) {
+				errors.push(`Phase '${p.id}': retry.backoffMs must be between 0 and 60000`);
+			}
+			if (p.retry.factor !== undefined && (p.retry.factor < 1 || p.retry.factor > 10)) {
+				errors.push(`Phase '${p.id}': retry.factor must be between 1 and 10`);
+			}
+		}
+		if (p.join && !JOIN_MODES.includes(p.join as JoinMode)) {
+			errors.push(`Phase '${p.id}': unknown join mode '${p.join}'`);
+		}
 	}
 
 	// dependsOn / from references must exist
@@ -247,10 +352,102 @@ export function validateTaskflow(def: unknown): ValidationResult {
 	}
 
 	// Exactly handle final-phase resolution lazily (0 finals => last phase is final)
-	const finals = (flow.phases as Phase[]).filter((p) => p.final);
+	const finals = (flow.phases as Phase[]).filter((p) => p?.final);
 	if (finals.length > 1) errors.push(`Only one phase may be marked 'final' (found ${finals.length})`);
 
-	return { ok: errors.length === 0, errors };
+	// --- Soft warnings: {steps.X.*} references that aren't declared deps -------
+	// Catches the most common authoring mistake: the task talks about
+	// `{steps.review.output}` but `dependsOn: ["review"]` is missing, so the
+	// phase runs in parallel with `review` and the model sees the literal
+	// placeholder string. The runtime can't infer the intent.
+	if (errors.length === 0) {
+		const idToPhase = new Map((flow.phases as Phase[]).map((p) => [p.id, p]));
+		for (const p of flow.phases as Phase[]) {
+			if (!p?.id) continue;
+			const deps = new Set(dependenciesOf(p));
+			const refs = collectRefs(p);
+			for (const ref of refs.steps) {
+				if (ref === p.id) {
+					warnings.push(`Phase '${p.id}': references its own output via {steps.${ref}.*}; this is almost always a bug.`);
+					continue;
+				}
+				if (!idToPhase.has(ref)) {
+					// Unknown ref is already an error from the dependsOn check, but
+					// {steps.X.*} can appear in a task without dependsOn. Don't
+					// double-warn — the dependsOn loop above already flags it.
+					continue;
+				}
+				if (!deps.has(ref)) {
+					warnings.push(
+						`Phase '${p.id}': task references {steps.${ref}.*} but '${ref}' is not in dependsOn. ` +
+							`The phase will run in parallel with '${ref}' and see the literal placeholder. ` +
+							`Add "dependsOn": ["${ref}"] (or include '${ref}' transitively).`,
+					);
+				}
+			}
+		}
+	}
+
+	// --- Runtime/invocation warnings: missing args + cwd/codebase mismatch -----
+	if (errors.length === 0 && opts.args) {
+		const argRefs = new Set<string>();
+		for (const p of flow.phases as Phase[]) {
+			if (!p?.id) continue;
+			for (const ref of collectRefs(p).args) argRefs.add(ref);
+		}
+		for (const ref of argRefs) {
+			if (!(ref in opts.args)) {
+				warnings.push(
+					`Taskflow references {args.${ref}} but the invocation did not provide '${ref}'. ` +
+						`The placeholder will remain literal unless a default or runtime arg is supplied.`,
+				);
+			}
+		}
+		if (opts.cwd && typeof opts.args.codebase === "string" && opts.args.codebase.trim()) {
+			const cwd = path.resolve(opts.cwd);
+			const codebase = path.resolve(cwd, opts.args.codebase);
+			// Safe case: cwd is the codebase root or a subdirectory within it.
+			// Warn when cwd is a sibling, unrelated path, or a parent of the
+			// codebase (agents that rely on cwd would inspect too broad a tree).
+			if (!pathContains(codebase, cwd)) {
+				warnings.push(
+					`Invocation cwd '${cwd}' does not match args.codebase '${codebase}'. ` +
+						`Some agents may inspect the wrong repo if they rely on cwd. Prefer running from the codebase root or set phase.cwd explicitly.`,
+				);
+			}
+		}
+	}
+
+	if (strict && warnings.length) {
+		errors.push(...warnings.map((w) => `Strict interpolation: ${w}`));
+	}
+
+	return { ok: errors.length === 0, errors, warnings };
+}
+
+function collectRefs(phase: Phase): { steps: string[]; args: string[] } {
+	const steps = new Set<string>();
+	const args = new Set<string>();
+	const scan = (s: string | undefined) => {
+		if (!s) return;
+		let m: RegExpExecArray | null;
+		const stepRe = /\{steps\.([a-zA-Z0-9_-]+)/g;
+		while ((m = stepRe.exec(s)) !== null) steps.add(m[1]);
+		const argRe = /\{args\.([a-zA-Z0-9_-]+)/g;
+		while ((m = argRe.exec(s)) !== null) args.add(m[1]);
+	};
+	scan(phase.task);
+	scan(phase.over);
+	scan(phase.when);
+	for (const b of phase.branches ?? []) scan(b.task);
+	for (const v of Object.values(phase.with ?? {})) if (typeof v === "string") scan(v);
+	for (const c of phase.context ?? []) scan(c);
+	return { steps: Array.from(steps), args: Array.from(args) };
+}
+
+function pathContains(parent: string, child: string): boolean {
+	const rel = path.relative(parent, child);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 
 /** Returns a cycle path if the DAG has one, else null. */
@@ -341,3 +538,18 @@ export function topoLayers(phases: Phase[]): Phase[][] {
 export function finalPhase(phases: Phase[]): Phase {
 	return phases.find((p) => p.final) ?? phases[phases.length - 1];
 }
+
+/**
+ * Apply a flow's declared arg defaults over the provided values, then pass
+ * through any extra provided keys. Shared by the tool entrypoint (index) and the
+ * sub-flow (`flow`) phase (runtime).
+ */
+export function resolveArgs(def: Taskflow, provided?: Record<string, unknown>): 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;
+	}
+	if (provided) for (const [k, v] of Object.entries(provided)) if (!(k in args)) args[k] = v;
+	return args;
+}

package/extensions/store.ts

@@ -11,7 +11,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { Taskflow } from "./schema.ts";
-import type { UsageStats } from "./runner.ts";
+import type { UsageStats } from "./usage.ts";
 
 export interface SavedFlow {
 	name: string;
@@ -39,6 +39,18 @@ export interface PhaseState {
 	liveText?: string;
 	/** Gate verdict (gate phases only). */
 	gate?: { verdict: "pass" | "block"; reason?: string };
+	/** Total subagent attempts incl. retries (when > calls, a retry happened). */
+	attempts?: number;
+	/** True when a map/parallel fan-out was cut short by the budget cap. */
+	budgetTruncated?: boolean;
+	/** Human-in-the-loop outcome (approval phases only). */
+	approval?: { decision: "approve" | "reject" | "edit"; note?: string; auto?: boolean };
+	/** Non-fatal diagnostic warnings accumulated during this phase (e.g.
+	 *  unresolved interpolation placeholders, suspicious templates). */
+	warnings?: string[];
+	/** Truncated previews of interpolated strings used to execute this phase,
+	 *  useful when diagnosing why a model saw a literal placeholder. */
+	interpolation?: Array<{ source: string; text: string; missing?: string[] }>;
 }
 
 export interface RunState {
@@ -118,7 +130,7 @@ export function saveFlow(
 	fs.mkdirSync(dir, { recursive: true });
 	const safe = def.name.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(dir, `${safe}.json`);
-	fs.writeFileSync(filePath, `${JSON.stringify(def, null, 2)}\n`, "utf-8");
+	writeFileAtomic(filePath, `${JSON.stringify(def, null, 2)}\n`);
 	return { filePath };
 }
 
@@ -138,12 +150,52 @@ export function saveRun(state: RunState): void {
 	const dir = runsDir(state.cwd);
 	fs.mkdirSync(dir, { recursive: true });
 	state.updatedAt = Date.now();
-	fs.writeFileSync(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2), "utf-8");
+	writeFileAtomic(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2));
 }
 
 export function loadRun(cwd: string, runId: string): RunState | null {
+	const dir = runsDir(cwd);
+
+	// Reject runIds that could be used for path traversal or filesystem abuse.
+	// Legitimate runIds are produced by newRunId() and contain only
+	// [A-Za-z0-9._-]; anything else (empty string, path separators, NUL bytes,
+	// backslashes on POSIX, forward slashes on Windows) is suspicious.
+	if (
+		typeof runId !== "string" ||
+		runId.length === 0 ||
+		runId.includes("/") ||
+		runId.includes("\\") ||
+		runId.includes("\0")
+	) {
+		return null;
+	}
+
+	const filePath = path.resolve(dir, `${runId}.json`);
+	// Reject runIds that would escape the runs directory (e.g. "../etc/passwd").
+	// Compare with a path-separator suffix so legitimate filenames like "..foo"
+	// (a name that just happens to start with two dots) are not false-positives.
+	const rel = path.relative(dir, filePath);
+	if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+
+	// Resolve symlinks on both the runs dir and the file, so the containment
+	// check below is on a consistent physical path. Without normalizing `dir`,
+	// a legitimate run on macOS (where /var → /private/var) would compare a
+	// symlinked dir prefix to a real path and falsely flag traversal. A
+	// malicious file already placed inside the runs dir could otherwise also
+	// point at an arbitrary path on disk and bypass the lexical check above.
+	let realDir: string;
+	let realFilePath: string;
+	try {
+		realDir = fs.realpathSync(dir);
+		realFilePath = fs.realpathSync(filePath);
+	} catch {
+		return null;
+	}
+	const realRel = path.relative(realDir, realFilePath);
+	if (realRel === ".." || realRel.startsWith(`..${path.sep}`) || path.isAbsolute(realRel)) return null;
+
 	try {
-		const raw = fs.readFileSync(path.join(runsDir(cwd), `${runId}.json`), "utf-8");
+		const raw = fs.readFileSync(realFilePath, "utf-8");
 		return JSON.parse(raw) as RunState;
 	} catch {
 		return null;
@@ -174,3 +226,23 @@ export function listRuns(cwd: string, limit = 20): RunState[] {
 export function hashInput(...parts: string[]): string {
 	return crypto.createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
 }
+
+/**
+ * Write a file atomically: write to a unique temp file in the same directory,
+ * then rename over the target (rename is atomic on the same filesystem). Prevents
+ * a crash or concurrent write from leaving a half-written, corrupt JSON file.
+ */
+function writeFileAtomic(filePath: string, data: string): void {
+	const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+	try {
+		fs.writeFileSync(tmp, data, "utf-8");
+		fs.renameSync(tmp, filePath);
+	} catch (e) {
+		try {
+			if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+		} catch {
+			/* ignore cleanup failure */
+		}
+		throw e;
+	}
+}

package/extensions/usage.ts

@@ -0,0 +1,42 @@
+/**
+ * Usage accounting — token/cost stats shared across the runner (producer),
+ * runtime (aggregation), store (persistence), and render (display).
+ *
+ * Kept in its own leaf module so persistence and TUI don't have to depend on
+ * the process-spawning layer (`runner.ts`) just for these types/helpers.
+ */
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+/** Sum numeric usage fields across runs. `contextTokens` is intentionally excluded (it is a point-in-time gauge, not additive). */
+export function aggregateUsage(usages: UsageStats[]): UsageStats {
+	const total = emptyUsage();
+	for (const u of usages) {
+		total.input += u.input;
+		total.output += u.output;
+		total.cacheRead += u.cacheRead;
+		total.cacheWrite += u.cacheWrite;
+		total.cost += u.cost;
+		total.turns += u.turns;
+	}
+	return total;
+}
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}

package/package.json

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

package/skills/taskflow/SKILL.md

@@ -86,6 +86,71 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 | `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
 | `gate` | quality/review step that can **halt the flow** (see below) |
 | `reduce` | aggregate `from[]` phases into one output |
+| `approval` | **human-in-the-loop** pause: ask a person to approve / reject / edit before continuing |
+| `flow` | run a **saved sub-flow** (by `use`) as a single phase — composition/reuse |
+
+### Control-flow fields (any phase)
+
+| field | meaning |
+|-------|---------|
+| `when` | conditional guard — skip the phase unless the expression is truthy. Supports `{refs}`, `== != < > <= >=`, `&& \|\| !`, parentheses, quoted strings/numbers. Parse errors fail **open** (phase runs). |
+| `join` | dependency join: `"all"` (default — wait for every dep) or `"any"` (OR-join — run as soon as one dep completes). |
+| `retry` | `{ "max": N, "backoffMs": ms, "factor": k }` — retry a failing subagent up to N times; delay is `backoffMs * factor^attempt` (`factor:1`=fixed, `2`=exponential). |
+
+### Conditional routing (when + gate/branches)
+
+Pair `when` with an upstream phase that emits a decision to build real if/else
+routing. Use `join: "any"` on the merge phase so it runs whichever branch fired:
+
+```jsonc
+{ "id": "triage", "type": "agent", "agent": "analyst", "output": "json",
+  "task": "Classify the task. Output ONLY {\"route\":\"deep\"} or {\"route\":\"quick\"}." },
+{ "id": "deep",  "when": "{steps.triage.json.route} == deep",  "dependsOn": ["triage"], "agent": "analyst", "task": "..." },
+{ "id": "quick", "when": "{steps.triage.json.route} == quick", "dependsOn": ["triage"], "agent": "executor_fast", "task": "..." },
+{ "id": "report", "type": "reduce", "from": ["deep","quick"], "join": "any",
+  "dependsOn": ["deep","quick"], "agent": "writer", "task": "...", "final": true }
+```
+
+> `when` should reference **upstream** (`dependsOn`) phases — a ref to a phase
+> that hasn't completed resolves empty and the guard is treated as false.
+
+### Approval phases (human-in-the-loop)
+
+An `approval` phase pauses the run and asks the operator to **Approve / Reject /
+Edit**. Distinct from `gate` (which is an *agent* reviewing): this is a *human*
+deciding. The (interpolated) `task` is the prompt shown.
+
+- **Approve** → continue; the phase output is `(approve)`.
+- **Reject** → halt the flow (same mechanism as a blocking gate).
+- **Edit** → the typed note becomes this phase's `output`, so you can inject
+  guidance mid-run: reference it downstream with `{steps.<id>.output}`.
+- **Non-interactive** runs (headless/CI/print mode) **auto-approve** and record it.
+
+```jsonc
+{ "id": "checkpoint", "type": "approval", "dependsOn": ["plan"],
+  "task": "Review the plan above before the expensive fan-out. Approve, reject, or add guidance." }
+```
+
+### Sub-flows (composition)
+
+A `flow` phase runs another **saved** taskflow by name and bubbles up its final
+output. Pass args via `with` (string values interpolate). Recursion is detected
+and rejected.
+
+```jsonc
+{ "id": "research", "type": "flow", "use": "deep-research",
+  "with": { "topic": "{item}" }, "dependsOn": ["plan"] }
+```
+
+### Budget (cost / token caps)
+
+Add a run-wide ceiling at the top level. When accumulated cost/tokens exceed it,
+remaining phases are skipped (and an in-flight `map`/`parallel` stops spawning
+new items); the run ends as `blocked`.
+
+```jsonc
+{ "name": "...", "budget": { "maxUSD": 1.50, "maxTokens": 2000000 }, "phases": [ ... ] }
+```
 
 ### Gate phases (quality control)
 
@@ -123,6 +188,85 @@ Review the audit results below. If any endpoint is missing auth, end with
 3. Reference upstream results explicitly with `{steps.ID...}` and set `dependsOn`.
 4. Mark the result-bearing phase with `"final": true` (else the last phase wins).
 
+## Common mistakes (the runtime will warn you, but don't trip them)
+
+The runtime validates your flow at startup and at each phase's interpolation.
+Two patterns account for ~all the broken runs in the wild — avoid them. If you
+want warnings like these to become hard failures, set `"strictInterpolation": true`
+on the flow.
+
+### 1. Referencing `{steps.X}` without `dependsOn: ["X"]`
+
+```jsonc
+// ❌ WRONG — 'fix-issues' will run in parallel with 'code-review-1' and see the
+// literal string "{steps.code-review-1.output}" instead of the review text.
+{
+  "id": "code-review-1", "type": "agent", "task": "review code"
+},
+{
+  "id": "fix-issues", "type": "agent",
+  "task": "fix {steps.code-review-1.output}"   // ← no dependsOn!
+}
+```
+
+The runtime logs a warning at run start (`Phase 'fix-issues': task references
+{steps.code-review-1.*} but 'code-review-1' is not in dependsOn`) and the phase
+itself gets a `warnings` field with a non-fatal `unresolved placeholders` line.
+The TUI shows a `⚠N` badge. **Always declare the chain:**
+
+```jsonc
+// ✅ RIGHT
+{
+  "id": "code-review-1", "type": "agent", "task": "review code"
+},
+{
+  "id": "fix-issues", "type": "agent",
+  "task": "fix {steps.code-review-1.output}",
+  "dependsOn": ["code-review-1"]                // ← declared
+},
+{
+  "id": "code-review-2", "type": "agent",
+  "task": "re-review {steps.fix-issues.output}",
+  "dependsOn": ["fix-issues"]
+}
+```
+
+Tip: write the `task` first (it tells you what each phase needs), then scan for
+`{steps.*}` references and add the matching `dependsOn`. If a phase truly does
+not depend on anything in its task, you can ignore the warning.
+
+### 2. Assuming the runtime knows "this is a chain"
+
+Phase order in the `phases` array is **documentation, not execution order**.
+The DAG comes from `dependsOn`. If you list `code-review-1`, `fix-issues`,
+`code-review-2`, `fix-final` in that order with no `dependsOn`, the runtime
+treats them as four independent phases and runs all of them in **layer 0** in
+parallel. A phase that finishes first may not be the one you expected.
+
+```jsonc
+// ❌ This is not a chain — it's 4 parallel phases, all racing.
+"phases": [
+  { "id": "code-review-1", ... },
+  { "id": "fix-issues",    ... },
+  { "id": "code-review-2", ... },
+  { "id": "fix-final",     ... }
+]
+```
+
+Use the shorthand if you literally just want `a → b → c → d`:
+
+```jsonc
+{ "chain": [
+  { "agent": "reviewer", "task": "review code" },
+  { "agent": "executor", "task": "fix {previous.output}" },
+  { "agent": "reviewer", "task": "re-review" },
+  { "agent": "executor", "task": "apply final fixes" }
+] }
+```
+
+…or write the full DAG with explicit `dependsOn` (so reviewers/fixers can run
+in parallel against multiple review streams when you want that).
+
 ## Configuration
 
 For the full set of knobs — per-phase `model`/`thinking`/`tools`/`cwd`, the
@@ -132,8 +276,8 @@ variables, and storage paths — read `configuration.md` (next to this file).
 
 Quick reference:
 
-- **Flow:** `name`, `description`, `concurrency` (default 8), `agentScope` (user|project|both), `args`.
-- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `final`.
+- **Flow:** `name`, `description`, `concurrency` (default 8), `budget` (`maxUSD`/`maxTokens`), `agentScope` (user|project|both), `args`, `strictInterpolation`.
+- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `when`, `join` (all|any), `retry`, `use`/`with` (flow), `final`.
 - **Precedence (model/thinking/tools):** phase value → `settings.subagents.agentOverrides[agent]` → agent frontmatter → global/default.
 - **Concurrency:** same-layer phases use `flow.concurrency`; a `map`/`parallel` phase uses `phase.concurrency ?? flow.concurrency ?? 8`.
 

package/skills/taskflow/configuration.md

@@ -86,7 +86,6 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
 | `cwd` | all | flow cwd | Run this phase's subagent in a different directory. |
 | `concurrency` | map, parallel | flow concurrency | Fan-out cap for this phase only. See §4. |
 | `final` | all | last phase | Exactly one phase may be `final`; its output is returned. |
-| `optional` | all | `false` | ⚠️ Declared in schema but **not yet enforced** — a failed phase still skips downstream. |
 
 ---
 
@@ -270,6 +269,5 @@ Taskflow shares the subagent settings file at `~/.pi/agent/settings.json`:
 These keys validate but the runtime does **not** act on them yet — don't rely on
 them for behavior:
 
-- `phase.optional` — a failed phase still marks downstream phases as skipped.
 - `arg.required` — missing required args are not rejected.
 - `flow.version` — informational only.