pi-taskflow 0.0.19 → 0.0.21

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.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
+- **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

@@ -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-601-6E8BFF?style=flat-square" alt="601 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>
@@ -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
 
@@ -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** · **601 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.
+- **601 tests across 25 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.
 - **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,11 +637,11 @@ 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):
 
-- **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/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

@@ -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/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

@@ -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/CI mode
+		// (safety: approval gates are never bypassed; the run records the rejection).
+		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 {
@@ -58,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 },
 );
@@ -81,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)",
@@ -110,6 +129,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 +190,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,
 					});
@@ -535,7 +591,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) {
@@ -614,6 +670,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;