pi-taskflow 0.0.21 → 0.0.22

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.22] — 2026-06-10
+
+> Dogfooding release. The `dogfood-full` self-audit taskflow (which itself
+> exercises all 9 phase types + when/join/retry/budget/cache/eval/flow-def/
+> loop/tournament/approval) ran against the codebase and surfaced these fixes.
+
+### Added
+- **Live auto-refresh for the `/tf runs` panel.** The run-history panel was a static snapshot taken when opened, so a background (detached) run's progress never updated while watching. It now polls run state on a 1s interval and re-renders only when a run's status/`updatedAt` actually changes — phase progress (including `map`/`parallel` `subProgress` like `24/24`) updates live. The user's selection follows the same `runId` across refreshes, a green `● live` tag shows while any run is running, and the refresh timer is cleared on close (`dispose()`) and `unref`'d so it never keeps the event loop alive. Fully backward-compatible: without live hooks the panel renders statically as before.
+  - 5 new tests (`test/runs-view.test.ts`): refresh-on-change, no-render-when-unchanged, dispose-stops-timer, selection-follows-runId, back-compat-no-hooks.
+
+### Fixed
+- **`safeParse` now prefers a `json`-tagged fence in multi-fence output.** When an LLM phase emitted an evidence block (e.g. ```` ```typescript ````) *before* the ```` ```json ```` payload, the old single-match regex grabbed the first fence, failed to parse, and the balanced-bracket fallback was misled by braces in the prose — `safeParse` returned `undefined` and any downstream `map` phase failed with `'over' did not resolve to an array`. It now scans every fenced block and tries `json`-tagged ones first, then untagged. (3 new multi-fence tests.)
+- **Unresolved interpolation refs are surfaced as phase warnings.** `interpolate()` returns `missing[]` (placeholders with no source), but the runtime discarded it on the main task path — so `{args.typo}` or a `{steps.x.output}` without `dependsOn` was silently left intact in the dispatched task. The `interpolate.ts` doc comment promised "a recorded warning" that no code produced. The runtime now logs `[taskflow] phase X: unresolved refs ...` and attaches the message to `PhaseState.warnings` (persisted in the run record, visible in `/tf runs`). Doc comment corrected to match.
+
 ## [0.0.21] — 2026-06-10
 
 ### Added

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-601-6E8BFF?style=flat-square" alt="601 tests"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-608-6E8BFF?style=flat-square" alt="608 tests"></a>
   <a href="#whats-inside"><img src="https://img.shields.io/badge/dogfooded-%E2%9C%93-43D9AD?style=flat-square" alt="dogfooded"></a>
   <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-B692FF?style=flat-square" alt="for the Pi coding agent"></a>
 </p>
@@ -608,12 +608,12 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 
 <div align="center">
 
-**0 runtime dependencies** · **601 tests** · **9 phase types** · **cross-session resume** · **cross-run memoization** · **~7.7k LOC runtime**
+**0 runtime dependencies** · **608 tests** · **9 phase types** · **cross-session resume** · **cross-run memoization** · **~7.7k LOC runtime**
 
 </div>
 
 - **Zero runtime dependencies.** No `dependencies` field — the runtime is built entirely on Node built-ins (`fs` / `path` / `os` / `child_process` / `crypto`). The file lock is `fs.openSync("wx")`, not a third-party library.
-- **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.
+- **608 tests across 26 test files** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, cross-run cache freshness (flow/thinking/tools key isolation, fingerprint invalidation, TTL/LRU eviction), gate verdicts, budget caps, retry/backoff, approval flows, loop termination, tournament judging, sub-flow composition, live run-history refresh, callback isolation, the idle watchdog, model-role init config, and parseModelFromLabel with parenthesized-model-name regression.
 - **Hardened by design.** Path-traversal defense (lexical + `realpath`), runId validation, HTML/error sanitization, atomic writes, stale-lock stealing via `rename`, and an idle watchdog that kills wedged subagents.
 - **Dogfooded.** Every new feature has to survive the project's own `self-improve` taskflow before it ships.
 

package/extensions/approval-view.ts

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

package/extensions/index.ts

@@ -206,7 +206,6 @@ async function runFlow(
 							},
 							done,
 							() => tui.terminal.rows,
-							tui.terminal,
 						);
 						const onAbort = () => done("reject");
 						signal?.addEventListener("abort", onAbort, { once: true });
@@ -799,8 +798,13 @@ export default function (pi: ExtensionAPI) {
 					);
 					return;
 				}
-				const result = await ctx.ui.custom<RunHistoryResult | undefined>((_tui, theme, _kb, done) => {
-					return new RunHistoryComponent(runs, theme, (r) => done(r));
+				const result = await ctx.ui.custom<RunHistoryResult | undefined>((tui, theme, _kb, done) => {
+					const comp = new RunHistoryComponent(runs, theme, (r) => done(r), {
+						refresh: () => listRuns(ctx.cwd, 50),
+						requestRender: () => tui.requestRender(),
+						intervalMs: 1000,
+					});
+					return comp;
 				});
 				if (result?.action === "resume") {
 					if (ctx.isIdle()) {

package/extensions/interpolate.ts

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

package/extensions/runs-view.ts

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

package/extensions/runtime.ts

@@ -87,8 +87,7 @@ function buildInterpolationContext(
 	return { args: state.args, steps, previousOutput, locals };
 }
 
-function resultToPhaseState(id: string, r: RunResult, inputHash: string, parseJson: boolean): PhaseState {
-	const failed = isFailed(r);
+function resultToPhaseState(id: string, r: RunResult, inputHash: string, parseJson: boolean): PhaseState {	const failed = isFailed(r);
 	const attempts = attemptsOf(r);
 	// For failed phases, embed the error info in the output so downstream
 	// phases (and the user) can see what went wrong. The raw r.output is
@@ -110,6 +109,22 @@ function resultToPhaseState(id: string, r: RunResult, inputHash: string, parseJs
 	};
 }
 
+/**
+ * Surface unresolved interpolation placeholders (the `missing[]` from
+ * `interpolate()`). Without this they are silently left intact in the task —
+ * the doc comment in interpolate.ts promises "a recorded warning". We both
+ * log to the console and return a string to attach to PhaseState.warnings so
+ * the warning is persisted in the run record and visible in `/tf runs`.
+ * Returns undefined when nothing is missing.
+ */
+function warnUnresolvedRefs(phaseId: string, missing: string[]): string | undefined {
+	if (!missing.length) return undefined;
+	const unique = Array.from(new Set(missing));
+	const msg = `unresolved refs in task: ${unique.map((m) => `{${m}}`).join(", ")} — left intact (check dependsOn / placeholder spelling)`;
+	console.warn(`[taskflow] phase '${phaseId}': ${msg}`);
+	return msg;
+}
+
 /** Attempts recorded by the retry wrapper (defaults to 1). */
 function attemptsOf(r: RunResult): number {
 	const a = r.attempts;
@@ -582,7 +597,9 @@ async function executePhase(
 				return ps;
 			}
 		}
-		const { text } = interpolate(phase.task ?? "", ctx);
+		const interp = interpolate(phase.task ?? "", ctx);
+		const text = interp.text;
+		const refWarning = warnUnresolvedRefs(phase.id, interp.missing);
 		const fullTask = preRead + text;
 		const agentName = resolveAgent(phase.agent, deps, state);
 		const inputHash = cacheKey(cc, [phase.id, agentName, phase.model ?? "", fullTask]);
@@ -591,6 +608,7 @@ async function executePhase(
 
 		const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress));
 		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
+		if (refWarning) ps.warnings = [...(ps.warnings ?? []), refWarning];
 		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
 
 		// onBlock:retry — re-execute upstream + gate until pass or max attempts.

package/package.json

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