pi-taskflow 0.0.12 → 0.0.13

package/extensions/runtime.ts

@@ -13,11 +13,12 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
 import type { AgentConfig } from "./agents.ts";
-import { coerceArray, evaluateCondition, interpolate, type InterpolationContext, safeParse } from "./interpolate.ts";
+import { coerceArray, evaluateCondition, interpolate, type InterpolationContext, safeParse, tryEvaluateCondition } from "./interpolate.ts";
 import { isFailed, isTransientError, type LiveUpdate, mapWithConcurrencyLimit, runAgentTask, type RunResult } from "./runner.ts";
 import { aggregateUsage, emptyUsage, type UsageStats } from "./usage.ts";
-import { type Budget, dependenciesOf, finalPhase, type Phase, resolveArgs, type Taskflow, topoLayers } from "./schema.ts";
+import { type Budget, type CacheScope, dependenciesOf, finalPhase, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, parseTtlMs, type Phase, resolveArgs, type Taskflow, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, type TournamentMode } from "./schema.ts";
 import { hashInput, newRunId, type PhaseState, type RunState } from "./store.ts";
+import { CacheStore, resolveFingerprint } from "./cache.ts";
 
 /** A human-in-the-loop approval request raised by an `approval` phase. */
 export interface ApprovalRequest {
@@ -49,6 +50,8 @@ export interface RuntimeDeps {
 	requestApproval?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
 	/** Resolve a saved taskflow by name for `flow` (sub-workflow) phases. */
 	loadFlow?: (name: string) => Taskflow | undefined;
+	/** Cross-run memoization store. Omit to construct a default one for `deps.cwd`. */
+	cacheStore?: CacheStore;
 	/** Internal: sub-flow call stack, for recursion detection. */
 	_stack?: string[];
 }
@@ -295,6 +298,23 @@ async function executePhase(
 	const ctx = buildInterpolationContext(state, previousOutput);
 	const preRead = await resolvePhaseContext(phase, ctx);
 
+	// Resolve this phase's cache policy once. Default scope is "run-only" (the
+	// historical within-run resume behavior). Only "cross-run" phases resolve a
+	// fingerprint and consult the persistent store.
+	const cacheScope: CacheScope = (phase.cache?.scope ?? "run-only") as CacheScope;
+	const cc: PhaseCacheCtx = {
+		scope: cacheScope,
+		ttlMs: phase.cache?.ttl ? (parseTtlMs(phase.cache.ttl) ?? undefined) : undefined,
+		fingerprint: cacheScope === "cross-run" ? resolveFingerprint(phase.cache?.fingerprint, phase.cwd ?? deps.cwd) : "",
+		store: deps.cacheStore ?? new CacheStore(deps.cwd),
+		prior,
+		phaseId: phase.id,
+		flowName: state.flowName,
+		runId: state.runId,
+		thinking: phase.thinking,
+		tools: phase.tools,
+	};
+
 	const baseRun = (agentName: string, task: string, onLive?: (l: LiveUpdate) => void) =>
 		run(
 			deps.cwd,
@@ -437,13 +457,14 @@ async function executePhase(
 		const { text } = interpolate(phase.task ?? "", ctx);
 		const fullTask = preRead + text;
 		const agentName = resolveAgent(phase.agent, deps, state);
-		const inputHash = hashInput(phase.id, agentName, phase.model ?? "", fullTask);
-		const cached = cachedPhase(prior, inputHash);
+		const inputHash = cacheKey(cc, [phase.id, agentName, phase.model ?? "", fullTask]);
+		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
 		const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress));
 		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
 		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
+		recordCache(cc, ps);
 		return ps;
 	}
 
@@ -455,12 +476,14 @@ async function executePhase(
 				task: preRead + r.text,
 			};
 		});
-		const inputHash = hashInput(phase.id, phase.model ?? "", JSON.stringify(branches));
-		const cached = cachedPhase(prior, inputHash);
+		const inputHash = cacheKey(cc, [phase.id, phase.model ?? "", JSON.stringify(branches)]);
+		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
 		const results = await runFanout(branches);
-		return mergePhaseState(phase.id, results, inputHash, parseJson);
+		const ps = mergePhaseState(phase.id, results, inputHash, parseJson);
+		recordCache(cc, ps);
+		return ps;
 	}
 
 	if (type === "map") {
@@ -485,19 +508,21 @@ async function executePhase(
 				task: preRead + interpolate(phase.task ?? "", localCtx).text,
 			};
 		});
-		const inputHash = hashInput(phase.id, phase.model ?? "", JSON.stringify(tasks));
-		const cached = cachedPhase(prior, inputHash);
+		const inputHash = cacheKey(cc, [phase.id, phase.model ?? "", JSON.stringify(tasks)]);
+		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
 		const results = await runFanout(tasks);
-		return mergePhaseState(phase.id, results, inputHash, parseJson);
+		const ps = mergePhaseState(phase.id, results, inputHash, parseJson);
+		recordCache(cc, ps);
+		return ps;
 	}
 
 	if (type === "approval") {
 		const ctx = buildInterpolationContext(state, previousOutput);
 		const message = interpolate(phase.task ?? "Approve to continue?", ctx).text;
 		const inputHash = hashInput(phase.id, phase.model ?? "", "approval", message);
-		const cached = cachedPhase(prior, inputHash);
+		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
 		// Non-interactive (headless/CI/tests): auto-approve, fail-open, but record it.
@@ -547,8 +572,8 @@ async function executePhase(
 			provided[k] = typeof v === "string" ? interpolate(v, ctx).text : v;
 		}
 		const subArgs = resolveArgs(subDef, provided);
-		const inputHash = hashInput(phase.id, `flow:${name}`, preRead, JSON.stringify(subArgs));
-		const cached = cachedPhase(prior, inputHash);
+		const inputHash = cacheKey(cc, [phase.id, `flow:${name}`, preRead, JSON.stringify(subArgs)]);
+		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
 		const live = state.phases[phase.id];
@@ -600,7 +625,7 @@ async function executePhase(
 			},
 		});
 		const sp = Object.values(subState.phases);
-		return {
+		const flowPs: PhaseState = {
 			id: phase.id,
 			status: subResult.ok ? "done" : "failed",
 			output: subResult.finalOutput,
@@ -619,6 +644,207 @@ async function executePhase(
 			inputHash,
 			endedAt: Date.now(),
 		};
+		recordCache(cc, flowPs);
+		return flowPs;
+	}
+
+	// loop-until-done: run the body repeatedly until `until` is truthy, the output
+	// converges to a fixed point, or maxIterations is hit (always terminates).
+	if (type === "loop") {
+		const agentName = resolveAgent(phase.agent, deps, state);
+		const rawMax = phase.maxIterations ?? LOOP_DEFAULT_MAX_ITERATIONS;
+		const maxIters = Math.max(1, Math.min(LOOP_HARD_MAX_ITERATIONS, Math.floor(rawMax)));
+		const convergence = phase.convergence ?? true;
+
+		const usages: UsageStats[] = [];
+		const loopWarnings: string[] = [];
+		let lastOutput = "";
+		let prevOutput: string | undefined;
+		let iterations = 0;
+		let stop: NonNullable<PhaseState["loop"]>["stop"] = "maxIterations";
+		let failedResult: RunResult | undefined;
+
+		for (let i = 1; i <= maxIters; i++) {
+			if (deps.signal?.aborted) {
+				stop = "failed";
+				break;
+			}
+			iterations = i;
+			// The body sees its iteration number and the prior iteration's output.
+			const bodyCtx = buildInterpolationContext(state, previousOutput, {
+				loop: { iteration: i, lastOutput, maxIterations: maxIters },
+			});
+			const body = preRead + interpolate(phase.task ?? "", bodyCtx).text;
+			const r = await runOne(agentName, body, liveSink(state, phase.id, emitProgress));
+			usages.push(r.usage);
+			if (isFailed(r)) {
+				failedResult = r;
+				stop = "failed";
+				break;
+			}
+			prevOutput = lastOutput;
+			lastOutput = r.output;
+
+			// Expose this iteration's output as {steps.<thisId>.output|json} so the
+			// `until` condition can inspect it (e.g. "{steps.refine.json.done}==true").
+			// Loop locals ({loop.iteration} etc.) are available to the condition too.
+			const untilCtx = buildInterpolationContext(state, previousOutput, {
+				loop: { iteration: i, lastOutput, maxIterations: maxIters },
+			});
+			untilCtx.steps[phase.id] = { output: lastOutput, json: safeParse(lastOutput) };
+			const { value: done, error: condErr } = tryEvaluateCondition(phase.until ?? "", untilCtx);
+			// A malformed condition must not spin forever: stop and surface a warning
+			// so the author learns the `until` never actually evaluated.
+			if (condErr) {
+				loopWarnings.push(`loop 'until' could not be evaluated (stopped early): ${condErr}`);
+				stop = "until";
+				break;
+			}
+			if (done) {
+				stop = "until";
+				break;
+			}
+			// Fixed-point convergence: identical consecutive output ⇒ further work is wasted.
+			if (convergence && prevOutput !== undefined && prevOutput === lastOutput) {
+				stop = "converged";
+				break;
+			}
+		}
+
+		const aggUsage = usages.length ? aggregateUsage(usages) : emptyUsage();
+		if (failedResult) {
+			return {
+				id: phase.id,
+				status: "failed",
+				output: lastOutput || undefined,
+				usage: aggUsage,
+				error: failedResult.errorMessage || failedResult.stderr || `loop '${phase.id}' iteration ${iterations} failed`,
+				loop: { iterations, stop: "failed" },
+				warnings: loopWarnings.length ? loopWarnings : undefined,
+				inputHash: hashInput(phase.id, "loop", phase.until ?? ""),
+				endedAt: Date.now(),
+			};
+		}
+		return {
+			id: phase.id,
+			status: "done",
+			output: lastOutput,
+			json: parseJson ? safeParse(lastOutput) : undefined,
+			usage: aggUsage,
+			loop: { iterations, stop },
+			warnings: loopWarnings.length ? loopWarnings : undefined,
+			inputHash: hashInput(phase.id, "loop", phase.until ?? "", String(iterations)),
+			endedAt: Date.now(),
+		};
+	}
+
+	// tournament: spawn N competing variants, then a judge picks the best (or
+	// synthesizes an aggregate). Combines the parallel fan-out with a gate-style
+	// verdict, expressed as a single declarative phase.
+	if (type === "tournament") {
+		const mode = (phase.mode ?? "best") as TournamentMode;
+		// Competitors: explicit `branches` win; otherwise N copies of `task`.
+		let competitors: Array<{ agent: string; task: string }>;
+		if (phase.branches && phase.branches.length > 0) {
+			competitors = phase.branches.map((b) => ({
+				agent: resolveAgent(b.agent ?? phase.agent, deps, state),
+				task: preRead + interpolate(b.task, ctx).text,
+			}));
+		} else {
+			const n = Math.max(2, Math.min(TOURNAMENT_HARD_MAX_VARIANTS, Math.floor(phase.variants ?? TOURNAMENT_DEFAULT_VARIANTS)));
+			const body = preRead + interpolate(phase.task ?? "", ctx).text;
+			competitors = Array.from({ length: n }, () => ({ agent: resolveAgent(phase.agent, deps, state), task: body }));
+		}
+
+		const results = await runFanout(competitors);
+		const ran = results.filter((r) => r.stopReason !== "budget-skipped");
+		const ok = ran.filter((r) => !isFailed(r));
+		const variantUsage = aggregateUsage(results.map((r) => r.usage));
+		// Winner numbers are 1-based over `ran` (exactly what the judge is shown).
+		// 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;
+
+		// All competitors failed → the tournament fails (nothing to judge).
+		if (ok.length === 0) {
+			return {
+				id: phase.id,
+				status: "failed",
+				usage: variantUsage,
+				error: `tournament '${phase.id}': all ${competitors.length} variants failed`,
+				tournament: { variants: competitors.length, winner: 0, mode },
+				inputHash: hashInput(phase.id, "tournament", String(competitors.length)),
+				endedAt: Date.now(),
+			};
+		}
+		// Only one competitor survived → no contest; it wins by default (skip judge).
+		if (ok.length === 1) {
+			return {
+				id: phase.id,
+				status: "done",
+				output: ok[0].output,
+				json: parseJson ? safeParse(ok[0].output) : undefined,
+				usage: variantUsage,
+				model: ok[0].model,
+				tournament: { variants: competitors.length, winner: ranIdx(ok[0]), mode, reason: "only surviving variant" },
+				inputHash: hashInput(phase.id, "tournament", String(competitors.length)),
+				endedAt: Date.now(),
+			};
+		}
+
+		// Build the judge prompt: label every variant output, then the rubric.
+		const labelled = ran
+			.map((r, i) => `### Variant ${i + 1}${isFailed(r) ? " (failed — ineligible)" : ""}\n\n${r.output}`)
+			.join("\n\n---\n\n");
+		const rubric =
+			interpolate(phase.judge ?? "", ctx).text.trim() ||
+			"You are judging competing answers to the same task. Pick the single best variant on correctness, completeness, and clarity.";
+		const directive =
+			mode === "best"
+				? `End your reply with a line exactly: WINNER: <number> (1–${ran.length}), choosing the strongest eligible variant.`
+				: `Synthesize the strongest possible answer by combining the best parts of the eligible variants. Then end with a line: WINNER: <number> indicating which variant contributed most.`;
+		const judgeTask = `${rubric}\n\nThe candidate variants:\n\n${labelled}\n\n${directive}`;
+		const judgeAgent = resolveAgent(phase.judgeAgent ?? phase.agent, deps, state);
+		const judgeRes = await runOne(judgeAgent, judgeTask, liveSink(state, phase.id, emitProgress));
+		const judgeUsage = aggregateUsage([variantUsage, judgeRes.usage]);
+
+		if (isFailed(judgeRes)) {
+			// Judge failed: fall back to the first eligible variant (fail-open, never
+			// lose the work). Report the variant we actually used, not a hardcoded 1.
+			return {
+				id: phase.id,
+				status: "done",
+				output: ok[0].output,
+				json: parseJson ? safeParse(ok[0].output) : undefined,
+				usage: judgeUsage,
+				model: ok[0].model,
+				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)),
+				endedAt: Date.now(),
+			};
+		}
+
+		const { winner, reason } = parseTournamentWinner(judgeRes.output, ran.length);
+		const winnerResult = ran[winner - 1];
+		const winnerIneligible = !winnerResult || isFailed(winnerResult);
+		// In 'best' mode the output is the winning variant verbatim; in 'aggregate'
+		// mode it is the judge's synthesized answer.
+		const chosen = winnerIneligible ? ok[0] : winnerResult;
+		const winnerIdx = ranIdx(chosen);
+		const output = mode === "aggregate" ? judgeRes.output : chosen.output;
+		return {
+			id: phase.id,
+			status: "done",
+			output,
+			json: parseJson ? safeParse(output) : undefined,
+			usage: judgeUsage,
+			model: mode === "aggregate" ? judgeRes.model : chosen.model,
+			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),
+			endedAt: Date.now(),
+		};
 	}
 
 	return {
@@ -657,13 +883,89 @@ function lastCompletedOutput(state: RunState, phase: Phase): string | undefined
 	return undefined;
 }
 
-function cachedPhase(prior: PhaseState | undefined, inputHash: string): PhaseState | null {
-	if (prior && prior.status === "done" && prior.inputHash === inputHash) {
-		return { ...prior, status: "done" };
+/**
+ * Per-phase cache policy resolved once at the top of executePhase. Carries the
+ * scope, optional TTL, and a pre-resolved fingerprint string so each phase-type
+ * branch can fold it into its inputHash and consult the cross-run store uniformly.
+ */
+interface PhaseCacheCtx {
+	scope: CacheScope;
+	ttlMs?: number;
+	fingerprint: string;
+	store: CacheStore;
+	prior: PhaseState | undefined;
+	phaseId: string;
+	flowName: string;
+	runId: string;
+	/** Per-phase execution config that materially affects subagent output and
+	 *  therefore must be part of the cache identity (else a config change could
+	 *  silently serve a stale cross-run hit). */
+	thinking?: string;
+	tools?: string[];
+}
+
+/** Fold the phase fingerprint into the base hash parts to form the final cache key. */
+function cacheKey(cc: PhaseCacheCtx, baseParts: string[]): string {
+	// Fold the full cache identity into the hash: flow name (prevents collisions
+	// across different flows that share a phase.id + task + model), the per-phase
+	// thinking/tools config (changing either changes the subagent's output), and
+	// the resolved world-state fingerprint.
+	const parts = [`flow:${cc.flowName}`, ...baseParts, `think:${cc.thinking ?? ""}`, `tools:${JSON.stringify(cc.tools ?? [])}`];
+	return cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
+}
+
+/**
+ * Resume/memoization lookup. Honors scope:
+ *   - "off":      never reuse (even within-run).
+ *   - "run-only": within-run resume only (historical behavior).
+ *   - "cross-run": within-run first, then the persistent cross-run store.
+ * On a cross-run hit, usage is zeroed and `cacheHit` records the source.
+ */
+function cachedPhase(cc: PhaseCacheCtx, inputHash: string): PhaseState | null {
+	if (cc.scope === "off") return null;
+
+	// 1. within-run resume (fastest; always allowed unless scope is off)
+	if (cc.prior && cc.prior.status === "done" && cc.prior.inputHash === inputHash) {
+		return { ...cc.prior, status: "done" };
+	}
+
+	// 2. cross-run memoization (opt-in)
+	if (cc.scope === "cross-run") {
+		const e = cc.store.get(inputHash, cc.ttlMs);
+		if (e) {
+			return {
+				id: cc.phaseId,
+				status: "done",
+				inputHash,
+				output: e.output,
+				json: e.json,
+				model: e.model,
+				usage: emptyUsage(),
+				cacheHit: "cross-run",
+				endedAt: Date.now(),
+			};
+		}
 	}
 	return null;
 }
 
+/** Persist a freshly-computed phase result to the cross-run store (best-effort). */
+function recordCache(cc: PhaseCacheCtx, ps: PhaseState): void {
+	if (cc.scope !== "cross-run") return;
+	if (ps.status !== "done" || !ps.inputHash) return;
+	if (ps.cacheHit) return; // don't re-store a value we just read from cache
+	cc.store.put({
+		key: ps.inputHash,
+		createdAt: Date.now(),
+		output: ps.output,
+		json: ps.json,
+		model: ps.model,
+		flowName: cc.flowName,
+		phaseId: cc.phaseId,
+		runId: cc.runId,
+	});
+}
+
 /**
  * Resolve an agent name against available agents. Falls back to the default
  * agent if the requested agent isn't found, logging a warning via safeEmit.
@@ -722,6 +1024,29 @@ function asReason(v: unknown): string | undefined {
 	return typeof v === "string" && v.trim() ? v.trim() : undefined;
 }
 
+/**
+ * Parse a judge's pick of the winning variant. Accepts JSON ({"winner":n} or
+ * {"best":n}) or a `WINNER: n` line (last match wins). Clamps to [1, count].
+ * Fail-open: an unreadable verdict defaults to variant 1 so the work is never
+ * lost. Returns the 1-based index plus an optional reason.
+ */
+export function parseTournamentWinner(output: string, count: number): { winner: number; reason?: string } {
+	const clamp = (n: number) => Math.min(Math.max(1, Math.floor(n)), Math.max(1, count));
+	const json = safeParse(output);
+	if (json && typeof json === "object") {
+		const o = json as Record<string, unknown>;
+		const raw = o.winner ?? o.best ?? o.choice;
+		const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
+		if (Number.isFinite(n)) return { winner: clamp(n), reason: asReason(o.reason) };
+	}
+	const matches = [...output.matchAll(/WINNER\s*[:=]\s*#?\s*(\d+)/gi)];
+	if (matches.length) {
+		const n = Number(matches[matches.length - 1][1]);
+		if (Number.isFinite(n)) return { winner: clamp(n) };
+	}
+	return { winner: 1, reason: "no parseable winner; defaulted to variant 1" };
+}
+
 /**
  * Best-effort invocation of the user-provided `persist` + `onProgress` callbacks.
  *

package/extensions/schema.ts

@@ -13,11 +13,27 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow"] as const;
+export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament"] as const;
 export type PhaseType = (typeof PHASE_TYPES)[number];
 
+/** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
+export const LOOP_DEFAULT_MAX_ITERATIONS = 10;
+export const LOOP_HARD_MAX_ITERATIONS = 100;
+
+/** Tournament competitor bounds. */
+export const TOURNAMENT_DEFAULT_VARIANTS = 3;
+export const TOURNAMENT_HARD_MAX_VARIANTS = 20;
+export const TOURNAMENT_MODES = ["best", "aggregate"] as const;
+export type TournamentMode = (typeof TOURNAMENT_MODES)[number];
+
 export const OUTPUT_FORMATS = ["text", "json"] as const;
 export const JOIN_MODES = ["all", "any"] as const;
+export const CACHE_SCOPES = ["run-only", "cross-run", "off"] as const;
+export type CacheScope = (typeof CACHE_SCOPES)[number];
+/** Allowed fingerprint entry prefixes. `glob!:` = content-hash variant of `glob:`. */
+export const CACHE_FINGERPRINT_PREFIXES = ["git:", "glob:", "glob!:", "file:", "env:"] as const;
+/** Phase types that must NOT be cached across runs (a fresh result is required each run). */
+export const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -39,6 +55,36 @@ const RetrySchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/**
+ * Per-phase cache policy. Defaults to `run-only` which is exactly the historical
+ * behavior (within-run resume only). `cross-run` opts a phase into the persistent
+ * cross-run memoization store; see docs/rfc-cross-run-memoization.md.
+ */
+const CacheSchema = Type.Object(
+	{
+		scope: Type.Optional(
+			StringEnum(CACHE_SCOPES, {
+				description:
+					"Cache reuse scope. 'run-only' (default) = within-run resume only (historical behavior); 'cross-run' = reuse identical-input results from any prior run; 'off' = never reuse (even within-run).",
+				default: "run-only",
+			}),
+		),
+		ttl: Type.Optional(
+			Type.String({
+				description:
+					"Max cache age before a cross-run hit is treated as a miss, e.g. '30m', '6h', '7d'. Omit for no time bound.",
+			}),
+		),
+		fingerprint: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"Extra freshness inputs folded into the cache key so 'the world changed' becomes a cache miss. Each entry: 'git:HEAD' | 'glob:<pattern>' | 'glob!:<pattern>' (content-hash) | 'file:<path>' | 'env:<NAME>'.",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 /** Run-wide cost / token ceiling. Exceeding it halts the run (remaining phases skipped). */
 const BudgetSchema = Type.Object(
 	{
@@ -79,6 +125,51 @@ const PhaseSchema = Type.Object(
 			}),
 		),
 
+		// loop-until-done
+		until: Type.Optional(
+			Type.String({
+				description:
+					"[loop] Stop condition evaluated after each iteration. The iteration's output is exposed as {steps.<thisId>.output}/.json. Supports the same operators as `when`. The loop stops when this is truthy, on convergence, or at maxIterations. A parse error stops the loop (fail-safe).",
+			}),
+		),
+		maxIterations: Type.Optional(
+			Type.Number({
+				description: `[loop] Hard cap on iterations (default ${LOOP_DEFAULT_MAX_ITERATIONS}, max ${LOOP_HARD_MAX_ITERATIONS}). The loop always terminates within this bound even if 'until' never becomes truthy.`,
+				default: LOOP_DEFAULT_MAX_ITERATIONS,
+			}),
+		),
+		convergence: Type.Optional(
+			Type.Boolean({
+				description:
+					"[loop] When true (default), stop early if an iteration's output is identical to the previous one (a fixed point — further iterations would not change anything).",
+				default: true,
+			}),
+		),
+
+		// tournament: N variants compete, a judge picks the best (or aggregates)
+		variants: Type.Optional(
+			Type.Number({
+				description: `[tournament] Number of competing variants to spawn from 'task' (default ${TOURNAMENT_DEFAULT_VARIANTS}, max ${TOURNAMENT_HARD_MAX_VARIANTS}). Ignored when 'branches' is provided (those become the variants instead).`,
+				default: TOURNAMENT_DEFAULT_VARIANTS,
+			}),
+		),
+		judge: Type.Optional(
+			Type.String({
+				description:
+					"[tournament] Judge prompt. The numbered variant outputs are injected before it. To pick a winner, end with a line like 'WINNER: <n>' or return JSON {\"winner\": <n>}. Defaults to a sensible built-in rubric.",
+			}),
+		),
+		judgeAgent: Type.Optional(
+			Type.String({ description: "[tournament] Agent that runs the judge step (defaults to the phase 'agent')." }),
+		),
+		mode: Type.Optional(
+			StringEnum(TOURNAMENT_MODES, {
+				description:
+					"[tournament] 'best' (default): output is the winning variant verbatim. 'aggregate': output is the judge's synthesized answer combining the variants.",
+				default: "best",
+			}),
+		),
+
 		dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Phase ids this phase depends on" })),
 		join: Type.Optional(
 			StringEnum(JOIN_MODES, {
@@ -115,6 +206,7 @@ const PhaseSchema = Type.Object(
 				default: 8000,
 			}),
 		),
+		cache: Type.Optional(CacheSchema),
 	},
 	{ additionalProperties: false },
 );
@@ -157,6 +249,7 @@ export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
 export type RetryPolicy = Static<typeof RetrySchema>;
 export type Budget = Static<typeof BudgetSchema>;
+export type CachePolicy = Static<typeof CacheSchema>;
 export type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
@@ -260,6 +353,21 @@ export interface ValidationResult {
 	warnings: string[];
 }
 
+/**
+ * Parse a TTL string like '30m', '6h', '7d', '500ms', '90s' into milliseconds.
+ * Returns null for malformed or non-positive values. Plain integers = ms.
+ */
+export function parseTtlMs(ttl: string): number | null {
+	if (typeof ttl !== "string") return null;
+	const m = ttl.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/i);
+	if (!m) return null;
+	const n = Number(m[1]);
+	if (!Number.isFinite(n) || n <= 0) return null;
+	const unit = (m[2] ?? "ms").toLowerCase();
+	const mult: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+	return n * mult[unit];
+}
+
 export interface ValidationOptions {
 	/** Resolved invocation args, used for runtime checks like missing `{args.X}`. */
 	args?: Record<string, unknown>;
@@ -320,6 +428,36 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 		if (type === "flow") {
 			if (!p.use) errors.push(`Phase '${p.id}' (flow) requires 'use' (a saved flow name)`);
 		}
+		if (type === "loop") {
+			if (!p.task) errors.push(`Phase '${p.id}' (loop) requires 'task' (the iteration body)`);
+			if (!p.until) errors.push(`Phase '${p.id}' (loop) requires 'until' (the stop condition)`);
+			if (p.maxIterations !== undefined) {
+				if (typeof p.maxIterations !== "number" || !Number.isFinite(p.maxIterations) || p.maxIterations < 1) {
+					errors.push(`Phase '${p.id}' (loop): maxIterations must be a number >= 1`);
+				} else if (p.maxIterations > LOOP_HARD_MAX_ITERATIONS) {
+					errors.push(`Phase '${p.id}' (loop): maxIterations must be <= ${LOOP_HARD_MAX_ITERATIONS}`);
+				}
+			}
+		}
+		if (type === "tournament") {
+			const hasBranches = Array.isArray(p.branches) && p.branches.length > 0;
+			if (!hasBranches && !p.task) {
+				errors.push(`Phase '${p.id}' (tournament) requires 'task' (the competitor prompt) or non-empty 'branches'`);
+			}
+			if (p.variants !== undefined) {
+				if (typeof p.variants !== "number" || !Number.isFinite(p.variants) || p.variants < 2) {
+					errors.push(`Phase '${p.id}' (tournament): variants must be a number >= 2`);
+				} else if (p.variants > TOURNAMENT_HARD_MAX_VARIANTS) {
+					errors.push(`Phase '${p.id}' (tournament): variants must be <= ${TOURNAMENT_HARD_MAX_VARIANTS}`);
+				}
+			}
+			if (hasBranches && p.branches!.length < 2) {
+				errors.push(`Phase '${p.id}' (tournament): 'branches' needs at least 2 competitors`);
+			}
+			if (p.mode && !TOURNAMENT_MODES.includes(p.mode as TournamentMode)) {
+				errors.push(`Phase '${p.id}' (tournament): unknown mode '${p.mode}'`);
+			}
+		}
 		if (p.retry) {
 			if (typeof p.retry.max !== "number" || p.retry.max < 0) {
 				errors.push(`Phase '${p.id}': retry.max must be a number >= 0`);
@@ -337,6 +475,33 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 			errors.push(`Phase '${p.id}': unknown join mode '${p.join}'`);
 		}
 
+		// Cache policy validation (cross-run memoization).
+		if (p.cache) {
+			const scope = p.cache.scope ?? "run-only";
+			if (!CACHE_SCOPES.includes(scope as CacheScope)) {
+				errors.push(`Phase '${p.id}': unknown cache.scope '${scope}' (expected one of ${CACHE_SCOPES.join(", ")})`);
+			}
+			// Gate B: gate/approval phases must produce a fresh result every run.
+			if (scope === "cross-run" && (CACHE_CROSS_RUN_BLOCKED_TYPES as readonly string[]).includes(type)) {
+				errors.push(
+					`Phase '${p.id}' (${type}): cache.scope 'cross-run' is not allowed for ${CACHE_CROSS_RUN_BLOCKED_TYPES.join("/")} phases — they must produce a fresh result each run. Use 'run-only'.`,
+				);
+			}
+			// Gate C: every fingerprint entry must use a known prefix (fail closed).
+			for (const fp of p.cache.fingerprint ?? []) {
+				const ok = CACHE_FINGERPRINT_PREFIXES.some((pre) => fp.startsWith(pre) && fp.length > pre.length);
+				if (!ok) {
+					errors.push(
+						`Phase '${p.id}': invalid cache.fingerprint entry '${fp}' (expected '<prefix><value>' with prefix one of ${CACHE_FINGERPRINT_PREFIXES.join(", ")})`,
+					);
+				}
+			}
+			// Gate D: TTL must parse to a positive duration when present.
+			if (p.cache.ttl !== undefined && parseTtlMs(p.cache.ttl) === null) {
+				errors.push(`Phase '${p.id}': invalid cache.ttl '${p.cache.ttl}' (expected e.g. '30m', '6h', '7d')`);
+			}
+		}
+
 		// Agent name convention: hyphens only (per AGENTS.md naming convention)
 		if (p.agent && typeof p.agent === "string" && p.agent.includes("_")) {
 			errors.push(`Phase '${p.id}': agent name '${p.agent}' uses underscores — use hyphens (e.g. 'executor-code' not 'executor_code')`);