pi-taskflow 0.0.19 → 0.0.20

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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

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.19",
+  "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

@@ -129,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"],
@@ -434,11 +435,19 @@ Quick reference:
 
 ## Actions
 
-- `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.
+- `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).