pi-taskflow 0.0.20 → 0.0.22

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to pi-taskflow are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [0.0.22] — 2026-06-10
+
+> Dogfooding release. The `dogfood-full` self-audit taskflow (which itself
+> exercises all 9 phase types + when/join/retry/budget/cache/eval/flow-def/
+> loop/tournament/approval) ran against the codebase and surfaced these fixes.
+
+### Added
+- **Live auto-refresh for the `/tf runs` panel.** The run-history panel was a static snapshot taken when opened, so a background (detached) run's progress never updated while watching. It now polls run state on a 1s interval and re-renders only when a run's status/`updatedAt` actually changes — phase progress (including `map`/`parallel` `subProgress` like `24/24`) updates live. The user's selection follows the same `runId` across refreshes, a green `● live` tag shows while any run is running, and the refresh timer is cleared on close (`dispose()`) and `unref`'d so it never keeps the event loop alive. Fully backward-compatible: without live hooks the panel renders statically as before.
+  - 5 new tests (`test/runs-view.test.ts`): refresh-on-change, no-render-when-unchanged, dispose-stops-timer, selection-follows-runId, back-compat-no-hooks.
+
+### Fixed
+- **`safeParse` now prefers a `json`-tagged fence in multi-fence output.** When an LLM phase emitted an evidence block (e.g. ```` ```typescript ````) *before* the ```` ```json ```` payload, the old single-match regex grabbed the first fence, failed to parse, and the balanced-bracket fallback was misled by braces in the prose — `safeParse` returned `undefined` and any downstream `map` phase failed with `'over' did not resolve to an array`. It now scans every fenced block and tries `json`-tagged ones first, then untagged. (3 new multi-fence tests.)
+- **Unresolved interpolation refs are surfaced as phase warnings.** `interpolate()` returns `missing[]` (placeholders with no source), but the runtime discarded it on the main task path — so `{args.typo}` or a `{steps.x.output}` without `dependsOn` was silently left intact in the dispatched task. The `interpolate.ts` doc comment promised "a recorded warning" that no code produced. The runtime now logs `[taskflow] phase X: unresolved refs ...` and attaches the message to `PhaseState.warnings` (persisted in the run record, visible in `/tf runs`). Doc comment corrected to match.
+
+## [0.0.21] — 2026-06-10
+
+### Added
+- **Per-step context pre-read in shorthand modes.** Single, chain, and tasks shorthand steps now accept `context` (file paths) and `contextLimit`, desugared directly onto the generated phases. This eliminates `O(N²)` file exploration without writing the full DSL. In parallel `tasks` mode all branches share the deduped union of step contexts; chain steps each carry their own context. A top-level `context` in chain mode produces a warning (no unsupported flow-level default). Context-file changes automatically invalidate phase caches.
+
+### Fixed
+- **Headless approval safety.** Approval phases now auto-reject (not auto-approve) when running in detached/background/CI mode, preventing silent bypass of human gates.
+- **Step-reference validator accepts transitive ancestors.** The step-reference checker previously raised false positives on valid DAGs where dependencies span multiple levels of ancestry. Ancestor transitive closure is now fully resolved.
+
 ## [0.0.20] — 2026-06-10
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-43D9AD?style=flat-square" alt="MIT license"></a>
   <a href="#whats-inside"><img src="https://img.shields.io/badge/runtime%20deps-0-43D9AD?style=flat-square" alt="zero runtime dependencies"></a>
   <a href="https://github.com/heggria/pi-taskflow/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/heggria/pi-taskflow/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
-  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-535-6E8BFF?style=flat-square" alt="535 tests"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-608-6E8BFF?style=flat-square" alt="608 tests"></a>
   <a href="#whats-inside"><img src="https://img.shields.io/badge/dogfooded-%E2%9C%93-43D9AD?style=flat-square" alt="dogfooded"></a>
   <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-B692FF?style=flat-square" alt="for the Pi coding agent"></a>
 </p>
@@ -304,7 +304,7 @@ Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8), `agen
 - **`when`** — skip a phase unless an expression is truthy. Supports `{refs}`, `== != < > <= >=`, `&& || !`, parentheses, and quoted strings/numbers. Pair with `join: "any"` on the merge phase for 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 all).
 - **`retry`** — `{ "max": 2, "backoffMs": 500, "factor": 2 }` retries a failing subagent with fixed or exponential backoff; usage is summed and the attempt count shows as `↻N` in the TUI. Transient provider errors (rate-limit / 5xx / timeout) **auto-retry even without an explicit policy**; hard errors don't.
-- **`approval`** — pause for a human (Approve / Reject / Edit). Reject halts the flow; Edit injects the typed note as the phase output for downstream steps. Non-interactive runs auto-approve.
+- **`approval`** — pause for a human (Approve / Reject / Edit). Reject halts the flow; Edit injects the typed note as the phase output for downstream steps. Non-interactive runs auto-reject (safety: approval gates are never bypassed).
 - **`flow`** — `{ "type": "flow", "use": "deep-research", "with": { "topic": "{item}" } }` runs a **saved** flow as a phase (recursion is detected and rejected). Or **generate the sub-flow at runtime**: `{ "type": "flow", "def": "{steps.plan.json}" }` resolves an upstream phase's JSON output into a sub-flow, **validates it (cycles / dangling refs / duplicate ids), then runs it** — the number and shape of the generated phases is decided at runtime, not authored in advance. A malformed plan fails *open* (the phase is skipped with a `defError`, the run continues). This is how a planner decides *at runtime* what work to spawn — the declarative answer to a code-mode `for` loop, with each generated plan checked before it spends a token. Pair it with `loop` for **data-dependent iterative replanning** (round N's plan depends on round N-1's result). See [`examples/dynamic-plan-execute.json`](./examples/dynamic-plan-execute.json) and [`examples/iterative-replan.json`](./examples/iterative-replan.json).
 
 ### Loop-until-done (`loop`)
@@ -434,7 +434,7 @@ Resume is keyed on each phase's input hash — if an upstream output changed, de
 ```
 .pi/taskflows/<name>.json          # project-scoped definitions (commit to share)
 ~/.pi/agent/taskflows/<name>.json  # user-scoped definitions
-.pi/taskflows/runs/<runId>.json    # run state for resume (gitignore this)
+.pi/taskflows/runs/<flowName>/<runId>.json  # run state for resume (gitignore this)
 ```
 
 > Commit `.pi/taskflows/` and your whole team shares the pipelines — no config sync, no onboarding doc. Run state is written atomically and guarded by a zero-dependency file lock, so concurrent runs never corrupt the index.
@@ -608,12 +608,12 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 
 <div align="center">
 
-**0 runtime dependencies** · **535 tests** · **9 phase types** · **cross-session resume** · **cross-run memoization** · **~5.4k LOC runtime**
+**0 runtime dependencies** · **608 tests** · **9 phase types** · **cross-session resume** · **cross-run memoization** · **~7.7k LOC runtime**
 
 </div>
 
 - **Zero runtime dependencies.** No `dependencies` field — the runtime is built entirely on Node built-ins (`fs` / `path` / `os` / `child_process` / `crypto`). The file lock is `fs.openSync("wx")`, not a third-party library.
-- **535 tests across 21 test files** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, cross-run cache freshness (flow/thinking/tools key isolation, fingerprint invalidation, TTL/LRU eviction), gate verdicts, budget caps, retry/backoff, approval flows, loop termination, tournament judging, sub-flow composition, callback isolation, the idle watchdog, model-role init config, and parseModelFromLabel with parenthesized-model-name regression.
+- **608 tests across 26 test files** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, cross-run cache freshness (flow/thinking/tools key isolation, fingerprint invalidation, TTL/LRU eviction), gate verdicts, budget caps, retry/backoff, approval flows, loop termination, tournament judging, sub-flow composition, live run-history refresh, callback isolation, the idle watchdog, model-role init config, and parseModelFromLabel with parenthesized-model-name regression.
 - **Hardened by design.** Path-traversal defense (lexical + `realpath`), runId validation, HTML/error sanitization, atomic writes, stale-lock stealing via `rename`, and an idle watchdog that kills wedged subagents.
 - **Dogfooded.** Every new feature has to survive the project's own `self-improve` taskflow before it ships.
 
@@ -637,7 +637,7 @@ Our `self-improve` flow is a 10-phase DAG — it audits the codebase, patches de
 
 ## Status & limits
 
-**v0.0.17** — loop-until-done (`loop` phase: iterate to a condition, convergence, or cap), tournament (best-of-N with a judge), cross-run memoization (content-addressed cache with git/file/glob/env fingerprints and TTL), interactive `/tf init` with role-aware model pickers + diff preview + atomic merge-write, configurable built-in agents, 18 built-in agents with 6 model roles. Full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`). Inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
+**v0.0.20** — loop-until-done (`loop` phase: iterate to a condition, convergence, or cap), tournament (best-of-N with a judge), cross-run memoization (content-addressed cache with git/file/glob/env fingerprints and TTL), interactive `/tf init` with role-aware model pickers + diff preview + atomic merge-write, configurable built-in agents, 18 built-in agents with 6 model roles. Full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`). Inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
 
 Known boundaries (tracked, bounded — no surprises mid-flow):
 

package/extensions/agents.ts

@@ -74,6 +74,7 @@ export interface AgentConfig {
 	filePath: string;
 }
 
+/** @internal */
 export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
@@ -224,7 +225,13 @@ export interface SubagentSettings {
  * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
  * Returns undefined if the value is not a role reference or the role is unmapped.
  */
-export function resolveModelRole(model: string | undefined, roles?: Record<string, string>): string | undefined {
+/**
+ * Resolve `{{roleName}}` model references against a role→model mapping.
+ * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
+ * Returns undefined if the value is not a role reference or the role is unmapped.
+ * @internal
+ */
+function resolveModelRole(model: string | undefined, roles?: Record<string, string>): string | undefined {
 	if (!model || !roles) return model;
 	const match = model.match(/^\{\{(\w+)\}\}$/);
 	if (!match) return model;

package/extensions/approval-view.ts

@@ -6,11 +6,15 @@
  * before deciding. Every line is padded to the full dialog width so the
  * overlay composites cleanly (no see-through, no ghosting in scrollback).
  *
- * While the dialog is open, SGR mouse reporting is enabled so the wheel
- * scrolls the viewport instead of the terminal scrollback. It is restored
- * on dispose.
+ * Mouse tracking is intentionally NOT used here. Enabling terminal-level
+ * SGR mouse reporting (DECSET 1000h/1006h) to capture wheel events would
+ * interfere with the terminal's native scrollback after the dialog closes,
+ * because the restore sequence depends on the overlay framework reliably
+ * calling dispose — which is not guaranteed across all lifecycle paths.
+ * Keyboard scrolling (↑↓/PgUp/PgDn/Home/End/j/k/g/G) covers the same
+ * ground without risking a stuck mouse-tracking mode.
  *
- * Keys: wheel/↑↓ scroll · PgUp/PgDn page · Home/End jump ·
+ * Keys: ↑↓ scroll · PgUp/PgDn page · Home/End jump ·
  *       a/Enter approve · e edit (guidance) · r/Esc reject.
  */
 
@@ -28,31 +32,16 @@ export interface ApprovalViewOptions {
 	upstream?: string;
 }
 
-/** Minimal writer used to toggle terminal mouse reporting. */
-export interface TerminalWriter {
-	write(data: string): void;
-}
-
 const FALLBACK_ROWS = 24;
-/** Wheel ticks scroll this many lines. */
-const WHEEL_STEP = 3;
-/** SGR mouse sequence: ESC [ < B ; X ; Y (M|m) */
-const MOUSE_SGR = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/;
-/** Enable basic mouse tracking + SGR encoding. */
-const MOUSE_ON = "\x1b[?1000h\x1b[?1006h";
-/** Restore: disable SGR encoding + mouse tracking. */
-const MOUSE_OFF = "\x1b[?1006l\x1b[?1000l";
 
 export class ApprovalViewComponent {
 	private theme: Theme;
 	private opts: ApprovalViewOptions;
 	private onDone: (choice: ApprovalChoice) => void;
 	private getRows: () => number;
-	private term?: TerminalWriter;
 	private scrollOffset = 0;
 	private cachedWidth?: number;
 	private cachedBody?: string[];
-	private mouseEnabled = false;
 	private decided = false;
 
 	constructor(
@@ -60,43 +49,19 @@ export class ApprovalViewComponent {
 		opts: ApprovalViewOptions,
 		onDone: (choice: ApprovalChoice) => void,
 		getRows?: () => number,
-		term?: TerminalWriter,
 	) {
 		this.theme = theme;
 		this.opts = opts;
 		this.onDone = onDone;
 		this.getRows = getRows ?? (() => FALLBACK_ROWS);
-		this.term = term;
-		this.enableMouse();
-	}
-
-	private enableMouse(): void {
-		if (this.term && !this.mouseEnabled) {
-			try {
-				this.term.write(MOUSE_ON);
-				this.mouseEnabled = true;
-			} catch {
-				// non-tty / closed stream — wheel support is best-effort
-			}
-		}
 	}
 
-	/** Restore terminal mouse state. Idempotent; call from the overlay's dispose. */
-	dispose(): void {
-		if (this.term && this.mouseEnabled) {
-			this.mouseEnabled = false;
-			try {
-				this.term.write(MOUSE_OFF);
-			} catch {
-				// ignore
-			}
-		}
-	}
+	/** No-op — kept for compatibility with Pi TUI overlay dispose contract. */
+	dispose(): void {}
 
 	private decide(choice: ApprovalChoice): void {
 		if (this.decided) return;
 		this.decided = true;
-		this.dispose();
 		this.onDone(choice);
 	}
 
@@ -155,17 +120,6 @@ export class ApprovalViewComponent {
 	}
 
 	handleInput(data: string): void {
-		// Mouse events (SGR) — wheel scrolls, everything else is swallowed.
-		const mouse = MOUSE_SGR.exec(data);
-		if (mouse) {
-			const b = Number(mouse[1]);
-			if (b & 64) {
-				// Wheel: low two bits 0 = up, 1 = down.
-				if ((b & 3) === 0) this.clampScroll(-WHEEL_STEP);
-				else if ((b & 3) === 1) this.clampScroll(WHEEL_STEP);
-			}
-			return;
-		}
 		// Decisions
 		if (matchesKey(data, "return") || data === "a" || data === "y") {
 			this.decide("approve");
@@ -251,7 +205,7 @@ export class ApprovalViewComponent {
 
 		// Key hints
 		lines.push(this.hrule(width, "├", "┤"));
-		const scrollHint = cap > 0 ? "wheel/↑↓/PgUp/PgDn scroll · " : "";
+		const scrollHint = cap > 0 ? "↑↓/PgUp/PgDn scroll · " : "";
 		lines.push(this.row(th.fg("dim", `${scrollHint}a/Enter approve · e edit · r/Esc reject`), width));
 		lines.push(this.hrule(width, "╰", "╯"));
 		return lines;

package/extensions/cache.ts

@@ -135,6 +135,7 @@ export function resolveFingerprint(entries: string[] | undefined, cwd: string):
 // Cross-run cache store
 // ---------------------------------------------------------------------------
 
+/** @internal */
 export interface CacheEntry {
 	/** The full cache key (== phase inputHash incl. fingerprint). */
 	key: string;

package/extensions/detached-runner.ts

@@ -56,8 +56,8 @@ try {
 		agents,
 		globalThinking: settings.globalThinking,
 		persist: (s) => saveRun(s, cleanupConfig),
-		// No requestApproval — approval phases auto-reject in detached mode
-		// (fail-open: phase records the rejection, run continues).
+		// No requestApproval — approval phases auto-reject in detached/CI mode
+		// (safety: approval gates are never bypassed; the run records the rejection).
 		loadFlow: (name: string) => getFlow(ctx.cwd, name)?.def,
 	});
 

package/extensions/index.ts

@@ -59,6 +59,15 @@ const ShorthandStep = Type.Object(
 	{
 		agent: Type.Optional(Type.String({ description: "Agent for this step (defaults to the first available agent)" })),
 		task: Type.String({ description: "Task prompt for this step (supports {previous.output} in chains)" }),
+		context: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"File paths to pre-read and inject before this step's task (same as Phase.context). In parallel `tasks` mode all branches SHARE the union of step contexts.",
+			}),
+		),
+		contextLimit: Type.Optional(
+			Type.Number({ description: "Max characters to read per context file (default 8000)." }),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -82,6 +91,15 @@ const TaskflowParams = Type.Object({
 	task: Type.Optional(
 		Type.String({ description: "Shorthand single mode: the task prompt (like subagent single mode)" }),
 	),
+	context: Type.Optional(
+		Type.Array(Type.String(), {
+			description:
+				"Shorthand single mode: file paths to pre-read and inject before the task (same as Phase.context).",
+		}),
+	),
+	contextLimit: Type.Optional(
+		Type.Number({ description: "Shorthand single mode: max characters to read per context file (default 8000)." }),
+	),
 	tasks: Type.Optional(
 		Type.Array(ShorthandStep, {
 			description: "Shorthand parallel mode: run these tasks concurrently and merge results (like subagent parallel)",
@@ -188,7 +206,6 @@ async function runFlow(
 							},
 							done,
 							() => tui.terminal.rows,
-							tui.terminal,
 						);
 						const onAbort = () => done("reject");
 						signal?.addEventListener("abort", onAbort, { once: true });
@@ -573,7 +590,7 @@ export default function (pi: ExtensionAPI) {
 					: params.tasks
 						? { tasks: params.tasks, name: params.name }
 						: params.task
-							? { task: params.task, agent: params.agent, name: params.name }
+							? { task: params.task, agent: params.agent, name: params.name, context: params.context, contextLimit: params.contextLimit }
 							: undefined);
 
 			if (shorthandSpec !== undefined) {
@@ -781,8 +798,13 @@ export default function (pi: ExtensionAPI) {
 					);
 					return;
 				}
-				const result = await ctx.ui.custom<RunHistoryResult | undefined>((_tui, theme, _kb, done) => {
-					return new RunHistoryComponent(runs, theme, (r) => done(r));
+				const result = await ctx.ui.custom<RunHistoryResult | undefined>((tui, theme, _kb, done) => {
+					const comp = new RunHistoryComponent(runs, theme, (r) => done(r), {
+						refresh: () => listRuns(ctx.cwd, 50),
+						requestRender: () => tui.requestRender(),
+						intervalMs: 1000,
+					});
+					return comp;
 				});
 				if (result?.action === "resume") {
 					if (ctx.isIdle()) {

package/extensions/interpolate.ts

@@ -8,8 +8,11 @@
  *   {previous.output}   alias for the immediately-preceding completed phase output
  *   {item} / {item.f}   map loop variable (or custom name via phase.as)
  *
- * Unknown placeholders are left intact (with a recorded warning) rather than
- * throwing, so a partially-specified task still runs.
+ * Unknown placeholders are left intact rather than throwing, so a
+ * partially-specified task still runs. The unresolved refs are returned in
+ * `missing[]`; the runtime surfaces them as a phase warning (see
+ * `warnUnresolvedRefs` in runtime.ts) — logged and persisted to
+ * `PhaseState.warnings`.
  */
 
 export interface InterpolationContext {
@@ -123,13 +126,21 @@ export function safeParse(text: string): unknown {
 	} catch {
 		// noop
 	}
-	// Extract from a ```json fenced block
-	const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
-	if (fence) {
+	// Extract from fenced blocks. Outputs often contain multiple fences
+	// (e.g. a ```typescript evidence block before the ```json payload), so try
+	// every fence — json-tagged blocks first, then untagged/other blocks.
+	const fenceRe = /```(\w*)[ \t]*\r?\n?([\s\S]*?)```/g;
+	const fenced: { lang: string; body: string }[] = [];
+	let fm: RegExpExecArray | null;
+	while ((fm = fenceRe.exec(trimmed)) !== null) {
+		fenced.push({ lang: fm[1].toLowerCase(), body: fm[2].trim() });
+	}
+	const ordered = [...fenced.filter((b) => b.lang === "json"), ...fenced.filter((b) => b.lang !== "json")];
+	for (const block of ordered) {
 		try {
-			return JSON.parse(fence[1].trim());
+			return JSON.parse(block.body);
 		} catch {
-			// noop
+			// noop — try the next fence
 		}
 	}
 	// Extract the first balanced [...] or {...}

package/extensions/runner.ts

@@ -69,7 +69,7 @@ export interface RunOptions {
  * 5 minutes is generous enough for slow reasoning/long tool calls while still
  * bounding a true hang.
  */
-export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
 
 export function isFailed(r: RunResult): boolean {
 	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";

package/extensions/runs-view.ts

@@ -40,6 +40,19 @@ function isResumable(r: RunState): boolean {
 	return r.status === "paused" || r.status === "failed";
 }
 
+/** Detect whether a refreshed run list differs from the current one in any way
+ * the panel renders (status, updatedAt, phase progress, membership). */
+function hasChanged(prev: RunState[], next: RunState[]): boolean {
+	if (prev.length !== next.length) return true;
+	const byId = new Map(prev.map((r) => [r.runId, r]));
+	for (const n of next) {
+		const p = byId.get(n.runId);
+		if (!p) return true;
+		if (p.status !== n.status || p.updatedAt !== n.updatedAt) return true;
+	}
+	return false;
+}
+
 export class RunHistoryComponent {
 	private runs: RunState[];
 	private theme: Theme;
@@ -48,14 +61,62 @@ export class RunHistoryComponent {
 	private mode: "list" | "detail" = "list";
 	private cachedWidth?: number;
 	private cachedLines?: string[];
+	/** Live-refresh wiring: re-read run state from disk while the panel is open
+	 * so background (detached) runs show live progress without reopening. */
+	private timer?: ReturnType<typeof setInterval>;
+	private refresh?: () => RunState[];
+	private requestRender?: () => void;
 
-	constructor(runs: RunState[], theme: Theme, onDone: (result?: RunHistoryResult) => void) {
+	constructor(
+		runs: RunState[],
+		theme: Theme,
+		onDone: (result?: RunHistoryResult) => void,
+		/** Optional live-refresh hooks. When both are provided the panel polls
+		 * `refresh()` on an interval and calls `requestRender()` if anything changed. */
+		live?: { refresh: () => RunState[]; requestRender: () => void; intervalMs?: number },
+	) {
 		if (!runs.length) {
 			throw new Error("RunHistoryComponent requires at least one run");
 		}
 		this.runs = runs;
 		this.theme = theme;
 		this.onDone = onDone;
+		if (live) {
+			this.refresh = live.refresh;
+			this.requestRender = live.requestRender;
+			const intervalMs = Math.max(250, live.intervalMs ?? 1000);
+			this.timer = setInterval(() => this.poll(), intervalMs);
+			// Don't keep the event loop alive just for the panel refresh.
+			(this.timer as { unref?: () => void }).unref?.();
+		}
+	}
+
+	/** Re-read run state; if anything changed, refresh the cached render. */
+	private poll(): void {
+		if (!this.refresh) return;
+		let next: RunState[];
+		try {
+			next = this.refresh();
+		} catch {
+			return; // transient read/lock error — try again next tick
+		}
+		if (!next.length) return;
+		if (!hasChanged(this.runs, next)) return;
+		// Preserve the user's selection by runId across refreshes.
+		const selectedId = this.runs[this.selected]?.runId;
+		this.runs = next;
+		const idx = next.findIndex((r) => r.runId === selectedId);
+		this.selected = idx >= 0 ? idx : Math.min(this.selected, next.length - 1);
+		this.invalidate();
+		this.requestRender?.();
+	}
+
+	/** Stop the refresh timer when the panel closes. */
+	dispose(): void {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = undefined;
+		}
 	}
 
 	handleInput(data: string): void {
@@ -104,7 +165,8 @@ export class RunHistoryComponent {
 			for (const l of renderProgress(run, th).split("\n")) lines.push(truncateToWidth(l, width));
 			lines.push("");
 			const hint = isResumable(run) ? "Esc back · r resume" : "Esc back";
-			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}`, width));
+			const liveTag = this.timer && run.status === "running" ? th.fg("success", " ● live") : "";
+			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}${liveTag}`, width));
 			lines.push("");
 			this.cachedWidth = width;
 			this.cachedLines = lines;
@@ -129,7 +191,11 @@ export class RunHistoryComponent {
 		});
 
 		lines.push("");
-		lines.push(truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}`, width));
+		const anyRunning = this.runs.some((r) => r.status === "running");
+		const liveHint = this.timer && anyRunning ? th.fg("success", " ● live") : "";
+		lines.push(
+			truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}${liveHint}`, width),
+		);
 		lines.push("");
 
 		this.cachedWidth = width;

package/extensions/runtime.ts

@@ -47,7 +47,7 @@ export interface RuntimeDeps {
 	onProgress?: (state: RunState) => void;
 	/** Injectable task runner (defaults to spawning a real subagent). Enables testing. */
 	runTask?: typeof runAgentTask;
-	/** Resolve an `approval` phase. Omit for non-interactive runs (auto-approve). */
+	/** Resolve an `approval` phase. Omit for non-interactive runs (auto-reject). */
 	requestApproval?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
 	/** Resolve a saved taskflow by name for `flow` (sub-workflow) phases. */
 	loadFlow?: (name: string) => Taskflow | undefined;
@@ -87,8 +87,7 @@ function buildInterpolationContext(
 	return { args: state.args, steps, previousOutput, locals };
 }
 
-function resultToPhaseState(id: string, r: RunResult, inputHash: string, parseJson: boolean): PhaseState {
-	const failed = isFailed(r);
+function resultToPhaseState(id: string, r: RunResult, inputHash: string, parseJson: boolean): PhaseState {	const failed = isFailed(r);
 	const attempts = attemptsOf(r);
 	// For failed phases, embed the error info in the output so downstream
 	// phases (and the user) can see what went wrong. The raw r.output is
@@ -110,6 +109,22 @@ function resultToPhaseState(id: string, r: RunResult, inputHash: string, parseJs
 	};
 }
 
+/**
+ * Surface unresolved interpolation placeholders (the `missing[]` from
+ * `interpolate()`). Without this they are silently left intact in the task —
+ * the doc comment in interpolate.ts promises "a recorded warning". We both
+ * log to the console and return a string to attach to PhaseState.warnings so
+ * the warning is persisted in the run record and visible in `/tf runs`.
+ * Returns undefined when nothing is missing.
+ */
+function warnUnresolvedRefs(phaseId: string, missing: string[]): string | undefined {
+	if (!missing.length) return undefined;
+	const unique = Array.from(new Set(missing));
+	const msg = `unresolved refs in task: ${unique.map((m) => `{${m}}`).join(", ")} — left intact (check dependsOn / placeholder spelling)`;
+	console.warn(`[taskflow] phase '${phaseId}': ${msg}`);
+	return msg;
+}
+
 /** Attempts recorded by the retry wrapper (defaults to 1). */
 function attemptsOf(r: RunResult): number {
 	const a = r.attempts;
@@ -392,6 +407,7 @@ async function executePhase(
 		runId: state.runId,
 		thinking: phase.thinking,
 		tools: phase.tools,
+		preRead,
 	};
 
 	const baseRun = (agentName: string, task: string, onLive?: (l: LiveUpdate) => void) =>
@@ -581,7 +597,9 @@ async function executePhase(
 				return ps;
 			}
 		}
-		const { text } = interpolate(phase.task ?? "", ctx);
+		const interp = interpolate(phase.task ?? "", ctx);
+		const text = interp.text;
+		const refWarning = warnUnresolvedRefs(phase.id, interp.missing);
 		const fullTask = preRead + text;
 		const agentName = resolveAgent(phase.agent, deps, state);
 		const inputHash = cacheKey(cc, [phase.id, agentName, phase.model ?? "", fullTask]);
@@ -590,6 +608,7 @@ async function executePhase(
 
 		const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress));
 		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
+		if (refWarning) ps.warnings = [...(ps.warnings ?? []), refWarning];
 		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
 
 		// onBlock:retry — re-execute upstream + gate until pass or max attempts.
@@ -700,13 +719,16 @@ async function executePhase(
 		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
-		// Non-interactive (headless/CI/tests): auto-approve, fail-open, but record it.
+		// Non-interactive (headless/CI/detached): auto-REJECT, fail-open, but record it.
+		// Approval gates are safety boundaries — bypassing them silently in CI would
+		// let unreviewed work ship. Detached/CI runs must not bypass approval gates.
 		if (!deps.requestApproval) {
 			return {
 				id: phase.id,
 				status: "done",
-				output: "(auto-approved: no interactive approver available)",
-				approval: { decision: "approve", auto: true },
+				output: "(auto-rejected: no interactive approver available)",
+				approval: { decision: "reject", auto: true },
+				gate: { verdict: "block", reason: "(auto-rejected: no interactive approver available)" },
 				usage: emptyUsage(),
 				inputHash,
 				endedAt: Date.now(),
@@ -1185,15 +1207,26 @@ interface PhaseCacheCtx {
 	 *  silently serve a stale cross-run hit). */
 	thinking?: string;
 	tools?: string[];
+	/** Resolved `context` pre-read content. Explicitly part of the cache identity
+	 *  so a context-file change always invalidates the phase — independent of
+	 *  whether a given branch happens to fold preRead into its task string
+	 *  (previously this was only incidentally true via `fullTask`). */
+	preRead?: string;
 }
 
 /** Fold the phase fingerprint into the base hash parts to form the final cache key. */
 function cacheKey(cc: PhaseCacheCtx, baseParts: string[]): string {
 	// Fold the full cache identity into the hash: flow name (prevents collisions
 	// across different flows that share a phase.id + task + model), the per-phase
-	// thinking/tools config (changing either changes the subagent's output), and
-	// the resolved world-state fingerprint.
-	const parts = [`flow:${cc.flowName}`, ...baseParts, `think:${cc.thinking ?? ""}`, `tools:${JSON.stringify(cc.tools ?? [])}`];
+	// thinking/tools config (changing either changes the subagent's output), the
+	// resolved context pre-read content, and the world-state fingerprint.
+	const parts = [
+		`flow:${cc.flowName}`,
+		...baseParts,
+		`think:${cc.thinking ?? ""}`,
+		`tools:${JSON.stringify(cc.tools ?? [])}`,
+		`ctx:${cc.preRead ?? ""}`,
+	];
 	return cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
 }
 

package/extensions/schema.ts

@@ -13,8 +13,8 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament"] as const;
-export type PhaseType = (typeof PHASE_TYPES)[number];
+const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament"] as const;
+type PhaseType = (typeof PHASE_TYPES)[number];
 
 /** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
 export const LOOP_DEFAULT_MAX_ITERATIONS = 10;
@@ -36,17 +36,18 @@ export const MAX_DYNAMIC_CONCURRENCY = 16;
 /** Tournament competitor bounds. */
 export const TOURNAMENT_DEFAULT_VARIANTS = 3;
 export const TOURNAMENT_HARD_MAX_VARIANTS = 20;
-export const TOURNAMENT_MODES = ["best", "aggregate"] as const;
+const TOURNAMENT_MODES = ["best", "aggregate"] as const;
+/** @internal */
 export type TournamentMode = (typeof TOURNAMENT_MODES)[number];
 
-export const OUTPUT_FORMATS = ["text", "json"] as const;
-export const JOIN_MODES = ["all", "any"] as const;
-export const CACHE_SCOPES = ["run-only", "cross-run", "off"] as const;
+const OUTPUT_FORMATS = ["text", "json"] as const;
+const JOIN_MODES = ["all", "any"] as const;
+const CACHE_SCOPES = ["run-only", "cross-run", "off"] as const;
 export type CacheScope = (typeof CACHE_SCOPES)[number];
 /** Allowed fingerprint entry prefixes. `glob!:` = content-hash variant of `glob:`. */
-export const CACHE_FINGERPRINT_PREFIXES = ["git:", "glob:", "glob!:", "file:", "env:"] as const;
+const CACHE_FINGERPRINT_PREFIXES = ["git:", "glob:", "glob!:", "file:", "env:"] as const;
 /** Phase types that must NOT be cached across runs (a fresh result is required each run). */
-export const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament"] as const;
+const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -282,7 +283,7 @@ export type ArgSpec = Static<typeof ArgSpecSchema>;
 export type RetryPolicy = Static<typeof RetrySchema>;
 export type Budget = Static<typeof BudgetSchema>;
 export type CachePolicy = Static<typeof CacheSchema>;
-export type JoinMode = (typeof JOIN_MODES)[number];
+type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
 // Shorthand (non-DAG) specs — subagent-style ergonomics
@@ -302,6 +303,10 @@ export type JoinMode = (typeof JOIN_MODES)[number];
 export interface ShorthandStep {
 	agent?: string;
 	task: string;
+	/** Files to pre-read and inject before the task (pass-through to Phase.context). */
+	context?: string[];
+	/** Max characters per context file (pass-through to Phase.contextLimit). */
+	contextLimit?: number;
 }
 
 /** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
@@ -316,11 +321,22 @@ export function isShorthand(def: unknown): boolean {
 	);
 }
 
+/** Coerce an unknown value into a non-empty list of non-empty strings (or undefined). */
+function readContextList(v: unknown): string[] | undefined {
+	if (!Array.isArray(v)) return undefined;
+	const list = v.filter((x): x is string => typeof x === "string" && x.trim().length > 0);
+	return list.length ? list : undefined;
+}
+
 function readStep(s: unknown): ShorthandStep {
 	if (typeof s === "string") return { task: s };
 	if (s && typeof s === "object") {
 		const o = s as Record<string, unknown>;
-		return { agent: typeof o.agent === "string" ? o.agent : undefined, task: String(o.task ?? "") };
+		const step: ShorthandStep = { agent: typeof o.agent === "string" ? o.agent : undefined, task: String(o.task ?? "") };
+		const ctx = readContextList(o.context);
+		if (ctx) step.context = ctx;
+		if (typeof o.contextLimit === "number") step.contextLimit = o.contextLimit;
+		return step;
 	}
 	return { task: "" };
 }
@@ -345,10 +361,19 @@ export function desugar(def: unknown): Taskflow {
 
 	// chain → sequential agent phases
 	if (Array.isArray(d.chain) && d.chain.length > 0) {
+		// Spec-level context in chain mode would be a flow-level default (every
+		// step), which is deliberately NOT supported — declare it per step instead.
+		if (d.context !== undefined || d.contextLimit !== undefined) {
+			console.warn(
+				"[taskflow] Shorthand chain ignores top-level 'context'/'contextLimit' — put them on individual steps instead.",
+			);
+		}
 		const steps = d.chain.map(readStep);
 		const phases: Phase[] = steps.map((s, i) => {
 			const phase: Phase = { id: `step${i + 1}`, type: "agent", task: s.task };
 			if (s.agent) phase.agent = s.agent;
+			if (s.context) phase.context = s.context;
+			if (s.contextLimit !== undefined) phase.contextLimit = s.contextLimit;
 			if (i > 0) phase.dependsOn = [`step${i}`];
 			if (i === steps.length - 1) phase.final = true;
 			return phase;
@@ -356,16 +381,30 @@ export function desugar(def: unknown): Taskflow {
 		return { name: nameOf("chain"), ...meta, phases };
 	}
 
-	// tasks → one parallel phase (fan-out + merge), no extra aggregation agent
+	// tasks → one parallel phase (fan-out + merge), no extra aggregation agent.
+	// Context is SHARED across all branches (the runtime pre-reads per phase, not
+	// per branch): spec-level context plus the union of step-level contexts.
 	if (Array.isArray(d.tasks) && d.tasks.length > 0) {
-		const branches: ParallelTask[] = d.tasks.map(readStep).map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
-		return { name: nameOf("parallel"), ...meta, phases: [{ id: "parallel", type: "parallel", branches, final: true }] };
+		const steps = d.tasks.map(readStep);
+		const branches: ParallelTask[] = steps.map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
+		const phase: Phase = { id: "parallel", type: "parallel", branches, final: true };
+		const shared = [...(readContextList(d.context) ?? []), ...steps.flatMap((s) => s.context ?? [])];
+		if (shared.length) phase.context = Array.from(new Set(shared));
+		const limits = [
+			typeof d.contextLimit === "number" ? d.contextLimit : undefined,
+			...steps.map((s) => s.contextLimit),
+		].filter((n): n is number => typeof n === "number");
+		if (limits.length) phase.contextLimit = Math.max(...limits);
+		return { name: nameOf("parallel"), ...meta, phases: [phase] };
 	}
 
-	// single task → one agent phase
+	// single task → one agent phase (the spec itself is the step)
 	if (typeof d.task === "string") {
 		const phase: Phase = { id: "main", type: "agent", task: d.task, final: true };
 		if (typeof d.agent === "string") phase.agent = d.agent;
+		const ctx = readContextList(d.context);
+		if (ctx) phase.context = ctx;
+		if (typeof d.contextLimit === "number") phase.contextLimit = d.contextLimit;
 		return { name: nameOf("task"), ...meta, phases: [phase] };
 	}
 
@@ -376,6 +415,7 @@ export function desugar(def: unknown): Taskflow {
 // Validation (beyond schema: DAG integrity, phase-type requirements)
 // ---------------------------------------------------------------------------
 
+/** @internal */
 export interface ValidationResult {
 	ok: boolean;
 	errors: string[];
@@ -618,16 +658,41 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 	// placeholder string. The runtime can't infer the intent — fail fast at
 	// validation time so the mistake is caught before the run starts.
 	//
+	// The check uses TRANSITIVE ancestors: if phase B depends on A, and C depends
+	// on B, then C may reference {steps.A.*} transitively. Only truly unreachable
+	// refs are errors.
+	//
 	// Phases with `join: "any"` are exempt: by design they only need ONE of
 	// their declared deps to complete, and may reference other phases as
 	// informational context (not as true dependencies).
 	if (errors.length === 0) {
 		const idToPhase = new Map((flow.phases as Phase[]).map((p) => [p.id, p]));
+		// Precompute transitive ancestors for every phase via BFS over dependsOn.
+		const transitiveCache = new Map<string, Set<string>>();
+		const transitiveAncestors = (phaseId: string): Set<string> => {
+			const cached = transitiveCache.get(phaseId);
+			if (cached) return cached;
+			const result = new Set<string>();
+			const queue = [...(idToPhase.get(phaseId)?.dependsOn ?? []), ...(idToPhase.get(phaseId)?.from ?? [])];
+			while (queue.length) {
+				const id = queue.shift()!;
+				if (result.has(id)) continue;
+				result.add(id);
+				const dep = idToPhase.get(id);
+				if (dep) {
+					for (const d of [...(dep.dependsOn ?? []), ...(dep.from ?? [])]) {
+						if (!result.has(d)) queue.push(d);
+					}
+				}
+			}
+			transitiveCache.set(phaseId, result);
+			return result;
+		};
 		for (const p of flow.phases as Phase[]) {
 			if (!p?.id) continue;
 			const isJoinAny = p.join === "any";
 			if (isJoinAny) continue;
-			const deps = new Set(dependenciesOf(p));
+			const transitive = transitiveAncestors(p.id);
 			const refs = collectRefs(p);
 			for (const ref of refs.steps) {
 				if (ref === p.id) {
@@ -640,9 +705,9 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 					// double-warn — the dependsOn loop above already flags it.
 					continue;
 				}
-				if (!deps.has(ref)) {
+				if (!transitive.has(ref)) {
 					errors.push(
-						`Phase '${p.id}': task references {steps.${ref}.*} but '${ref}' is not in dependsOn. ` +
+						`Phase '${p.id}': task references {steps.${ref}.*} but '${ref}' is not reachable via dependsOn. ` +
 							`The phase will run in parallel with '${ref}' and see the literal placeholder. ` +
 							`Add "dependsOn": ["${ref}"] (or include '${ref}' transitively).`,
 					);

package/extensions/store.ts

@@ -29,6 +29,7 @@ export interface SavedFlow {
 	def: Taskflow;
 }
 
+/** @internal */
 export type PhaseStatus = "pending" | "running" | "done" | "failed" | "skipped";
 
 export interface PhaseState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "A declarative, verifiable graph of task nodes for the Pi coding agent — not a workflow you script, but a DAG you declare: statically verified before it runs, with dynamic fan-out, gates, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",
@@ -37,7 +37,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= 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/init.test.ts test/render.test.ts test/approval-view.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts test/verify.test.ts test/gate-eval.test.ts test/transient-error.test.ts test/runtime-branches.test.ts test/interpolate-extended.test.ts test/store-extended.test.ts test/flow-def.test.ts test/detached.test.ts",
+    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= 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/init.test.ts test/render.test.ts test/approval-view.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts test/verify.test.ts test/gate-eval.test.ts test/transient-error.test.ts test/runtime-branches.test.ts test/interpolate-extended.test.ts test/store-extended.test.ts test/flow-def.test.ts test/detached.test.ts test/runs-view.test.ts",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts",
     "test:dogfood-cache": "node --experimental-strip-types test/dogfood-cache.mts"
   },

package/skills/taskflow/SKILL.md

@@ -43,10 +43,25 @@ proper flow, so you still get progress, persistence, resume, and `save`.
 ```
 
 - `agent` is optional (defaults to the first available agent).
+- `context` (optional, per step or top-level in single mode): file paths to
+  pre-read and inject before the task — same as the full-DSL `Phase.context`
+  (per-file `contextLimit`, default 8000 chars). In **parallel `tasks` mode**
+  all branches SHARE the union of step contexts (the runtime pre-reads per
+  phase, not per branch). In **chain mode** declare `context` on individual
+  steps; a top-level `context` is ignored (with a warning).
 - Add `name` to label the run (and to `save` it as a `/tf:<name>` command).
 - Precedence if several are given: `chain` > `tasks` > `task`.
 - You can pass these as top-level tool params **or** inside `define`.
 
+```jsonc
+// context pre-read in shorthand — the file content is injected before the task
+{ "chain": [
+  { "task": "Map the public API of src/lib", "agent": "scout" },
+  { "task": "Write docs for:\n{previous.output}", "agent": "doc-writer",
+    "context": ["AGENTS.md", "docs/style-guide.md"] }
+] }
+```
+
 ## How to author a taskflow
 
 Call the `taskflow` tool. To run a brand-new flow you write inline, pass
@@ -128,7 +143,7 @@ deciding. The (interpolated) `task` is the prompt shown.
 - **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.
+- **Non-interactive** runs (headless/CI/print mode) **auto-reject** and record it — approval gates are safety boundaries that must never be silently bypassed.
 - **Background (detached)** runs **auto-reject** (no interactive approver) — downstream sees the rejection; the flow continues (fail-open).
 
 ```jsonc
@@ -170,9 +185,10 @@ Use hyphens in ids, never underscores. Sub-flow phases reference each other in
 their **own** `{steps.x.output}` namespace (no parent-id prefixing needed).
 
 **Fail-open & limits:** if the `def` doesn't parse, has the wrong shape, or fails
-validation, the phase fails *open* — it's marked failed with a `defError`, the
-upstream output is preserved, and the run continues (use `optional: true` on the
-flow phase so a bad plan never aborts the run). An **empty** `phases` array is a
+validation, the phase completes with `status: "done"` and carries a `defError`
+diagnostic field; downstream phases receive empty output. Authors who want a
+hard failure can add a gate that checks for `defError`. The run continues
+(add `optional: true` on the flow phase so a bad plan never aborts the run). An **empty** `phases` array is a
 valid no-op (the planner decided there's nothing to do). Inline nesting is capped
 at `MAX_DYNAMIC_NESTING` (5) to bound runaway self-spawning.
 
@@ -217,7 +233,7 @@ A `tournament` phase runs `variants` competing attempts in parallel, then a
 (`mode: "aggregate"`). Use it when one shot is unreliable and you want the best
 of several drafts, or a synthesis of diverse approaches.
 
-- `variants` — the competing attempts: a number (run the same `task` N times) or an array of `{task, agent?}` for genuinely different approaches.
+- `variants` — a number specifying how many competing variants to spawn from 'task' (default 3, max 20). For genuinely different approaches, use the `branches` field instead — an explicit array of `{task, agent?}` definitions.
 - `mode` — `"best"` (judge picks one winner, default) or `"aggregate"` (judge merges all into one output).
 - `judge` — the judge's rubric/instructions (how to choose or merge).
 - `judgeAgent` — *(optional)* the agent that runs the judge step; defaults to the phase `agent`.
@@ -450,12 +466,13 @@ Add `detach: true` to `action: "run"` to spawn the flow in a detached child proc
 
 ## Operating a run (lifecycle, resume, inspection)
 
-A run moves through: **running →** `completed` (a `final` phase produced output) **/** `blocked` (a gate emitted BLOCK, an `approval` was rejected, or the `budget` cap was hit) **/** `failed` (a non-`optional` phase errored) **/** `paused` (the run was aborted). `failed` and `paused` runs are resumable; `blocked` is terminal (fix the gate/budget and re-run).
+A run moves through: **running →** `completed` (a `final` phase produced output) **/** `blocked` (a gate emitted BLOCK, an `approval` was rejected, or the `budget` cap was hit) **/** `failed` (a non-`optional` phase errored) **/** `paused` (the run was aborted). `failed` and `paused` runs are resumable.
 
-- **Resume is cache-aware.** `action: "resume"` re-runs only what didn't finish: every phase already `done` is reused from its recorded output (within-run cache), so resuming after a crash or a `blocked`/`failed` stop never repeats completed work. A phase that was mid-flight is re-executed cleanly (stale `error`/`endedAt` are cleared first).
+- **`blocked` runs:** a blocked status halts the current run — the flow status is set to `blocked` and remaining phases are skipped. Re-running the flow resumes from the last completed state: `done` phases with matching input hashes are skipped; blocked/failed/skipped phases are re-attempted. Fix the gate condition or budget before re-running.
+- **Resume is cache-aware.** `action: "resume"` re-runs only what didn't finish: every phase already `done` is reused from its recorded output (within-run cache), so resuming after a crash or a failed/blocked stop never repeats completed work. A phase that was mid-flight is re-executed cleanly (stale `error`/`endedAt` are cleared first).
 - **When to resume vs. re-run.** Resume when the inputs are unchanged and you just want to continue/retry the tail (fixed a gate, raised the budget, approved a checkpoint). Re-run from scratch when the task or upstream inputs changed — resume would reuse now-stale outputs. (For reuse *across* runs, opt a phase into `cache: {scope:"cross-run"}` — see configuration.md.)
 - **Budget mid-run.** When the run-wide `budget` is exceeded, remaining phases are skipped and an in-flight `map`/`parallel` stops spawning new items; the run ends `blocked` with the partial outputs preserved.
-- **Inspect runs.** `/tf runs` lists recent runs with status; `/tf show <name>` prints a saved flow's definition. Run state lives at `<project .pi>/taskflows/runs/<runId>.json` (gitignored).
+- **Inspect runs.** `/tf runs` lists recent runs with status; `/tf show <name>` prints a saved flow's definition. Run state lives at `<project .pi>/taskflows/runs/<flowName>/<runId>.json` (gitignored).
 
 ## User commands
 

package/skills/taskflow/configuration.md

@@ -286,7 +286,7 @@ for the design.
 ### `ttl` (cross-run only)
 
 Max age before a cross-run hit is treated as a miss: e.g. `"30m"`, `"6h"`, `"7d"`.
-Omit for no time bound. A hit older than the TTL re-executes the phase.
+Omit for no time bound. A hit older than the TTL re-executes the phase. Cross-run cache entries are hard-evicted after 90 days regardless of per-entry TTL. This ceiling is not configurable.
 
 ### `fingerprint` (cross-run only)
 
@@ -298,7 +298,7 @@ Each entry is one of:
 | Entry | Becomes a miss when… | Resolves to |
 |-------|----------------------|-------------|
 | `git:HEAD` / `git:<ref>` | the commit moves | the resolved SHA (30s timeout → `<timeout>`; no git → `<no-git>`) |
-| `glob:<pattern>` | the **set of matching paths** changes | sorted path list (mtime-free) |
+| `glob:<pattern>` | the **set of matching paths** or their metadata changes | sorted path list with size + mtime (content-hashed globs use `glob!:` instead, which is mtime-independent) |
 | `glob!:<pattern>` | the **contents** of matching files change | content hashes (capped at 5000 matches) |
 | `file:<path>` | that file's content changes | sha256 of the file (>10 MB or missing → `<skip>`/`<missing>`) |
 | `env:<NAME>` | the env var changes | the env value |
@@ -333,7 +333,7 @@ Each entry is one of:
 |------|------|---------|
 | User-scoped flow | `~/.pi/agent/taskflows/<name>.json` | personal |
 | Project-scoped flow | `<nearest .pi>/taskflows/<name>.json` | ✅ commit to share |
-| Run state (resume) | `<project .pi>/taskflows/runs/<runId>.json` | ❌ gitignore |
+| Run state (resume) | `<project .pi>/taskflows/runs/<flowName>/<runId>.json` | ❌ gitignore |
 
 - `action: "save"` takes `scope: "project"` (default) or `"user"`.
 - Saved flows auto-register as `/tf:<name>` (immediately for the current session,