pi-taskflow 0.0.18 → 0.0.20

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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.20] — 2026-06-10
+
+### Added
+- **Background (detached) execution — `detach: true`.** Run a taskflow in a detached child process without blocking the current session. Pass `detach: true` and get a `runId` back immediately; the flow executes in the background, persisting state to the store. Status polled via `/tf runs` and `resume` works as normal.
+  - `extensions/detached-runner.ts` (new): lightweight child-process entry script — reads serialized context, calls `executeTaskflow`, persists terminal state.
+  - `extensions/index.ts`: `detach: Boolean` parameter on the taskflow tool + child-process spawn logic (records PID in `RunState`).
+  - `extensions/store.ts`: `RunState` gains `pid?: number` + `detached?: boolean` fields; `isProcessAlive(pid)` stale-PID helper.
+  - Design: entry-point spawn wrapper — zero changes to the 1340-line `runtime.ts` core, no new phase type, no DSL version bump, fully backward-compatible.
+  - Approval phases auto-reject in background mode. Idle watchdog kills stalled children. Stale PID detection via signal-0 probe.
+  - 8 new tests (`test/detached.test.ts`): process-alive, PID persistence, end-to-end detached, crash→failed, resume after failure, stale PID, backward compat.
+
+### Fixed
+- `approvalView` initialization robustness: throws a clear error when the approval view module is unavailable, preventing silent failures in detached/background mode.
+
+## [0.0.19] — 2026-06-10
+
+### Documentation
+- **Closed the SKILL coverage gap — the LLM can now author every shipped feature.** A schema-vs-SKILL.md audit (`docs/internal/skill-coverage-audit.md`, machine-checked + cross-adversarial reviewed) found several implemented + tested features that were undocumented in the LLM-facing skill, so the model never generated them. All ~46 user-facing schema fields are now documented across SKILL.md + configuration.md.
+  - **SKILL.md**: phase-type table now lists all 9 types (added `loop`, `tournament`) with a “details” column pointing each to its section; new **Loop phases** (`until`/`maxIterations`/`convergence`) and **Tournament phases** (`variants`/`judge`/`mode`/`judgeAgent`) sections; `eval` (zero-token machine gate) and `onBlock: "retry"` (self-healing rework loop) folded into the Gate section; cross-run `cache` pointer + `optional` + static `branches` notes.
+  - **SKILL.md**: new **Operating a run** section — run lifecycle (`running → completed/blocked/failed/paused`), cache-aware resume, when to resume vs. re-run, budget-mid-run behavior, and run inspection. Clarified action semantics (`define` vs `name`, save scope/collision, `verify`/`agents` actions).
+  - **configuration.md**: new **§2.1 Context pre-reading** (`context`/`contextLimit` — resolution order, per-file 8000-char cap, 200k total cap) and **§8 Cross-run caching** (`cache.scope`, `ttl`, full `fingerprint` prefix table for git/glob/glob!/file/env). Fixed a stale “5 phase types” → 9 cross-file drift.
+- Every documented JSON example validates against the live schema; all run-status/resume claims verified against the runtime (`blocked` is terminal; `paused`/`failed` are resumable). 560 tests pass, zero regression.
+
+### CI
+- GitHub Packages publish is now best-effort (`continue-on-error`) so an unscoped-package 404 there can never block the npm publish or the GitHub Release.
+
 ## [0.0.18] — 2026-06-09
 
 ### Added

package/README.md

@@ -131,7 +131,7 @@ The Pi ecosystem now has **20+ delegation, workflow, and orchestration extension
 - **`pi-subagents` / `@gotgenes/pi-subagents`** are the mature picks for ad-hoc "use reviewer on this diff" delegation and background jobs. `pi-taskflow` is for when those delegations need to become a *repeatable, resumable pipeline*.
 - **`pi-pipeline` / `pi-agent-flow`** ship *opinionated, fixed* flows. `pi-taskflow` ships an *empty canvas*: you (or the model) declare the graph that fits the job.
 
-> The honest one-liner: **`pi-taskflow` is the only Pi extension that gives you a *declarative, verifiable, resumable* DAG of task nodes — saved as a one-word command, with zero runtime dependencies and context isolation by design.** Where code-mode workflows let the model *script* the work, `pi-taskflow` lets it *declare a graph the runtime can prove correct before running.* The known gaps it's closing next: loop-until-done, worktree isolation, and non-blocking background runs (see [`STRATEGY.md`](./STRATEGY.md)).
+> The honest one-liner: **`pi-taskflow` is the only Pi extension that gives you a *declarative, verifiable, resumable* DAG of task nodes — saved as a one-word command, with zero runtime dependencies and context isolation by design.** Where code-mode workflows let the model *script* the work, `pi-taskflow` lets it *declare a graph the runtime can prove correct before running.* The known gaps it's closing next: worktree isolation (see [`STRATEGY.md`](./STRATEGY.md)).
 
 ## 30-second start
 
@@ -641,7 +641,7 @@ Our `self-improve` flow is a 10-phase DAG — it audits the codebase, patches de
 
 Known boundaries (tracked, bounded — no surprises mid-flow):
 
-- **No detached background execution.** A run needs the Pi session open. True background execution (and event/cron triggers on top of it) is on the roadmap.
+- **Detached background execution (new).** Add `detach: true` to `action: "run"` to spawn the flow in a detached child process. The tool returns immediately with the `runId`; the flow continues running even if the host session exits. Status is polled via the store (`/tf runs` or `action: "resume"`). Approval phases auto-reject in detached mode.
 - **No `output: "file"`.** Outputs are text/JSON only — write files via an agent's `write` tool call.
 - **`map` requires a JSON array.** The `over` field must resolve to a `{steps.ID.json}` array. Wrap a text list in a single-agent `output: "json"` phase first.
 - **The DAG must be acyclic.** Cycles are rejected at validation.

package/extensions/approval-view.ts

@@ -0,0 +1,264 @@
+/**
+ * Modal approval dialog for `approval` phases (ctx.ui.custom with overlay).
+ *
+ * Rendered as a centered bordered popup: the full upstream output (e.g. a
+ * plan) is shown in a scrollable viewport so long content can be reviewed
+ * 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.
+ *
+ * Keys: wheel/↑↓ scroll · PgUp/PgDn page · Home/End jump ·
+ *       a/Enter approve · e edit (guidance) · r/Esc reject.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+export type ApprovalChoice = "approve" | "reject" | "edit";
+
+export interface ApprovalViewOptions {
+	/** Header title, e.g. "Taskflow approval — flow/phase". */
+	title: string;
+	/** Interpolated approval prompt. */
+	message: string;
+	/** Full upstream phase output (the content being approved). */
+	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(
+		theme: Theme,
+		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
+			}
+		}
+	}
+
+	private decide(choice: ApprovalChoice): void {
+		if (this.decided) return;
+		this.decided = true;
+		this.dispose();
+		this.onDone(choice);
+	}
+
+	private rows(): number {
+		try {
+			return this.getRows() || FALLBACK_ROWS;
+		} catch {
+			return FALLBACK_ROWS;
+		}
+	}
+
+	/** Visible body height given the message height — dialog targets ~80% of the terminal. */
+	private maxVisible(msgRows: number): number {
+		const avail = Math.max(10, Math.floor(this.rows() * 0.8));
+		// Chrome: top border, message rows, separator, scroll info, separator, hints, bottom border.
+		const chrome = 1 + msgRows + 1 + 1 + 1 + 1 + 1;
+		return Math.max(3, Math.min(avail - chrome, 60));
+	}
+
+	/** Wrap the upstream text to the viewport width (cached per width). */
+	private bodyLines(innerW: number): string[] {
+		if (this.cachedBody && this.cachedWidth === innerW) return this.cachedBody;
+		const out: string[] = [];
+		const upstream = (this.opts.upstream ?? "").replace(/\r\n/g, "\n").trimEnd();
+		if (upstream) {
+			for (const raw of upstream.split("\n")) {
+				if (!raw.trim()) {
+					out.push("");
+					continue;
+				}
+				for (const l of wrapTextWithAnsi(raw, innerW)) out.push(l);
+			}
+		}
+		this.cachedWidth = innerW;
+		this.cachedBody = out;
+		return out;
+	}
+
+	private msgLines(innerW: number): string[] {
+		const out: string[] = [];
+		for (const raw of this.opts.message.split("\n")) {
+			for (const l of wrapTextWithAnsi(raw, innerW)) out.push(l);
+		}
+		return out.length ? out : [""];
+	}
+
+	private maxOffset(totalLines: number, visible: number): number {
+		return Math.max(0, totalLines - visible);
+	}
+
+	private clampScroll(delta: number): void {
+		const total = this.cachedBody?.length ?? 0;
+		const visible = this.maxVisible(1);
+		const cap = this.maxOffset(total, visible);
+		this.scrollOffset = Math.max(0, Math.min(cap, this.scrollOffset + delta));
+	}
+
+	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");
+			return;
+		}
+		if (data === "e") {
+			this.decide("edit");
+			return;
+		}
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || data === "r" || data === "n") {
+			this.decide("reject");
+			return;
+		}
+		// Scrolling (only meaningful when a body exists)
+		const page = this.maxVisible(1);
+		if (matchesKey(data, "up") || data === "k") {
+			this.clampScroll(-1);
+		} else if (matchesKey(data, "down") || data === "j") {
+			this.clampScroll(1);
+		} else if (matchesKey(data, "pageUp") || matchesKey(data, "ctrl+u")) {
+			this.clampScroll(-page);
+		} else if (matchesKey(data, "pageDown") || matchesKey(data, "ctrl+d") || matchesKey(data, "space")) {
+			this.clampScroll(page);
+		} else if (matchesKey(data, "home") || data === "g") {
+			this.scrollOffset = 0;
+		} else if (matchesKey(data, "end") || data === "G") {
+			this.clampScroll(Number.MAX_SAFE_INTEGER);
+		}
+	}
+
+	/** Pad `content` with spaces to exactly `w` visible columns (ANSI-aware). */
+	private pad(content: string, w: number): string {
+		const t = truncateToWidth(content, w);
+		return t + " ".repeat(Math.max(0, w - visibleWidth(t)));
+	}
+
+	/** A full-width dialog row: │ <content padded> │ */
+	private row(content: string, width: number): string {
+		const th = this.theme;
+		const inner = this.pad(content, Math.max(1, width - 4));
+		return th.fg("border", "│") + " " + inner + " " + th.fg("border", "│");
+	}
+
+	private hrule(width: number, left: string, right: string): string {
+		const th = this.theme;
+		return th.fg("border", left + "─".repeat(Math.max(0, width - 2)) + right);
+	}
+
+	render(width: number): string[] {
+		const th = this.theme;
+		const innerW = Math.max(20, width - 4);
+		const lines: string[] = [];
+
+		// Top border with embedded title
+		const title = truncateToWidth(` ${this.opts.title} `, Math.max(0, width - 6));
+		const fill = Math.max(0, width - 4 - visibleWidth(title));
+		lines.push(
+			th.fg("border", "╭─") + th.fg("accent", title) + th.fg("border", "─".repeat(fill) + "─╮"),
+		);
+
+		// Approval prompt
+		const msg = this.msgLines(innerW);
+		for (const l of msg) lines.push(this.row(th.fg("text", l), width));
+
+		// Scrollable upstream body
+		const body = this.bodyLines(innerW);
+		const visible = this.maxVisible(msg.length);
+		const cap = this.maxOffset(body.length, visible);
+		this.scrollOffset = Math.min(this.scrollOffset, cap);
+		if (body.length > 0) {
+			lines.push(this.hrule(width, "├", "┤"));
+			const slice = body.slice(this.scrollOffset, this.scrollOffset + visible);
+			while (slice.length < Math.min(visible, body.length)) slice.push("");
+			for (const l of slice) lines.push(this.row(l, width));
+			if (cap > 0) {
+				const above = this.scrollOffset;
+				const below = Math.max(0, body.length - visible - this.scrollOffset);
+				lines.push(
+					this.row(th.fg("dim", `↑${above} more · ↓${below} more (${body.length} lines)`), width),
+				);
+			}
+		}
+
+		// Key hints
+		lines.push(this.hrule(width, "├", "┤"));
+		const scrollHint = cap > 0 ? "wheel/↑↓/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;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedBody = undefined;
+	}
+}

package/extensions/detached-runner.ts

@@ -0,0 +1,79 @@
+/**
+ * Detached runner — spawned as a child process for background (detached) runs.
+ *
+ * Reads a context JSON file (path passed as argv[2]), calls executeTaskflow,
+ * and persists the terminal state.  Top-level try/catch writes status "failed"
+ * on crash.  Approval phases auto-reject in detached mode (no interactive
+ * approver available).
+ *
+ * This file is NOT imported by index.ts — it is spawned via `child_process.spawn`.
+ */
+
+import { readFileSync } from "node:fs";
+import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
+import { executeTaskflow } from "./runtime.ts";
+import { getFlow, loadRun, saveRun, DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS } from "./store.ts";
+
+interface DetachContext {
+	runId: string;
+	defName: string;
+	args: Record<string, unknown>;
+	cwd: string;
+}
+
+const contextPath = process.argv[2];
+if (!contextPath) {
+	console.error("[detached-runner] Missing context file path argument");
+	process.exit(1);
+}
+
+let ctx: DetachContext;
+try {
+	ctx = JSON.parse(readFileSync(contextPath, "utf-8")) as DetachContext;
+} catch (e) {
+	console.error(`[detached-runner] Failed to read context: ${e instanceof Error ? e.message : String(e)}`);
+	process.exit(1);
+}
+
+const cleanupConfig = { maxKeep: DEFAULT_KEPT_RUNS, maxAgeDays: DEFAULT_RUN_AGE_DAYS };
+
+try {
+	const state = loadRun(ctx.cwd, ctx.runId);
+	if (!state) {
+		console.error(`[detached-runner] Run not found: ${ctx.runId}`);
+		process.exit(1);
+	}
+
+	// Re-discover agents using the same settings as the host session.
+	const settings = readSubagentSettings();
+	cleanupConfig.maxKeep = settings.taskflow.maxKeptRuns;
+	cleanupConfig.maxAgeDays = settings.taskflow.maxRunAgeDays;
+	const scope: AgentScope = state.def.agentScope ?? "user";
+	const { agents } = discoverAgents(ctx.cwd, scope, settings.modelRoles, settings.taskflow);
+
+	const result = await executeTaskflow(state, {
+		cwd: ctx.cwd,
+		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).
+		loadFlow: (name: string) => getFlow(ctx.cwd, name)?.def,
+	});
+
+	saveRun(result.state, cleanupConfig);
+} catch (e) {
+	// Top-level catch: persist failure so the host can poll the terminal state.
+	const message = e instanceof Error ? e.message : String(e);
+	console.error(`[detached-runner] Fatal: ${message}`);
+	try {
+		const state = loadRun(ctx.cwd, ctx.runId);
+		if (state && state.status === "running") {
+			state.status = "failed";
+			saveRun(state, cleanupConfig);
+		}
+	} catch {
+		// Best-effort — if we can't even load the state, there's nothing to persist.
+	}
+	process.exit(1);
+}

package/extensions/index.ts

@@ -27,6 +27,7 @@ import { Type } from "typebox";
 import { type AgentScope, discoverAgents, readSubagentSettings, shouldSyncBuiltinAgentsToProject, syncBuiltinAgentsToProject } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
 import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
+import { ApprovalViewComponent, type ApprovalChoice } from "./approval-view.ts";
 import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
 import { finalPhase, resolveArgs, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
 import {
@@ -110,6 +111,11 @@ const TaskflowParams = Type.Object({
 				"Destructive: overwrites modelRoles in settings.json. Required for mode='apply-defaults'.",
 		}),
 	),
+	detach: Type.Optional(
+		Type.Boolean({
+			description: "Run in background (detached child process); return runId immediately. Status polled via store.",
+		}),
+	),
 });
 
 function makeRunState(def: Taskflow, args: Record<string, unknown>, cwd: string): RunState {
@@ -166,19 +172,51 @@ async function runFlow(
 	}
 
 	// Human-in-the-loop approver — only when an interactive UI is available.
+	// Renders a centered modal popup (TUI overlay) with a scrollable viewport
+	// so long upstream output (e.g. a plan) can be reviewed in full before
+	// deciding (mouse wheel / ↑↓ / PgUp / PgDn to scroll).
 	const requestApproval = ctx.hasUI
 		? async (req: ApprovalRequest): Promise<ApprovalDecision> => {
-				if (req.upstream?.trim()) {
-					const snip = req.upstream.replace(/\s+/g, " ").trim();
-					ctx.ui.notify(`[${def.name}/${req.phaseId}] ${snip.length > 280 ? `${snip.slice(0, 280)}…` : snip}`, "info");
-				}
-				const choice = await ctx.ui.select(
-					`Taskflow approval — ${req.phaseId}: ${req.message}`,
-					["Approve", "Reject", "Edit / add guidance"],
-					{ signal },
+				const choice = await ctx.ui.custom<ApprovalChoice>(
+					(tui, theme, _kb, done) => {
+						const view = new ApprovalViewComponent(
+							theme,
+							{
+								title: `Taskflow approval — ${def.name}/${req.phaseId}`,
+								message: req.message,
+								upstream: req.upstream,
+							},
+							done,
+							() => tui.terminal.rows,
+							tui.terminal,
+						);
+						const onAbort = () => done("reject");
+						signal?.addEventListener("abort", onAbort, { once: true });
+						return {
+							render: (w: number) => view.render(w),
+							invalidate: () => view.invalidate(),
+							handleInput: (data: string) => {
+								view.handleInput(data);
+								tui.requestRender();
+							},
+							dispose: () => {
+								view.dispose();
+								signal?.removeEventListener("abort", onAbort);
+							},
+						};
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							width: "80%",
+							minWidth: 60,
+							maxHeight: "85%",
+							anchor: "center",
+						},
+					},
 				);
-				if (!choice || choice === "Reject") return { decision: "reject" };
-				if (choice.startsWith("Edit")) {
+				if (choice === "reject") return { decision: "reject" };
+				if (choice === "edit") {
 					const note = await ctx.ui.input("Guidance passed downstream as this phase's output", "type guidance…", {
 						signal,
 					});
@@ -614,6 +652,41 @@ export default function (pi: ExtensionAPI) {
 			for (const w of v.warnings) {
 				console.warn(`[taskflow:${def.name}] ${w}`);
 			}
+			// Detached (background) execution: spawn a child process and return immediately.
+			if (params.detach) {
+				const state = makeRunState(def, args, ctx.cwd);
+				state.detached = true;
+				saveRun(state);
+
+				// Serialize context for the detached runner script.
+				const { writeFileSync } = await import("node:fs");
+				const { spawn } = await import("node:child_process");
+				const os = await import("node:os");
+				const path = await import("node:path");
+				const tmpFile = path.join(os.tmpdir(), `taskflow-detach-${state.runId}.json`);
+				writeFileSync(tmpFile, JSON.stringify({
+					runId: state.runId,
+					defName: def.name,
+					args,
+					cwd: ctx.cwd,
+				}));
+
+				const runnerScript = path.join(path.dirname(new URL(import.meta.url).pathname), "detached-runner.ts");
+				const child = spawn(process.execPath, ["--experimental-strip-types", runnerScript, tmpFile], {
+					detached: true,
+					stdio: "ignore",
+				});
+				child.unref();
+
+				state.pid = child.pid ?? undefined;
+				saveRun(state);
+
+				return {
+					content: [{ type: "text", text: `Taskflow '${def.name}' started in background (pid: ${child.pid}). Run id: ${state.runId}` }],
+					details: { action, state, message: state.runId } satisfies TaskflowDetails,
+				};
+			}
+
 			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.

package/extensions/interpolate.ts

@@ -260,7 +260,7 @@ function tokenize(input: string): Tok[] {
 			continue;
 		}
 		// number
-		const numMatch = /^-?\d+(?:\.\d+)?/.exec(input.slice(i));
+		const numMatch = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(input.slice(i));
 		if (numMatch) {
 			toks.push({ t: "num", v: Number(numMatch[0]) });
 			i += numMatch[0].length;

package/extensions/runner.ts

@@ -13,6 +13,15 @@ import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "./agents.ts";
 import { emptyUsage, type UsageStats } from "./usage.ts";
 
+const activeChildren = new Set<number>();
+const killAll = () => {
+	for (const pid of activeChildren) {
+		try { process.kill(pid, "SIGKILL"); } catch { /* already dead */ }
+	}
+};
+process.on("exit", killAll);
+process.on("SIGTERM", () => { killAll(); process.exit(143); });
+
 export interface RunResult {
 	agent: string;
 	task: string;
@@ -345,6 +354,7 @@ export async function runAgentTask(
 				shell: false,
 				stdio: ["ignore", "pipe", "pipe"],
 			});
+			if (proc.pid) activeChildren.add(proc.pid);
 			let buffer = "";
 
 			// Idle watchdog: a subagent that goes silent on stdout for too long is
@@ -389,13 +399,18 @@ export async function runAgentTask(
 			// Cap prevents OOM from verbose tool output (e.g., npm install). 64 KB is
 			// generous for error diagnosis while preventing memory exhaustion.
 			const STDERR_MAX_LEN = 64 * 1024;
+			let stderrCapped = false;
 			proc.stderr.on("data", (data) => {
-				result.stderr += data.toString();
-				if (result.stderr.length >= STDERR_MAX_LEN) {
-					result.stderr = result.stderr.slice(0, STDERR_MAX_LEN) + "\n[...stderr truncated at 64KB]";
+				if (!stderrCapped) {
+					result.stderr += data.toString();
+					if (result.stderr.length >= STDERR_MAX_LEN) {
+						result.stderr = result.stderr.slice(0, STDERR_MAX_LEN) + "\n[...stderr truncated at 64KB]";
+						stderrCapped = true;
+					}
 				}
 			});
 			proc.on("close", (code, signal) => {
+				if (proc.pid) activeChildren.delete(proc.pid);
 				clearTimers();
 				if (buffer.trim()) processLine(buffer);
 				if (code === null && signal) killedBySignal = signal;

package/extensions/runtime.ts

@@ -1025,6 +1025,7 @@ async function executePhase(
 		// Using indexOf on the stable `ran` array is reference-based and correct even
 		// when two variants produce byte-identical output.
 		const ranIdx = (r: RunResult) => ran.indexOf(r) + 1;
+		const budgetSkipCount = results.filter((r) => r.stopReason === "budget-skipped").length;
 
 		// All competitors failed → the tournament fails (nothing to judge).
 		if (ok.length === 0) {
@@ -1033,6 +1034,7 @@ async function executePhase(
 				status: "failed",
 				usage: variantUsage,
 				error: `tournament '${phase.id}': all ${competitors.length} variants failed`,
+				budgetTruncated: budgetSkipCount > 0 || undefined,
 				tournament: { variants: competitors.length, winner: 0, mode },
 				inputHash: hashInput(phase.id, "tournament", String(competitors.length)),
 				endedAt: Date.now(),
@@ -1047,6 +1049,7 @@ async function executePhase(
 				json: parseJson ? safeParse(ok[0].output) : undefined,
 				usage: variantUsage,
 				model: ok[0].model,
+				budgetTruncated: budgetSkipCount > 0 || undefined,
 				tournament: { variants: competitors.length, winner: ranIdx(ok[0]), mode, reason: "only surviving variant" },
 				inputHash: hashInput(phase.id, "tournament", String(competitors.length)),
 				endedAt: Date.now(),
@@ -1062,6 +1065,7 @@ async function executePhase(
 				json: parseJson ? safeParse(ok[0].output) : undefined,
 				usage: variantUsage,
 				model: ok[0].model,
+				budgetTruncated: budgetSkipCount > 0 || undefined,
 				warnings: ["judge skipped: run aborted or budget exceeded"],
 				tournament: { variants: competitors.length, winner: ranIdx(ok[0]), mode, reason: "judge skipped" },
 				inputHash: hashInput(phase.id, "tournament", String(competitors.length)),
@@ -1095,6 +1099,7 @@ async function executePhase(
 				json: parseJson ? safeParse(ok[0].output) : undefined,
 				usage: judgeUsage,
 				model: ok[0].model,
+				budgetTruncated: budgetSkipCount > 0 || undefined,
 				warnings: [`judge failed (${judgeRes.errorMessage ?? "error"}); used variant ${ranIdx(ok[0])}`],
 				tournament: { variants: competitors.length, winner: ranIdx(ok[0]), mode, reason: "judge failed" },
 				inputHash: hashInput(phase.id, "tournament", String(competitors.length)),
@@ -1117,6 +1122,7 @@ async function executePhase(
 			json: parseJson ? safeParse(output) : undefined,
 			usage: judgeUsage,
 			model: mode === "aggregate" ? judgeRes.model : chosen.model,
+			budgetTruncated: budgetSkipCount > 0 || undefined,
 			warnings: winnerIneligible ? [`judge picked an ineligible variant; used variant ${winnerIdx}`] : undefined,
 			tournament: { variants: competitors.length, winner: winnerIdx, mode, reason },
 			inputHash: hashInput(phase.id, "tournament", String(competitors.length), mode),
@@ -1398,12 +1404,10 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 	let gateBlocked = false;
 	let gateReason = "";
 	let gateOutput = "";
-	// `budgetBlocked` gates the skipping of remaining phases once the cap is hit.
-	// `budgetSkipped` records that a phase was *actually* skipped/truncated for
-	// budget — only then is the run terminal-status "blocked" (a cap crossed by the
-	// very last phase, with nothing left to skip, must NOT mark a good run failed).
+	// `budgetBlocked` gates the skipping of remaining phases once the cap is hit
+	// and also drives the terminal "blocked" status — a maxUSD ceiling must never
+	// silently do nothing.
 	let budgetBlocked = false;
-	let budgetSkipped = false;
 	let budgetReason = "";
 	const byId = new Map(def.phases.map((p) => [p.id, p]));
 
@@ -1442,7 +1446,7 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 			}
 
 			if (skipReason) {
-				if (skipReason.startsWith("Budget exceeded")) budgetSkipped = true;
+				if (skipReason.startsWith("Budget exceeded")) budgetBlocked = true;
 				state.phases[phase.id] = {
 					id: phase.id,
 					status: "skipped",
@@ -1485,7 +1489,6 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 			// A fan-out cut short by the cap is itself a budget skip.
 			if (ps.budgetTruncated) {
 				budgetBlocked = true;
-				budgetSkipped = true;
 				if (!budgetReason) budgetReason = "fan-out truncated by budget";
 			}
 			// Budget ceiling: once exceeded, remaining phases are skipped.
@@ -1494,7 +1497,7 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 			// the budget is detected as exceeded. This bounded overshoot is
 			// acceptable: budgetBlocked prevents cascading into subsequent layers.
 			const ob = overBudget(state);
-			if (ob.over && !budgetBlocked) {
+			if (ob.over) {
 				budgetBlocked = true;
 				budgetReason = ob.reason;
 			}
@@ -1517,7 +1520,7 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 
 	state.status = aborted
 		? "paused"
-		: gateBlocked || budgetSkipped
+		: gateBlocked || budgetBlocked
 			? "blocked"
 			: anyFailed
 				? "failed"
@@ -1527,7 +1530,7 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 	let finalOutput = finalState?.output ?? "(no output)";
 	if (gateBlocked) {
 		finalOutput = `Gate blocked the workflow.${gateReason ? `\nReason: ${gateReason}` : ""}${gateOutput ? `\n\n${gateOutput}` : ""}`;
-	} else if (budgetSkipped) {
+	} else if (budgetBlocked) {
 		finalOutput = `Budget exceeded — run halted.${budgetReason ? `\nReason: ${budgetReason}` : ""}${finalState?.output ? `\n\n${finalState.output}` : ""}`;
 	}
 

package/extensions/store.ts

@@ -84,6 +84,10 @@ export interface RunState {
 	createdAt: number;
 	updatedAt: number;
 	cwd: string;
+	/** OS PID of a detached runner process (set only for background runs). */
+	pid?: number;
+	/** True for runs spawned via `detach: true` (background execution). */
+	detached?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -458,10 +462,21 @@ function cleanupTerminalRuns(
 		}
 
 		// Sort terminal by updatedAt desc (newest first).
-		terminal.sort((a, b) => b.updatedAt - a.updatedAt);
+		// Filter out entries with corrupt updatedAt (non-numeric/NaN) BEFORE sorting
+		// to prevent NaN from corrupting sort order. Corrupt entries cannot be
+		// reliably aged, so they are always moved to toRemove.
+		const cleanTerminal: RunIndexEntry[] = [];
+		for (const e of terminal) {
+			if (typeof e.updatedAt === "number" && !Number.isNaN(e.updatedAt)) {
+				cleanTerminal.push(e);
+			} else {
+				toRemove.push(e);
+			}
+		}
+		cleanTerminal.sort((a, b) => b.updatedAt - a.updatedAt);
 
-		for (let i = 0; i < terminal.length; i++) {
-			const e = terminal[i]!;
+		for (let i = 0; i < cleanTerminal.length; i++) {
+			const e = cleanTerminal[i]!;
 			const expiredByAge = now - e.updatedAt > maxAgeMs;
 			const excessByCount = i >= maxKeep;
 			if (expiredByAge || excessByCount) {
@@ -473,7 +488,7 @@ function cleanupTerminalRuns(
 
 		// Commit the pruned index while holding the lock so a concurrent
 		// updateIndexEntry cannot interleave and lose entries.
-		const remaining = terminal.filter((e) => !toRemove.includes(e));
+		const remaining = cleanTerminal.filter((e) => !toRemove.includes(e));
 		writeIndex(runsRoot, [...active, ...remaining]);
 	});
 
@@ -783,8 +798,12 @@ export function listRuns(cwd: string, limit = 20): RunState[] {
 	}
 
 	// Sort by updatedAt desc, slice to limit.
-	entries.sort((a, b) => b.updatedAt - a.updatedAt);
-	const sliced = entries.slice(0, limit);
+	// Filter out entries with non-numeric/NaN updatedAt BEFORE sorting to
+	// prevent NaN from corrupting V8's sort order (which can displace valid
+	// entries when a limit is applied).
+	const valid = entries.filter((e) => typeof e.updatedAt === "number" && !Number.isNaN(e.updatedAt));
+	valid.sort((a, b) => b.updatedAt - a.updatedAt);
+	const sliced = valid.slice(0, limit);
 
 	// Read full RunState for each entry.
 	const runs: RunState[] = [];
@@ -804,6 +823,20 @@ export function hashInput(...parts: string[]): string {
 	return crypto.createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
 }
 
+/**
+ * Check whether a process with the given PID is still alive.
+ * Uses signal 0 (no signal sent) — succeeds if the process exists and we have
+ * permission to signal it, throws ESRCH if it doesn't exist.
+ */
+export function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Write a file atomically: write to a unique temp file in the same directory,
  * then rename over the target (rename is atomic on the same filesystem). Prevents

package/package.json

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

@@ -79,15 +79,17 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 
 ### Phase types
 
-| type | meaning |
-|------|---------|
-| `agent` | one subagent runs `task` |
-| `parallel` | run `branches[]` concurrently |
-| `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
-| `gate` | quality/review step that can **halt the flow** (see below) |
-| `reduce` | aggregate `from[]` phases into one output |
-| `approval` | **human-in-the-loop** pause: ask a person to approve / reject / edit before continuing |
-| `flow` | run a **sub-flow** as one phase — **saved** (`use`) or **runtime-generated** (`def`) |
+| type | meaning | details |
+|------|---------|---------|
+| `agent` | one subagent runs `task` | DSL shape |
+| `parallel` | run `branches[]` concurrently | Conditional routing |
+| `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound | DSL shape |
+| `gate` | quality/review step that can **halt the flow** | Gate phases |
+| `reduce` | aggregate `from[]` phases into one output | DSL shape |
+| `approval` | **human-in-the-loop** pause: ask a person to approve / reject / edit before continuing | Approval phases |
+| `flow` | run a **sub-flow** as one phase — **saved** (`use`) or **runtime-generated** (`def`) | Sub-flows |
+| `loop` | repeat a body until a condition / convergence / `maxIterations` | Loop phases |
+| `tournament` | run N competing `variants`, a `judge` picks the best or aggregates | Tournament phases |
 
 ### Control-flow fields (any phase)
 
@@ -100,7 +102,9 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 ### Conditional routing (when + gate/branches)
 
 Pair `when` with an upstream phase that emits a decision to build real if/else
-routing. Use `join: "any"` on the merge phase so it runs whichever branch fired:
+routing. Use `join: "any"` on the merge phase so it runs whichever branch fired. For
+static (non-conditional) concurrency, a `parallel` phase runs fixed `branches[]`
+instead — `{ "type": "parallel", "branches": [{"task":"..."}, {"task":"...","agent":"reviewer"}] }`.
 
 ```jsonc
 { "id": "triage", "type": "agent", "agent": "analyst", "output": "json",
@@ -125,6 +129,7 @@ deciding. The (interpolated) `task` is the prompt shown.
 - **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.
+- **Background (detached)** runs **auto-reject** (no interactive approver) — downstream sees the rejection; the flow continues (fail-open).
 
 ```jsonc
 { "id": "checkpoint", "type": "approval", "dependsOn": ["plan"],
@@ -176,6 +181,62 @@ so round N's plan depends on round N-1's **result** (not a one-shot fan-out):
 the declarative equivalent of `for (...) { read result; decide next }`. See
 `examples/dynamic-plan-execute.json` and `examples/iterative-replan.json`.
 
+### Loop phases (iterate until done)
+
+A `loop` phase runs its body repeatedly, exposing each iteration's output as
+`{steps.<thisId>.output}` / `.json` so the next round can react to the last. It
+stops on the first of: `until` truthy, **convergence** (output stops changing),
+or `maxIterations` (hard cap). This is the declarative "keep going until good
+enough" — the runtime always terminates (the cap is mandatory).
+
+- `until` — stop condition, same operators as `when` (a parse error stops the loop, fail-safe).
+- `maxIterations` — hard iteration cap (required to bound the loop).
+- `convergence` — `true` to stop early when an iteration's output equals the previous one.
+
+```jsonc
+{
+  "id": "refine",
+  "type": "loop",
+  "agent": "executor",
+  "maxIterations": 5,
+  "until": "{steps.refine.json.done} == true",
+  "convergence": true,
+  "task": "Improve the draft. When nothing else needs fixing, output JSON {\"done\":true,\"draft\":\"...\"}; otherwise {\"done\":false,\"draft\":\"...\"}.",
+  "output": "json",
+  "final": true
+}
+```
+
+For data-dependent **replanning** each round, pair a `loop` body that emits a
+plan with `flow{def}` (see Sub-flows above). See `examples/iterative-replan.json`.
+
+### Tournament phases (N variants, judge picks best)
+
+A `tournament` phase runs `variants` competing attempts in parallel, then a
+**judge** sub-phase selects the winner (`mode: "best"`) or merges them
+(`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.
+- `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`.
+- Fail-open: if the judge's pick is unparseable, variant 1 is returned (work is never lost).
+
+```jsonc
+{
+  "id": "headline",
+  "type": "tournament",
+  "agent": "executor",
+  "variants": 3,
+  "mode": "best",
+  "judge": "Pick the clearest, most accurate headline. End with: WINNER: <n>.",
+  "task": "Write one headline for the article below.\n\n{steps.draft.output}",
+  "dependsOn": ["draft"],
+  "final": true
+}
+```
+
 ### Budget (cost / token caps)
 
 Add a run-wide ceiling at the top level. When accumulated cost/tokens exceed it,
@@ -206,6 +267,30 @@ Review the audit results below. If any endpoint is missing auth, end with
 {steps.audit.output}
 ```
 
+**Zero-token machine checks (`eval`).** Before spending a token on the LLM gate,
+list machine-checkable assertions in `eval`. If **all** pass, the gate
+auto-passes with **no LLM call**; if any fails, it falls through to the LLM
+`task` (the qualitative residue). Each entry supports the `when` operators plus
+`X contains Y` (substring). A parse error fails **open** (consistent with the
+gate invariant).
+
+```jsonc
+{ "id": "quality", "type": "gate", "dependsOn": ["build","test"],
+  "eval": ["{steps.build.output} contains BUILD SUCCESS", "{steps.test.json.failures} == 0"],
+  "task": "Review the diff for subtle logic errors a linter can't catch. VERDICT: PASS or BLOCK." }
+```
+
+**Self-healing (`onBlock: "retry"`).** By default a blocking gate halts the run
+(`onBlock: "halt"`). With `onBlock: "retry"` the gate instead **re-runs its
+upstream `dependsOn` phases and re-evaluates**, up to `retry.max` rounds (or
+until PASS / budget / abort) — a generate→critique→regenerate rework loop.
+
+```jsonc
+{ "id": "spec-gate", "type": "gate", "onBlock": "retry", "retry": { "max": 3 },
+  "dependsOn": ["implement"],
+  "task": "Does the implementation satisfy ALL acceptance criteria? VERDICT: PASS or BLOCK with reasons." }
+```
+
 ### Structured-verify phases (v0.0.8.1)
 
 A "verify" phase typically runs `npx tsc --noEmit && npm test && git diff --stat`
@@ -343,16 +428,34 @@ 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`, `strictInterpolation`.
-- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `when`, `join` (all|any), `retry`, `use`/`with` (flow), `final`.
+- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `when`, `join` (all|any), `retry`, `use`/`with` (flow), `optional` (fail-soft — a failed/blocked phase won't abort the run), `final`.
+- **Cross-run caching:** add `cache: { "scope": "cross-run" }` to a phase to memoize its output across runs (same input → instant reuse, zero tokens). See `configuration.md` for `ttl`, `fingerprint` (git/glob/file/env invalidation), and scope options.
 - **Precedence (model/thinking/tools):** phase value → agent frontmatter (resolved via `modelRoles`) → global/default.
 - **Concurrency:** same-layer phases use `flow.concurrency`; a `map`/`parallel` phase uses `phase.concurrency ?? flow.concurrency ?? 8`.
 
 ## Actions
 
-- `action: "run"` — run inline `define` or a saved `name` (with optional `args`).
-- `action: "save"` — persist `define` (scope `project` or `user`); becomes `/tf:<name>`.
-- `action: "resume"` — continue a paused/failed run by `runId` (completed phases are cached).
-- `action: "list"` — list saved flows.
+- `action: "run"` — run an inline `define` (a one-off DAG) **or** a saved `name` (with optional `args`). Use `define` for an ad-hoc flow; use `name` to invoke something previously saved. Add `detach: true` to run in the background (returns immediately with the runId; poll the store for status).
+- `action: "save"` — persist `define` (scope `project` — default, committed/shared — or `user`); it becomes `/tf:<name>`. On a name collision, project overrides user.
+- `action: "resume"` — continue a paused/failed run by `runId`.
+- `action: "list"` — list saved flows. `action: "verify"` — static-check a `define` (zero tokens). `action: "agents"` — list available agents.
+
+## Background (detached) runs
+
+Add `detach: true` to `action: "run"` to spawn the flow in a detached child process. The tool returns immediately with the `runId`; the flow continues running even if the host session exits. Status is polled via the store (`/tf runs` or `action: "resume"`).
+
+- **Approval phases auto-reject** in detached mode (no interactive approver). Downstream phases see the rejection; the flow continues (fail-open).
+- **Crash resilience:** if the detached process crashes, the store persists `status: "failed"`; resume with `action: "resume"`.
+- **Same flow, both modes:** a flow can run foreground or background — `detach` is a dispatch-time decision, not a flow property.
+
+## 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).
+
+- **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).
+- **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).
 
 ## User commands
 

package/skills/taskflow/configuration.md

@@ -50,7 +50,7 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
 ```jsonc
 {
   "id": "audit",            // required, unique — referenced via {steps.audit.output}
-  "type": "map",            // agent | parallel | map | gate | reduce (default: agent)
+  "type": "map",            // agent | parallel | map | gate | reduce | approval | flow | loop | tournament (default: agent)
   "agent": "analyst",       // agent name to run this phase
   "task": "Audit {item.route}…",
   "dependsOn": ["discover"],// DAG edges
@@ -71,7 +71,7 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
 | Key | Applies to | Default | Notes |
 |-----|-----------|---------|-------|
 | `id` | all | — | **Required, unique.** Used in `{steps.<id>…}`. |
-| `type` | all | `agent` | One of the 5 phase types. |
+| `type` | all | `agent` | One of the 9 phase types (agent, parallel, map, gate, reduce, approval, flow, loop, tournament). |
 | `agent` | all | first available | Agent name; resolved from the scoped pool. |
 | `task` | agent, gate, map, reduce | — | Prompt; supports interpolation. Required for these types. |
 | `over` | map | — | **Required for map.** Must resolve to an array. |
@@ -85,8 +85,52 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
 | `tools` | all | agent default | Whitelist of tools for the subagent. See §5. |
 | `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. |
+| `context` | all | — | File paths / `{steps.X}` refs to **pre-read and inject** before the task. See §2.1. |
+| `contextLimit` | all | `8000` | Max characters read **per file** in `context`. See §2.1. |
+| `cache` | all | `run-only` | Per-phase cache policy (`scope`/`ttl`/`fingerprint`). See §11. |
 | `final` | all | last phase | Exactly one phase may be `final`; its output is returned. |
 
+> Gate-only control fields (`eval`, `onBlock`) and the loop/tournament control
+> fields (`until`/`maxIterations`/`convergence`, `variants`/`judge`/`judgeAgent`/`mode`)
+> are documented in `SKILL.md` next to their phase types.
+
+---
+
+## 2.1 Context pre-reading (`context` / `contextLimit`)
+
+Instead of making a subagent *discover* files by exploring (an O(N²) turn-cost
+spiral), you can **pre-read** known files and inject their contents ahead of the
+task prompt. List file paths and/or `{steps.X}` refs in `context`; the runtime
+resolves interpolated refs first, then reads each file and prepends labeled
+blocks to the task.
+
+```jsonc
+{
+  "id": "review",
+  "type": "agent",
+  "agent": "reviewer",
+  "context": ["src/auth.ts", "src/middleware.ts", "{steps.spec.output}"],
+  "contextLimit": 12000,
+  "task": "Review the auth flow against the spec above. VERDICT: PASS or BLOCK.",
+  "dependsOn": ["spec"]
+}
+```
+
+**Behavior & limits (all enforced in the runtime):**
+
+| Aspect | Rule |
+|--------|------|
+| Resolution order | interpolate `{steps.X}` / `{args.X}` refs **first**, then read file paths. |
+| Per-file cap | `contextLimit` characters per file (default **8000**); longer files are truncated with a marker. |
+| Total cap | the combined injected block is hard-capped at **200,000 chars**; overflow is truncated with a notice. |
+| Unreadable file | skipped with a `console.warn` (never aborts the phase). |
+| JSON-looking entry | a value that looks like a JSON blob (not a path) is diagnosed and skipped, not read as a file. |
+
+Use `context` for **known, bounded** inputs (a handful of source files, an
+upstream phase's output). For large/unknown exploration, let the agent use its
+`read`/`grep` tools instead — pre-reading hundreds of files just hits the total
+cap.
+
 ---
 
 ## 3. Declaring & passing arguments
@@ -209,7 +253,73 @@ Taskflow shares the subagent settings file at `~/.pi/agent/settings.json`:
 
 ---
 
-## 8. Environment variables
+## 8. Cross-run caching (`cache`)
+
+By default every phase is **`run-only`**: completed phases are reused only when
+you *resume the same run* (the historical behavior). Opt a phase into the
+persistent **cross-run** memoization store to reuse an identical-input result
+from *any prior run* — instant, zero tokens. See `docs/rfc-cross-run-memoization.md`
+for the design.
+
+```jsonc
+{
+  "id": "summarize-deps",
+  "type": "agent",
+  "agent": "writer",
+  "task": "Summarize the dependency tree of this repo.",
+  "cache": {
+    "scope": "cross-run",
+    "ttl": "6h",
+    "fingerprint": ["git:HEAD", "file:package-lock.json"]
+  }
+}
+```
+
+### `scope`
+
+| Value | Meaning |
+|-------|---------|
+| `run-only` (default) | Reuse only within a resumed run — exactly the historical behavior. |
+| `cross-run` | Reuse an identical-input result from **any** prior run (the persistent store). |
+| `off` | Never reuse, even within a run (force re-execution every time). |
+
+### `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.
+
+### `fingerprint` (cross-run only)
+
+The cache key is normally `phaseId + agent + model + interpolated-task`. A
+fingerprint folds **“did the world change?”** signals into that key, so an
+external change becomes a cache **miss** even when the task text is identical.
+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 **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 |
+
+### What is cached, and when
+
+- Only phases whose **`status` is `done`** and that **were not themselves a cache
+  hit** are written to the store (no re-storing a value just read).
+- The store is keyed by the full input hash + fingerprint, tagged with
+  `flowName`/`phaseId`/`runId`/`model` for inspection and LRU eviction.
+- Cross-run reuse is **safe by construction**: a different agent, model, task, or
+  fingerprint produces a different key, so stale results are never served.
+
+> **When to use it:** expensive, deterministic phases whose inputs rarely change
+> (dependency summaries, doc generation, repeated audits of the same tree). For
+> phases that *should* re-run every time (anything reading live external state
+> without a fingerprint), leave the default `run-only` or set `off`.
+
+---
+
+## 9. Environment variables
 
 | Variable | Effect |
 |----------|--------|
@@ -217,7 +327,7 @@ Taskflow shares the subagent settings file at `~/.pi/agent/settings.json`:
 
 ---
 
-## 9. Storage & file locations
+## 10. Storage & file locations
 
 | What | Path | Commit? |
 |------|------|---------|
@@ -233,7 +343,7 @@ Taskflow shares the subagent settings file at `~/.pi/agent/settings.json`:
 
 ---
 
-## 10. Quick recipes
+## 11. Quick recipes
 
 **Pin a strong model only for the review gate:**
 ```jsonc