pi-taskflow 0.0.6 → 0.0.7

package/README.md

@@ -22,9 +22,10 @@ saveable as a one-word `/tf:<name>` command.
 pi install npm:pi-taskflow
 ```
 
-Fan out one subagent per item, gate the results with an adversarial review, and
-get back only the final report — none of the intermediate transcripts ever touch
-your conversation.
+Fan out one subagent per item, route on results, retry the flaky ones, pause for
+human approval, cap the spend, and gate the output with an adversarial review —
+all from one declarative definition. Only the final report reaches your
+conversation; every intermediate transcript stays in the runtime.
 
 ## Why
 
@@ -45,6 +46,11 @@ only the final phase's output.
 | Scale | a few tasks | dynamic `map` fan-out |
 | Resumable | no | yes (cross-session, cached phases skip) |
 | Quality gates | no | `gate` phases with `VERDICT: BLOCK / PASS` |
+| Conditional routing | no | `when` guards + `join: any` OR-joins |
+| Fault tolerance | no | per-phase `retry` with backoff |
+| Human-in-the-loop | no | `approval` phases (approve / reject / edit) |
+| Cost control | no | run-wide `budget` (USD / token caps) |
+| Composition | no | `flow` phases run saved sub-flows |
 | Progress visibility | opaque while running | live DAG render with timing + cost |
 | Ergonomics | inline JSON each time | shorthand (`task`/`tasks`/`chain`) or DSL |
 
@@ -137,6 +143,36 @@ only the final report back.
 
 Save it once → `/tf:summarize-files` forever.
 
+### Route, gate, and guard
+
+Phases also **branch, retry, pause for a human, and respect a budget** — still
+declaratively, no scripting:
+
+```jsonc
+{
+  "name": "triage-and-fix",
+  "budget": { "maxUSD": 1.5 },
+  "phases": [
+    { "id": "triage", "type": "agent", "agent": "analyst", "output": "json",
+      "task": "Classify the bug. Output ONLY {\"severity\":\"high\"} or {\"severity\":\"low\"}." },
+    { "id": "deep",  "when": "{steps.triage.json.severity} == high", "dependsOn": ["triage"],
+      "agent": "executor_code", "task": "Root-cause and patch it.",
+      "retry": { "max": 2, "backoffMs": 500 } },
+    { "id": "quick", "when": "{steps.triage.json.severity} == low",  "dependsOn": ["triage"],
+      "agent": "executor_fast", "task": "Apply the quick fix." },
+    { "id": "approve", "type": "approval", "join": "any", "dependsOn": ["deep", "quick"],
+      "task": "Review the fix before it ships." },
+    { "id": "ship", "type": "agent", "dependsOn": ["approve"],
+      "task": "Open a PR with the change.", "final": true }
+  ]
+}
+```
+
+- **`when`** routes to `deep` *or* `quick` from the triage JSON; the other branch is skipped.
+- **`join: "any"`** lets `approve` run as soon as whichever branch fired completes.
+- **`retry`** re-runs a flaky patch with backoff; **`budget`** halts the whole run if it gets too expensive.
+- **`approval`** pauses for a human (approve / reject / edit) before the final `ship`.
+
 ## Watch it run
 
 This is the live progress render for a real run — the `self-improve` flow that
@@ -181,11 +217,28 @@ writes and verifies its own test suites, caught here mid-block by a quality gate
 | `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`,
-`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.
+### Common phase fields
+
+Every phase needs a unique `id` and a `type` (defaults to `agent`). On top of the
+per-type fields above:
+
+| Field | Meaning |
+|---|---|
+| `agent` | Agent to run (defaults to the first discovered agent) |
+| `dependsOn` | Phase ids this phase waits for — builds the DAG |
+| `join` | `"all"` (default) waits for every dep; `"any"` is an OR-join |
+| `when` | Conditional guard — skip unless the expression is truthy |
+| `retry` | `{ max, backoffMs?, factor? }` — retry a failing subagent |
+| `output` | `"text"` (default) or `"json"` (exposes `{steps.ID.json}`) |
+| `model` / `thinking` / `tools` | Per-phase overrides for the subagent |
+| `cwd` | Working directory for the subagent |
+| `concurrency` | Fan-out cap for `map` / `parallel` (overrides the flow default) |
+| `final` | Marks the result-bearing phase (else the last phase wins) |
+| `optional` | A failure here does **not** abort the run |
+| `use` / `with` | (`flow`) saved sub-flow name + its args |
+
+Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8),
+`agentScope`, and `budget: { maxUSD?, maxTokens? }`.
 
 ### Control flow & reliability
 
@@ -294,6 +347,20 @@ file). Phase-level overrides for `model`, `thinking`, and `tools` are passed as
 Settings from `~/.pi/agent/settings.json` (the `subagents.agentOverrides` map)
 are honored, letting you tweak model, thinking, or tools per agent across all flows.
 
+## Examples
+
+Ready-to-read definitions live in [`examples/`](./examples):
+
+| File | Demonstrates |
+|---|---|
+| [`summarize-files.json`](./examples/summarize-files.json) | discover → `map` fan-out → `reduce` |
+| [`conditional-research.json`](./examples/conditional-research.json) | `when` routing + `join: any` + `gate` + `budget` |
+| [`guarded-refactor.json`](./examples/guarded-refactor.json) | `approval` (human-in-the-loop) + `retry` + `gate` |
+
+To use one, copy it into `.pi/taskflows/<name>.json` (or
+`~/.pi/agent/taskflows/`) and it registers as `/tf:<name>` — or just point the
+model at the definition.
+
 ## Status & limits
 
 - **v0.0.6** — control flow & reliability: conditional `when` guards, `join: any`
@@ -327,13 +394,10 @@ are honored, letting you tweak model, thinking, or tools per agent across all fl
 ```bash
 npm install
 npm run typecheck
-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
+npm test            # unit tests — no network, no process spawning
 
 # real end-to-end (spawns live subagents; needs model access)
-PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts
+npm run test:e2e
 ```
 
 ## Contributing

package/extensions/index.ts

@@ -301,19 +301,28 @@ export default function (pi: ExtensionAPI) {
 							);
 					},
 				});
+				const warningText = v.warnings.length ? `\n\nWarnings:\n- ${v.warnings.join("\n- ")}` : "";
 				return {
 					content: [
-						{ type: "text", text: `Saved taskflow '${def.name}' → ${filePath}\nRun it with /tf:${def.name} or action=run.` },
+						{ type: "text", text: `Saved taskflow '${def.name}' → ${filePath}\nRun it with /tf:${def.name} or action=run.${warningText}` },
 					],
 					details: { action, message: filePath } satisfies TaskflowDetails,
 				};
 			}
 
 			// run
-			const v = validateTaskflow(def);
-			if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
 			const args = resolveArgs(def, params.args);
+			const v = validateTaskflow(def, { args, cwd: ctx.cwd });
+			if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
+			for (const w of v.warnings) {
+				console.warn(`[taskflow:${def.name}] ${w}`);
+			}
 			const result = await runFlow(def, args, ctx, signal, onUpdate as any);
+			// Surface the validation warnings in the tool result so the model
+			// can acknowledge or fix them, and the user sees them in the chat.
+			if (v.warnings.length) {
+				result.finalOutput = `${result.finalOutput}\n\nWarnings:\n- ${v.warnings.join("\n- ")}`;
+			}
 			return finalResult(action, result);
 		},
 

package/extensions/interpolate.ts

@@ -20,7 +20,7 @@ export interface InterpolationContext {
 	locals?: Record<string, unknown>;
 }
 
-const PLACEHOLDER = /\{([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*)\}/g;
+const PLACEHOLDER = /\{([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)\}/g;
 
 export interface InterpolationResult {
 	text: string;

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 "./usage.ts";
+import { type UsageStats } from "./usage.ts";
 import type { PhaseState, RunState } from "./store.ts";
 import { dependenciesOf, type Phase, topoLayers } from "./schema.ts";
 
@@ -62,23 +62,16 @@ function miniBar(done: number, total: number, theme: Theme, width = 8): string {
 	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 agentRole(phase: Phase, ps: PhaseState | undefined, theme: Theme): string {
+	const role = phase.agent ?? phase.type ?? "agent";
+	const model = ps?.model ? shortModel(ps.model) : "";
+	if (!model) return theme.fg("accent", role);
+	return theme.fg("accent", role) + theme.fg("dim", `（${model}）`);
 }
 
-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 costStr(usage: UsageStats | undefined, theme: Theme): string {
+	if (!usage?.cost) return "";
+	return theme.fg("muted", `$${usage.cost.toFixed(3)}`);
 }
 
 function aggregateCost(state: RunState): number {
@@ -118,7 +111,7 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	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}`);
+		return theme.fg("muted", `skipped · ${snip}`) + (ps.warnings?.length ? theme.fg("warning", `  ⚠${ps.warnings.length}`) : "");
 	}
 
 	const isFanout = type === "map" || type === "parallel" || type === "flow";
@@ -131,30 +124,34 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 			return (
 				theme.fg("toolOutput", `${done - failed}/${total}`) +
 				theme.fg("error", ` ${failed}✗`) +
-				(snip ? theme.fg("error", `  ${snip}`) : "")
+				(snip ? theme.fg("error", `  ${snip}`) : "") +
+				(ps.warnings?.length ? theme.fg("warning", `  ⚠${ps.warnings.length}`) : "")
 			);
 		}
-		return theme.fg("error", snip);
+		return theme.fg("error", snip) + (ps.warnings?.length ? theme.fg("warning", `  ⚠${ps.warnings.length}`) : "");
 	}
 
 	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);
+		const roleLabel = agentRole(phase, ps, theme);
+		const cost = costStr(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}`;
+			s += `  ${roleLabel}`;
+			if (cost) s += `  ${cost}`;
 			if (time) s += `  ${time}`;
+			if (ps.warnings?.length) s += theme.fg("warning", `  ⚠${ps.warnings.length}`);
 			return s;
 		}
-		let s = model ? theme.fg("accent", model) : theme.fg("warning", "running…");
-		if (tokens) s += `  ${tokens}`;
+		let s = roleLabel;
+		if (cost) s += `  ${cost}`;
 		if (time) s += `  ${time}`;
+		if (ps.warnings?.length) s += theme.fg("warning", `  ⚠${ps.warnings.length}`);
 		return s;
 	}
 
@@ -163,20 +160,22 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 		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}`;
+		const cost = costStr(ps.usage, theme);
+		if (cost) s += `  ${cost}`;
 		if (time) s += `  ${time}`;
+		if (ps.warnings?.length) s += theme.fg("warning", `  ⚠${ps.warnings.length}`);
 		return s;
 	}
 	// single-agent done
-	const model = shortModel(ps.model);
-	const u = compactUsage(ps.usage, theme);
+	const roleLabel = agentRole(phase, ps, theme);
+	const cost = costStr(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()));
+		let a = theme.fg("warning", "⚠") + " " + 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}`;
+		if (ps.warnings?.length) a += theme.fg("warning", `  ⚠${ps.warnings.length}`);
 		return a;
 	}
 	if (ps.gate) {
@@ -187,16 +186,18 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 			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)}`;
+		const cost = costStr(ps.usage, theme);
+		if (cost) g += `  ${cost}`;
 		if (time) g += `  ${time}`;
+		if (ps.warnings?.length) g += theme.fg("warning", `  ⚠${ps.warnings.length}`);
 		return g;
 	}
-	let s = "";
-	if (model) s += theme.fg("accent", model);
-	if (u) s += (s ? "  " : "") + u;
+	let s = roleLabel;
+	if (cost) s += `  ${cost}`;
 	if (ps.attempts && ps.attempts > 1) s += theme.fg("warning", `  ↻${ps.attempts - 1}`);
 	if (time) s += `  ${time}`;
-	return s || theme.fg("dim", "done");
+	if (ps.warnings?.length) s += theme.fg("warning", `  ⚠${ps.warnings.length}`);
+	return s;
 }
 
 /** Header line: status glyph + name + compact totals. */

package/extensions/runner.ts

@@ -48,12 +48,67 @@ export function isFailed(r: RunResult): boolean {
 	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
 }
 
+/** Placeholder written to a failed phase's `output` so downstream interpolation
+ *  can detect "upstream failed" without being polluted by raw HTML/JSON. */
+export const TRANSPORT_ERROR_PLACEHOLDER = "(upstream error: subagent failed; see error)";
+
+/** Hard cap on the errorMessage field stored in PhaseState (≈ 4 KB). */
+export const ERROR_MESSAGE_MAX_LEN = 4096;
+
+/** Cheap HTML/JSON detector so we can summarize upstream garbage. */
+export function looksLikeHtmlOrJson(s: string): boolean {
+	const t = s.trimStart();
+	if (!t) return false;
+	if (t.startsWith("<")) {
+		// HTML/XML/Cloudflare challenge pages
+		return /^<(?:!doctype\s+html|html|head|body|script|svg|div|iframe|span|p)\b/i.test(t);
+	}
+	if (t.startsWith("{")) {
+		// Truncated JSON. A genuine JSON envelope is fine to keep; an unwrapped
+		// {error: "..."} from an SDK is short. We only treat it as "garbage" if
+		// it parses and is huge — but that's caught by the size cap below.
+		return false;
+	}
+	return false;
+}
+
+/**
+ * Truncate and (when obviously HTML) summarize an errorMessage before it is
+ * persisted. Returns the cleaned string. Empty input returns empty.
+ */
+export function sanitizeErrorMessage(raw: string | undefined): string {
+	if (!raw) return "";
+	const cleaned = raw.replace(/\s+/g, " ").trim();
+	if (!cleaned) return "";
+	// Decide the sanitization branch on the RAW length, not the whitespace-
+	// collapsed length — otherwise an HTML page padded with spaces would slip
+	// through the "looks like HTML" branch and be persisted as-is.
+	const rawLen = raw.length;
+	if (rawLen > ERROR_MESSAGE_MAX_LEN) {
+		const head = cleaned.slice(0, 200);
+		const tail = cleaned.slice(-200);
+		return `${head} ... [truncated ${rawLen - 400} chars] ... ${tail}`;
+	}
+	if (looksLikeHtmlOrJson(cleaned)) {
+		// Any document-like HTML (Cloudflare challenge pages, proxy error pages,
+		// gateway error pages) is a strong signal the upstream returned a page
+		// instead of JSON. Summarize it instead of letting HTML pollute the
+		// phase's error and downstream interpolation contexts.
+		const title = cleaned.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1]?.trim();
+		const stripped = cleaned.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+		const m = stripped.match(/(?:Unable to load site|Ray ID[: ]+([A-Za-z0-9]+)|[A-Z][a-z]+Error[: ]+(.{0,200}))/i);
+		const hint = title || (m ? (m[1] || m[0]).trim() : stripped.slice(0, 200));
+		return `Upstream returned non-JSON response (${rawLen} chars). Hint: ${hint}`;
+	}
+	return cleaned;
+}
+
 function getFinalOutput(messages: Message[]): string {
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const msg = messages[i];
 		if (msg.role === "assistant") {
 			for (const part of msg.content) {
-				if (part.type === "text") return part.text;
+				if (part.type === "text" && part.text.trim()) return part.text;
 			}
 		}
 	}
@@ -289,8 +344,17 @@ export async function runAgentTask(
 			result.stopReason = "aborted";
 			result.errorMessage = "Subagent was aborted";
 		}
+		// On failure, build a short, structured errorMessage + a placeholder
+		// output. We deliberately do NOT copy the raw errorMessage into
+		// `output`: upstream providers (e.g. a Cloudflare challenge page) can
+		// surface huge HTML/JSON in errorMessage, and that garbage would
+		// otherwise flow into downstream phase interpolations.
 		if (isFailed(result) && !result.output) {
-			result.output = result.errorMessage || result.stderr || "(no output)";
+			result.output = TRANSPORT_ERROR_PLACEHOLDER;
+			if (!result.errorMessage) {
+				result.errorMessage = result.stderr || `Subagent exited with code ${result.exitCode} (stopReason: ${result.stopReason ?? "unknown"})`;
+			}
+			result.errorMessage = sanitizeErrorMessage(result.errorMessage);
 		}
 		return result;
 	} finally {

package/extensions/runtime.ts

@@ -10,6 +10,8 @@
  * result are skipped.
  */
 
+import * as path from "node:path";
+import * as fs from "node:fs";
 import type { AgentConfig } from "./agents.ts";
 import { coerceArray, evaluateCondition, interpolate, type InterpolationContext, safeParse } from "./interpolate.ts";
 import { isFailed, type LiveUpdate, mapWithConcurrencyLimit, runAgentTask, type RunResult } from "./runner.ts";
@@ -147,6 +149,9 @@ function mergePhaseState(
 	const ran = results.filter((r) => r.stopReason !== "budget-skipped");
 	const anyFailed = ran.some(isFailed);
 	const usage = aggregateUsage(results.map((r) => r.usage));
+	// B12: surface the model(s) used in the fan-out so consumers can show
+	// which model produced the merged output.
+	const model = ran.find((r) => r.model !== undefined)?.model;
 	// Combine outputs as a labelled list; also expose a JSON array of outputs.
 	const combinedText = ran
 		.map((r, i) => `### [${i + 1}/${ran.length}] ${r.agent}${isFailed(r) ? " (failed)" : ""}\n\n${r.output}`)
@@ -163,6 +168,7 @@ function mergePhaseState(
 		output: combinedText,
 		json: jsonArray,
 		usage,
+		model,
 		attempts: attempts > results.length ? attempts : undefined,
 		budgetTruncated: budgetSkips.length > 0 || undefined,
 		subProgress: { done: ran.length, total: results.length, running: 0, failed: failedCount },
@@ -188,6 +194,89 @@ function liveSink(state: RunState, phaseId: string, emitProgress: () => void): (
 	};
 }
 
+
+/**
+ * Pre-read files listed in a phase's `context` field and return them as
+ * markdown code blocks. Handles:
+ * - literal paths
+ * - interpolation refs (e.g. `{steps.scout.json}` resolving to `["a.ts"]`)
+ * - per-file truncation via `contextLimit`
+ *
+ * The result is a single string that should be prepended to the phase task so
+ * the subagent never needs to spend turns on file exploration.
+ */
+const CONTEXT_MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_TOTAL_CONTEXT_CHARS = 200_000;
+
+async function resolvePhaseContext(
+	phase: Phase,
+	ctx: InterpolationContext,
+): Promise<string> {
+	const entries = phase.context;
+	if (!entries || entries.length === 0) return "";
+	const limit = phase.contextLimit ?? 8000;
+
+	const paths: string[] = [];
+	for (const entry of entries) {
+		const r = interpolate(entry, ctx);
+		if (r.text !== entry) {
+			// Resolved — may be a JSON array from {steps.X.json}
+			const parsed = safeParse(r.text);
+			if (Array.isArray(parsed)) {
+				for (const item of parsed) {
+					if (typeof item === "string" && item.trim()) paths.push(item.trim());
+				}
+			} else if (typeof r.text === "string" && r.text.trim()) {
+				paths.push(r.text.trim());
+			}
+		} else {
+			// Unchanged — literal path
+			paths.push(entry);
+		}
+	}
+
+	const unique = Array.from(new Set(paths));
+
+	// Diagnose JSON blobs masquerading as file paths — common when a context
+	// entry like {steps.discover.output} resolves to {"files":[...]} instead
+	// of a flat path or JSON array. The author should use {steps.discover.json.files}.
+	const jsonBlobs = unique.filter((p) => p.startsWith("{"));
+	for (const blob of jsonBlobs) {
+		console.warn(
+			`[taskflow] Context entry "${blob.slice(0, 80)}…" looks like a JSON object, not a file path. ` +
+				`Use {steps.<id>.json.<field>} to extract a specific field.`,
+		);
+	}
+	const filtered = jsonBlobs.length ? unique.filter((p) => !p.startsWith("{")) : unique;
+
+	const blocks: string[] = [];
+	for (const p of filtered) {
+		try {
+			const abs = path.resolve(p);
+			const stat = fs.statSync(abs);
+			if (!stat.isFile()) continue;
+			if (stat.size > CONTEXT_MAX_FILE_BYTES) continue;
+			const content = fs.readFileSync(abs, "utf-8");
+			const truncated =
+				content.length > limit
+					? content.slice(0, limit) + `\n... [truncated ${content.length - limit} chars]`
+					: content;
+			const ext = path.extname(p).slice(1) || "txt";
+			blocks.push(`## File: ${p}\n\n\`\`\`${ext}\n${truncated}\n\`\`\``);
+		} catch {
+			console.warn(`[taskflow] Skipped unreadable context file: ${p}`);
+		}
+	}
+
+	// Safety cap: truncate total context when too many files are listed.
+	let result = blocks.join("\n\n") + "\n\n";
+	if (result.length > MAX_TOTAL_CONTEXT_CHARS) {
+		result = result.slice(0, MAX_TOTAL_CONTEXT_CHARS) + `\n\n... [truncated ${result.length - MAX_TOTAL_CONTEXT_CHARS} total chars]`;
+	}
+	return result;
+}
+
+
 async function executePhase(
 	phase: Phase,
 	state: RunState,
@@ -200,6 +289,12 @@ async function executePhase(
 	const previousOutput = lastCompletedOutput(state, phase);
 	const run = deps.runTask ?? runAgentTask;
 
+	// Resolve context pre-read files once, before any type branching.
+	// The content is prepended to every task so the subagent never spends
+	// turns on file exploration for files the flow author already knows.
+	const ctx = buildInterpolationContext(state, previousOutput);
+	const preRead = await resolvePhaseContext(phase, ctx);
+
 	const baseRun = (agentName: string, task: string, onLive?: (l: LiveUpdate) => void) =>
 		run(
 			deps.cwd,
@@ -228,6 +323,10 @@ async function executePhase(
 			if (deps.signal?.aborted) break;
 			last = await baseRun(agentName, task, onLive);
 			usages.push(last.usage);
+			// B6: aggregate and surface cumulative usage before the retry decision,
+			// so the TUI / budget guard see the in-flight spend on every attempt.
+			const liveRetry = state.phases[phase.id];
+			if (liveRetry) liveRetry.usage = aggregateUsage(usages);
 			if (!isFailed(last)) break;
 			// Stop retrying on abort or once the run is over budget.
 			if (deps.signal?.aborted || overBudget(state).over) break;
@@ -313,24 +412,26 @@ async function executePhase(
 	// interpolated task. gate additionally parses a verdict; reduce simply pulls
 	// its inputs from `from` phases (already exposed via interpolation).
 	if (type === "agent" || type === "gate" || type === "reduce") {
-		const ctx = buildInterpolationContext(state, previousOutput);
 		const { text } = interpolate(phase.task ?? "", ctx);
-		const inputHash = hashInput(phase.id, phase.agent ?? "", text);
+		const fullTask = preRead + text;
+		const inputHash = hashInput(phase.id, phase.agent ?? "", fullTask);
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
-		const r = await runOne(phase.agent ?? defaultAgent(deps), text, liveSink(state, phase.id, emitProgress));
+		const r = await runOne(phase.agent ?? defaultAgent(deps), fullTask, liveSink(state, phase.id, 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") {
-		const ctx = buildInterpolationContext(state, previousOutput);
-		const branches = (phase.branches ?? []).map((b) => ({
-			agent: b.agent ?? phase.agent ?? defaultAgent(deps),
-			task: interpolate(b.task, ctx).text,
-		}));
+		const branches = (phase.branches ?? []).map((b) => {
+			const r = interpolate(b.task, ctx);
+			return {
+				agent: b.agent ?? phase.agent ?? defaultAgent(deps),
+				task: preRead + r.text,
+			};
+		});
 		const inputHash = hashInput(phase.id, JSON.stringify(branches));
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
@@ -340,7 +441,6 @@ async function executePhase(
 	}
 
 	if (type === "map") {
-		const ctx = buildInterpolationContext(state, previousOutput);
 		const overResolved = interpolate(phase.over ?? "", ctx).text;
 		// `over` may itself be a placeholder that resolved to a JSON string.
 		const arr = coerceArray(safeParse(overResolved)) ?? coerceArray(directRef(phase.over ?? "", state));
@@ -359,7 +459,7 @@ async function executePhase(
 			const localCtx = buildInterpolationContext(state, previousOutput, { [loopVar]: item });
 			return {
 				agent: phase.agent ?? defaultAgent(deps),
-				task: interpolate(phase.task ?? "", localCtx).text,
+				task: preRead + interpolate(phase.task ?? "", localCtx).text,
 			};
 		});
 		const inputHash = hashInput(phase.id, JSON.stringify(tasks));
@@ -424,7 +524,7 @@ async function executePhase(
 			provided[k] = typeof v === "string" ? interpolate(v, ctx).text : v;
 		}
 		const subArgs = resolveArgs(subDef, provided);
-		const inputHash = hashInput(phase.id, `flow:${name}`, JSON.stringify(subArgs));
+		const inputHash = hashInput(phase.id, `flow:${name}`, preRead, JSON.stringify(subArgs));
 		const cached = cachedPhase(prior, inputHash);
 		if (cached) return cached;
 
@@ -442,10 +542,16 @@ async function executePhase(
 			phases: {},
 			createdAt: Date.now(),
 			updatedAt: Date.now(),
-			cwd: deps.cwd,
+			cwd: phase.cwd ?? deps.cwd,
 		};
+		// B8: pass this flow phase's preRead content to every sub-flow phase by
+		// wrapping runTask — sub-phase preRead still gets prepended on top of it.
+		const baseRunTask = deps.runTask ?? runAgentTask;
+		const subRunTask: typeof runAgentTask = (cwd, agents, agentName, subTask, opts, globalThinking) =>
+			baseRunTask(cwd, agents, agentName, preRead + subTask, opts, globalThinking);
 		const subResult = await executeTaskflow(subState, {
 			...deps,
+			runTask: subRunTask,
 			_stack: [...stack, state.flowName],
 			persist: undefined,
 			onProgress: () => {
@@ -494,7 +600,7 @@ async function executePhase(
 
 /** Resolve a `{steps.x.json}`-style ref directly to its parsed value (bypassing stringify). */
 function directRef(over: string, state: RunState): unknown {
-	const m = over.match(/^\{steps\.([a-zA-Z0-9_]+)\.(output|json)(?:\.([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*))?\}$/);
+	const m = over.match(/^\{steps\.([a-zA-Z0-9_-]+)\.(output|json)(?:\.([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*))?\}$/);
 	if (!m) return undefined;
 	const step = state.phases[m[1]];
 	if (!step || step.status !== "done") return undefined;

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";
 
@@ -102,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 },
 );
@@ -126,6 +139,13 @@ export const TaskflowSchema = Type.Object(
 		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 },
@@ -190,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
@@ -228,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>();
@@ -318,7 +355,99 @@ export function validateTaskflow(def: unknown): ValidationResult {
 	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. */

package/extensions/store.ts

@@ -45,6 +45,12 @@ export interface PhaseState {
 	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 {
@@ -148,8 +154,48 @@ export function saveRun(state: RunState): void {
 }
 
 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;

package/package.json

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

package/skills/taskflow/SKILL.md

@@ -188,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
@@ -197,7 +276,7 @@ variables, and storage paths — read `configuration.md` (next to this file).
 
 Quick reference:
 
-- **Flow:** `name`, `description`, `concurrency` (default 8), `budget` (`maxUSD`/`maxTokens`), `agentScope` (user|project|both), `args`.
+- **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.