taskflow-core 0.1.3 → 0.1.5

package/dist/runtime.js

@@ -12,7 +12,8 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { coerceArray, evaluateCondition, interpolate, safeParse, tryEvaluateCondition } from "./interpolate.js";
-import { isFailed, isTransientError, mapWithConcurrencyLimit } from "./runner-core.js";
+import { contractViolations } from "./contract.js";
+import { isFailed, isTransientError, mapWithConcurrencyLimit, sanitizeErrorMessage } from "./runner-core.js";
 /** Default runner used when no host injected one: fail loudly rather than
  *  silently spawn anything (core is host-neutral and cannot spawn pi/codex). */
 const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
@@ -28,6 +29,9 @@ const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
 import { aggregateUsage, emptyUsage } from "./usage.js";
 import { dependenciesOf, finalPhase, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateTaskflow } from "./schema.js";
 import { verifyTaskflow } from "./verify.js";
+import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors } from "./scorers.js";
+import { runCodeCompilesScorer } from "./scorer-runtime.js";
+import { buildReflexionSummary, isContractViolation, REFLEXION_SENTINEL } from "./reflexion.js";
 import { hashInput, newRunId, runsDir } from "./store.js";
 import { CacheStore, resolveFingerprint } from "./cache.js";
 import { compileTaskflowToIR, phaseFingerprint } from "./flowir/index.js";
@@ -64,7 +68,7 @@ export function summarizeReuse(state) {
         savedUSD,
     };
 }
-function buildInterpolationContext(state, previousOutput, locals, onRead) {
+function buildInterpolationContext(state, previousOutput, locals, onRead, reflexion) {
     const steps = {};
     for (const [id, ps] of Object.entries(state.phases)) {
         // Include both done AND failed phases so downstream phases can see
@@ -81,7 +85,7 @@ function buildInterpolationContext(state, previousOutput, locals, onRead) {
             }
         }
     }
-    return { args: state.args, steps, previousOutput, locals, onRead };
+    return { args: state.args, steps, previousOutput, locals, onRead, reflexion };
 }
 function resultToPhaseState(id, r, inputHash, parseJson) {
     const failed = isFailed(r);
@@ -100,6 +104,7 @@ function resultToPhaseState(id, r, inputHash, parseJson) {
         usage: r.usage,
         model: r.model,
         attempts: attempts > 1 ? attempts : undefined,
+        timedOut: r.phaseTimeout || undefined,
         error: failed ? r.errorMessage || r.stderr || r.output : undefined,
         inputHash,
         endedAt: Date.now(),
@@ -314,6 +319,7 @@ function mergePhaseState(id, results, inputHash, parseJson) {
         usage,
         model,
         attempts: attempts > results.length ? attempts : undefined,
+        timedOut: ran.some((r) => r.phaseTimeout) || undefined,
         budgetTruncated: budgetSkips.length > 0 || undefined,
         subProgress: { done: ran.length, total: results.length, running: 0, failed: failedCount },
         error: errors.length ? errors.join("; ") : undefined,
@@ -550,9 +556,26 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
     return { reports: `\n\n<!-- ctx_spawn: ${lines.length} child report(s) -->\n${lines.join("\n\n")}`, usage };
 }
 async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth = 0, opts) {
+    // Side-effect classification: stamp the marker at the single exit point so
+    // every type branch inside executePhaseInner is covered. A skipped phase ran
+    // nothing — no side effect to record.
+    const stamp = (ps) => {
+        if (phase.idempotent === false && ps.status !== "skipped") {
+            ps.sideEffect = true;
+            // Resume double-fire warning (issue #20): a non-idempotent phase is never
+            // cached, so on resume it RE-EXECUTES even though a prior attempt already
+            // completed — re-firing its side effect. Surface it so operators aren't
+            // surprised by a second webhook/deploy. Only when a prior DONE state
+            // existed (the resume signal) and this run actually re-ran (status done).
+            if (prior?.status === "done" && ps.status === "done" && !ps.cacheHit) {
+                ps.warnings = [...(ps.warnings ?? []), "idempotent:false phase re-executed on resume (a prior attempt had completed) — its side effect fired again"];
+            }
+        }
+        return ps;
+    };
     // Non-keyword cwd (or none): no workspace lifecycle — run directly.
     if (!isWorkspaceKeyword(phase.cwd)) {
-        return executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth, opts);
+        return stamp(await executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth, opts));
     }
     let ws;
     try {
@@ -574,7 +597,7 @@ async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth
             const msg = ws.note ? `${tag} — ${ws.note}` : `${tag} at ${ws.dir}`;
             ps.warnings = [...(ps.warnings ?? []), msg];
         }
-        return ps;
+        return stamp(ps);
     }
     finally {
         try {
@@ -648,13 +671,21 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     // each run (schema already rejects explicit cross-run, but the default-scope
     // path must also be blocked). If flowDefHash failed, cross-run is unsafe
     // because the key degrades to flowName-only and reopens cross-flow collisions.
-    const CROSS_RUN_BLOCKED_TYPES = new Set(["gate", "approval", "loop", "tournament"]);
+    const CROSS_RUN_BLOCKED_TYPES = new Set(["gate", "approval", "loop", "tournament", "script"]);
     if (cacheScope === "cross-run" && CROSS_RUN_BLOCKED_TYPES.has(type)) {
         cacheScope = "run-only";
     }
     if (state.flowDefHash === "failed" && cacheScope === "cross-run") {
         cacheScope = "run-only";
     }
+    // Side-effect classification: a non-idempotent phase is NEVER cached — not
+    // served from within-run resume, not served from or written to the cross-run
+    // store (cachedPhase and recordCache both gate on scope). One assignment
+    // covers every cache path, including the map per-item path (perItemCacheable
+    // requires scope === "cross-run").
+    if (phase.idempotent === false) {
+        cacheScope = "off";
+    }
     const cc = {
         scope: cacheScope,
         ttlMs: phase.cache?.ttl ? (parseTtlMs(phase.cache.ttl) ?? undefined) : undefined,
@@ -671,12 +702,12 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         tools: phase.tools,
         preRead,
     };
-    const baseRun = (agentName, task, onLive, ctxNodeId) => run(effCwd, deps.agents, agentName, task, {
+    const baseRun = (agentName, task, onLive, ctxNodeId, signal) => run(effCwd, deps.agents, agentName, task, {
         model: phase.model,
         thinking: phase.thinking,
         tools: phase.tools,
         cwd: effCwd,
-        signal: deps.signal,
+        signal: signal ?? deps.signal,
         onLive,
         ctxDir: ctxDir,
         nodeId: ctxDir ? ctxNodeId : undefined,
@@ -693,7 +724,12 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     const DEFAULT_TRANSIENT_RETRIES = 3;
     const DEFAULT_TRANSIENT_BACKOFF_MS = 2000;
     const DEFAULT_TRANSIENT_FACTOR = 2;
-    const runOne = async (agentName, task, onLive, ctxNodeId) => {
+    // Per-phase timeout: caps EACH subagent call of an agent-running phase.
+    // (script phases enforce their own child-process timeout — see the script branch.)
+    const phaseTimeoutMs = type !== "script" && typeof phase.timeout === "number" && Number.isFinite(phase.timeout) && phase.timeout >= 1000
+        ? phase.timeout
+        : undefined;
+    const runOne = async (agentName, task, onLive, ctxNodeId, check) => {
         const explicitMax = Math.max(1, 1 + Math.max(0, Math.floor(retry?.max ?? 0)));
         // Allow enough attempts to cover whichever policy applies on a given attempt.
         const maxAttempts = Math.max(explicitMax, 1 + DEFAULT_TRANSIENT_RETRIES);
@@ -702,8 +738,65 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             if (deps.signal?.aborted)
                 break;
-            last = await baseRun(agentName, task, onLive, ctxNodeId);
+            // Phase timeout — an AbortController chained to the run's signal that also
+            // fires after `phase.timeout` ms. Deterministic: a timed-out call is never
+            // retried (retrying a call that just burned its full cap would double-spend).
+            let timedOut = false;
+            let timer;
+            let onParentAbort;
+            let callSignal;
+            if (phaseTimeoutMs) {
+                const ac = new AbortController();
+                callSignal = ac.signal;
+                if (deps.signal?.aborted)
+                    ac.abort();
+                else if (deps.signal) {
+                    onParentAbort = () => ac.abort();
+                    deps.signal.addEventListener("abort", onParentAbort, { once: true });
+                }
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    ac.abort();
+                }, phaseTimeoutMs);
+            }
+            try {
+                last = await baseRun(agentName, task, onLive, ctxNodeId, callSignal);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                if (onParentAbort)
+                    deps.signal?.removeEventListener("abort", onParentAbort);
+            }
+            if (timedOut) {
+                // Reclassify the abort as a phase timeout: a distinct, deterministic
+                // failure (stopReason "error" keeps it in the failed bucket; the
+                // phaseTimeout marker excludes it from transient retry).
+                last = {
+                    ...last,
+                    exitCode: last.exitCode === 0 ? 1 : last.exitCode,
+                    stopReason: "error",
+                    errorMessage: `Phase timed out after ${phaseTimeoutMs}ms (subagent aborted)`,
+                    phaseTimeout: true,
+                };
+                usages.push(last.usage);
+                break;
+            }
             usages.push(last.usage);
+            // Output contract (`expect`): a successful attempt whose JSON output
+            // violates the declared contract is a failure — eligible for the phase's
+            // explicit retry policy (never the transient fallback).
+            if (check && !isFailed(last)) {
+                const violations = check(last);
+                if (violations.length > 0) {
+                    last = {
+                        ...last,
+                        exitCode: last.exitCode === 0 ? 1 : last.exitCode,
+                        stopReason: "error",
+                        errorMessage: `Output contract violated:\n- ${violations.join("\n- ")}`,
+                    };
+                }
+            }
             // B6: aggregate and surface cumulative usage before the retry decision,
             // so the TUI / budget guard see the in-flight spend on every attempt.
             const liveRetry = state.phases[phase.id];
@@ -720,7 +813,13 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // policy stops immediately (no point burning attempts on a hard error).
             const withinExplicit = attempt < explicitMax - 1;
             const transient = isTransientError(last);
-            const withinTransient = transient && attempt < DEFAULT_TRANSIENT_RETRIES;
+            // Side-effect classification: the implicit transient retry is a runtime
+            // safety net the author did not ask for — repeating a side-effecting
+            // call behind the author's back is exactly the hazard idempotent:false
+            // exists to prevent. Explicit retry{} (withinExplicit) stays honored:
+            // it is the author's declaration that a repeat is acceptable.
+            const allowTransient = phase.idempotent !== false;
+            const withinTransient = transient && allowTransient && attempt < DEFAULT_TRANSIENT_RETRIES;
             if (!withinExplicit && !withinTransient)
                 break;
             // Backoff: prefer the explicit policy's curve when the phase defines one
@@ -759,6 +858,17 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         return last;
     };
     const parseJson = phase.output === "json";
+    // Output contract (`expect`): validates the parsed JSON output of a finished
+    // subagent call. Wired into `runOne` so a violation counts as a failed attempt
+    // (retryable under the phase's explicit `retry` policy).
+    const contractCheck = phase.expect !== undefined && parseJson
+        ? (r) => {
+            const parsed = safeParse(r.output);
+            if (parsed === undefined)
+                return ["$: output is not valid JSON (contract could not be checked)"];
+            return contractViolations(parsed, phase.expect);
+        }
+        : undefined;
     // Runs a list of sub-tasks with live fan-out progress + aggregate live usage/activity.
     // `perItem` (map only) enables per-item cross-run caching: each item is looked
     // up in the cache before spawning a subagent, and a successful fresh item is
@@ -949,6 +1059,216 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 return ps;
             }
         }
+        // Scoring gate (`score`): deterministic scorers → zero-token auto-pass /
+        // LLM judge / task fallback. Self-contained (including its own onBlock:retry
+        // mirror) so the non-score gate path below stays byte-identical.
+        const scoreRaw = type === "gate" ? phase.score : undefined;
+        if (scoreRaw !== undefined) {
+            const shapeErrs = scorerShapeErrors(scoreRaw);
+            if (shapeErrs.length === 0) {
+                const sc = scoreRaw;
+                const combine = sc.combine ?? "all";
+                const threshold = combine === "weighted" ? (sc.threshold ?? SCORE_DEFAULT_THRESHOLD) : undefined;
+                const scoreId = JSON.stringify(scoreRaw);
+                // One full score evaluation (deterministics → auto-pass | judge | task |
+                // deterministic BLOCK). Re-invoked by the onBlock:retry loop, so it
+                // rebuilds its interpolation context from the CURRENT state each call.
+                const evaluateScore = async () => {
+                    const freshPrev = lastCompletedOutput(state, phase);
+                    const freshCtx = buildInterpolationContext(state, freshPrev, undefined, onRead);
+                    const tInterp = interpolate(sc.target ?? "{previous.output}", freshCtx);
+                    const targetResolved = tInterp.missing.length === 0;
+                    const target = tInterp.text;
+                    // Deterministic scorers — pure ones inline, code-compiles via the
+                    // impure runtime module. Skipped entirely when the target ref did not
+                    // resolve (scoring a literal placeholder would be noise).
+                    const results = [];
+                    if (targetResolved) {
+                        for (let i = 0; i < sc.scorers.length; i++) {
+                            const s = sc.scorers[i];
+                            results.push(s.type === "code-compiles"
+                                ? await runCodeCompilesScorer(s, i, target)
+                                : evaluatePureScorer(s, i, target));
+                        }
+                    }
+                    // Weighted + judge: the judge's weight enlarges the denominator so the
+                    // deterministic combination is a LOWER BOUND — clearing the threshold
+                    // without the judge means the judge could not change the outcome.
+                    const judgeWeight = combine === "weighted" && sc.judge ? (sc.weights?.[sc.scorers.length] ?? 1) : 0;
+                    const det = combineScores(results, combine, sc.weights, threshold ?? SCORE_DEFAULT_THRESHOLD, judgeWeight);
+                    // Auto-pass is only sound when the judge could not veto it:
+                    //  - no judge configured → the deterministics ARE the decision;
+                    //  - weighted + judge → det.passed used the judge-inflated denominator
+                    //    (lower bound), so the judge's score cannot drop it below threshold.
+                    // all/any WITH a judge must NOT auto-skip: there the judge's verdict is
+                    // authoritative (it may check what scorers cannot — e.g. factuality) and
+                    // skipping it would silently bypass a configured quality check.
+                    const judgeCannotVeto = !sc.judge || combine === "weighted";
+                    if (targetResolved && det.passed && judgeCannotVeto) {
+                        // AUTO-PASS — zero LLM tokens (mirrors the eval-skip fast-path).
+                        const inputHash = cacheKeys(cc, [phase.id, "score-skip", scoreId, target]).key;
+                        const scores = { results, combined: det.combined, threshold };
+                        const ps = {
+                            id: phase.id,
+                            status: "done",
+                            output: "PASS (scorers passed — no LLM call)",
+                            gate: { verdict: "pass", scores },
+                            json: scoreResultJSON(results, det.combined, "pass", threshold),
+                            usage: emptyUsage(),
+                            inputHash,
+                            endedAt: Date.now(),
+                        };
+                        if (readRefs.length)
+                            ps.reads = readRefsToReads(readRefs, state);
+                        return ps;
+                    }
+                    const report = targetResolved
+                        ? formatScorerReport(results, det.combined, threshold)
+                        : `## Deterministic scorer report\n(scorers skipped — score.target did not resolve: ${tInterp.missing.join(", ")})`;
+                    // Judge fallback — the LLM-as-judge decides, with the target and the
+                    // deterministic report in evidence. Fail-open on unparseable output.
+                    if (sc.judge) {
+                        const judgeAgent = resolveAgent(sc.judge.agent ?? phase.agent, deps, state);
+                        const judgeText = interpolate(sc.judge.task, freshCtx).text;
+                        // Neutralize fences in the (model-produced) target so it cannot
+                        // close the evidence block and inject instructions at prompt level.
+                        const safeTarget = target.replace(/```/g, "`\u200b``");
+                        const fullJudgeTask = `${preRead}${judgeText}\n\n---\n\n## Target under evaluation\n\`\`\`\n${safeTarget}\n\`\`\`\n\n${report}\n\n` +
+                            `Return JSON {"score": 0.0-1.0, "verdict": "pass"|"block", "reason": "..."} (or end with VERDICT: PASS|BLOCK).`;
+                        const ckJ = cacheKeys(cc, [phase.id, judgeAgent, phase.model ?? "", fullJudgeTask, scoreId]);
+                        const inputHash = ckJ.key;
+                        const cachedJ = cachedPhase(cc, ckJ);
+                        if (cachedJ)
+                            return cachedJ;
+                        const r = await runOne(judgeAgent, fullJudgeTask, liveSink(state, phase.id, emitProgress), nodeIdFor("judge"));
+                        const ps = resultToPhaseState(phase.id, r, inputHash, false);
+                        if (ps.status === "done") {
+                            const judged = parseJudgeOutput(r.output);
+                            // Weighted: the judge's score folds into the combination and the
+                            // threshold decides. all/any: the judge's verdict is authoritative.
+                            const final = combine === "weighted"
+                                ? combineWithJudge(results, sc.weights, threshold ?? SCORE_DEFAULT_THRESHOLD, judged.score)
+                                : { combined: judged.score, passed: judged.verdict === "pass" };
+                            const verdict = final.passed ? "pass" : "block";
+                            ps.gate = { verdict, reason: judged.reason, scores: { results, combined: final.combined, threshold } };
+                            ps.json = scoreResultJSON(results, final.combined, verdict, threshold, { score: judged.score, reason: judged.reason });
+                        }
+                        if (readRefs.length)
+                            ps.reads = readRefsToReads(readRefs, state);
+                        return ps;
+                    }
+                    // Task fallback — the gate's own LLM task runs with the scorer report
+                    // appended, verdict parsed as usual.
+                    if (phase.task) {
+                        const agentName = resolveAgent(phase.agent, deps, state);
+                        const text = interpolate(phase.task, freshCtx).text;
+                        const fullTask = `${preRead}${text}\n\n---\n\n${report}`;
+                        const ckT = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", fullTask, scoreId]);
+                        const inputHash = ckT.key;
+                        const cachedT = cachedPhase(cc, ckT);
+                        if (cachedT)
+                            return cachedT;
+                        const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress), nodeIdFor(), contractCheck);
+                        const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
+                        if (ps.status === "done") {
+                            const v = parseGateVerdict(r.output);
+                            ps.gate = { ...v, scores: { results, combined: det.combined, threshold } };
+                            ps.json = scoreResultJSON(results, det.combined, v.verdict, threshold);
+                        }
+                        if (readRefs.length)
+                            ps.reads = readRefsToReads(readRefs, state);
+                        return ps;
+                    }
+                    // No LLM fallback configured.
+                    if (!targetResolved) {
+                        // Unresolved target with no judge/task is AMBIGUITY, not an explicit
+                        // failure — fail-open PASS with a warning (project invariant).
+                        const inputHash = cacheKeys(cc, [phase.id, "score-unresolved", scoreId]).key;
+                        return {
+                            id: phase.id,
+                            status: "done",
+                            output: "PASS (score.target did not resolve — fail-open)",
+                            gate: { verdict: "pass", reason: `score.target unresolved: ${tInterp.missing.join(", ")}` },
+                            json: scoreResultJSON([], 0, "pass", threshold),
+                            warnings: [`gate score.target did not resolve (${tInterp.missing.join(", ")}) — fail-open PASS`],
+                            usage: emptyUsage(),
+                            inputHash,
+                            endedAt: Date.now(),
+                        };
+                    }
+                    // Deterministic explicit failure is NOT ambiguity: BLOCK.
+                    const inputHash = cacheKeys(cc, [phase.id, "score-block", scoreId, target]).key;
+                    const scores = { results, combined: det.combined, threshold };
+                    const ps = {
+                        id: phase.id,
+                        status: "done",
+                        output: `BLOCK (deterministic scorers failed — no LLM fallback)\n\n${report}`,
+                        gate: { verdict: "block", reason: "deterministic scorers below threshold", scores },
+                        json: scoreResultJSON(results, det.combined, "block", threshold),
+                        usage: emptyUsage(),
+                        inputHash,
+                        endedAt: Date.now(),
+                    };
+                    if (readRefs.length)
+                        ps.reads = readRefsToReads(readRefs, state);
+                    return ps;
+                };
+                let ps = await evaluateScore();
+                // onBlock:retry — mirrors the non-score gate loop below (re-run upstream
+                // deps, then RE-SCORE), sharing its depth cap and budget/abort guards.
+                if (ps.gate?.verdict === "block") {
+                    const onBlockV = phase.onBlock ?? "halt";
+                    const MAX_RETRY_DEPTH = 3;
+                    let attempt = 0;
+                    while (onBlockV === "retry" && attempt < (phase.retry?.max ?? 1)) {
+                        if (deps.signal?.aborted || overBudget(state).over)
+                            break;
+                        attempt++;
+                        if (_retryDepth < MAX_RETRY_DEPTH) {
+                            const { _cwdOverride: _dropGateWs, ...depsForUpstream } = deps;
+                            for (const depId of phase.dependsOn ?? []) {
+                                const d = state.def.phases.find((p) => p.id === depId);
+                                if (!d)
+                                    continue;
+                                const dPs = await executePhase(d, state, depsForUpstream, prior, emitProgress, _retryDepth + 1, undefined);
+                                state.phases[depId] = dPs;
+                            }
+                        }
+                        const prevAttempts = ps.attempts ?? 0;
+                        ps = await evaluateScore();
+                        ps.attempts = prevAttempts + (ps.attempts ?? 0);
+                        if (ps.gate?.verdict !== "block" || overBudget(state).over)
+                            break;
+                    }
+                    if (attempt > 0)
+                        ps.attempts = Math.max(ps.attempts ?? 0, attempt);
+                }
+                recordCache(cc, ps);
+                return ps;
+            }
+            // Malformed score (validation reports it) — fail-open: fall through to
+            // the plain LLM gate with a warning so an authoring slip degrades to the
+            // historical behavior instead of crashing the phase.
+            const scoreWarning = `gate 'score' is malformed and was ignored: ${shapeErrs[0]}`;
+            const interpM = interpolate(phase.task ?? "", ctx);
+            const textM = interpM.text;
+            const refWarningM = warnUnresolvedRefs(phase.id, interpM.missing);
+            const fullTaskM = preRead + textM;
+            const agentNameM = resolveAgent(phase.agent, deps, state);
+            const ckM = cacheKeys(cc, [phase.id, agentNameM, phase.model ?? "", fullTaskM]);
+            const cachedM = cachedPhase(cc, ckM);
+            if (cachedM)
+                return cachedM;
+            const rM = await runOne(agentNameM, fullTaskM, liveSink(state, phase.id, emitProgress), nodeIdFor(), contractCheck);
+            const psM = resultToPhaseState(phase.id, rM, ckM.key, parseJson);
+            if (readRefs.length)
+                psM.reads = readRefsToReads(readRefs, state);
+            psM.warnings = [...(psM.warnings ?? []), scoreWarning, ...(refWarningM ? [refWarningM] : [])];
+            if (psM.status === "done")
+                psM.gate = parseGateVerdict(rM.output);
+            recordCache(cc, psM);
+            return psM;
+        }
         const interp = interpolate(phase.task ?? "", ctx);
         const text = interp.text;
         const refWarning = warnUnresolvedRefs(phase.id, interp.missing);
@@ -959,7 +1279,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const cached = cachedPhase(cc, ck);
         if (cached)
             return cached;
-        const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress), nodeIdFor());
+        const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress), nodeIdFor(), contractCheck);
         const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
         if (readRefs.length)
             ps.reads = readRefsToReads(readRefs, state);
@@ -1021,7 +1341,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 const retryText = interpolate(phase.task ?? "", retryCtx).text;
                 const retryTask = preRead + retryText;
                 const retryIH = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", retryTask]).key;
-                const retryR = await runOne(agentName, retryTask, liveSink(state, phase.id, emitProgress));
+                const retryR = await runOne(agentName, retryTask, liveSink(state, phase.id, emitProgress), undefined, contractCheck);
                 gatePs = resultToPhaseState(phase.id, retryR, retryIH, parseJson);
                 if (gatePs.status === "done")
                     gatePs.gate = parseGateVerdict(retryR.output);
@@ -1035,6 +1355,157 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         recordCache(cc, ps);
         return ps;
     }
+    // script — zero-token shell command. Spawns a child process, pipes
+    // interpolated `input` to stdin, captures stdout as the phase output.
+    if (type === "script") {
+        const cmd = phase.run;
+        if (!cmd) {
+            return {
+                id: phase.id,
+                status: "failed",
+                error: "script phase requires 'run'",
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            };
+        }
+        // Interpolate the command.
+        // Array form: interpolate each element (safe — schema rejects placeholders in string form).
+        // String form: skip interpolation — schema already guarantees no {placeholders}.
+        const interpRun = Array.isArray(cmd)
+            ? cmd.map((s) => interpolate(s, ctx))
+            : [{ text: cmd, missing: [] }];
+        // Warn unresolved references.
+        for (const r of interpRun) {
+            if (r.missing.length)
+                warnUnresolvedRefs(phase.id, r.missing);
+        }
+        const interpRunText = interpRun.map((r) => r.text);
+        // Interpolate stdin input if provided.
+        const stdinInterp = phase.input !== undefined ? interpolate(phase.input, ctx) : undefined;
+        if (stdinInterp?.missing.length)
+            warnUnresolvedRefs(phase.id, stdinInterp.missing);
+        const stdinInput = stdinInterp?.text;
+        const ck = cacheKeys(cc, [phase.id, JSON.stringify(interpRunText), stdinInput ?? ""]);
+        const inputHash = ck.key;
+        const cached = cachedPhase(cc, ck);
+        if (cached)
+            return cached;
+        const MAX_STDOUT = 1_048_576; // 1 MB cap
+        const SCRIPT_TIMEOUT_MS = (phase.timeout ?? 60_000); // default 60 s, configurable via phase.timeout
+        const SIGKILL_GRACE_MS = 5_000; // grace period after SIGTERM before SIGKILL
+        try {
+            const { spawn } = await import("node:child_process");
+            const result = await new Promise((resolve, reject) => {
+                // Array command → direct spawn (safe); string → shell (rejected at validation if it has placeholders).
+                const child = Array.isArray(cmd)
+                    ? spawn(interpRunText[0], interpRunText.slice(1), {
+                        cwd: effCwd,
+                        env: process.env,
+                        shell: false,
+                        signal: deps.signal,
+                    })
+                    : spawn(interpRunText[0], [], {
+                        cwd: effCwd,
+                        env: process.env,
+                        shell: true,
+                        signal: deps.signal,
+                    });
+                let stdout = "";
+                let stderr = "";
+                let stdoutOversize = false;
+                let timedOut = false;
+                child.stdout?.on("data", (d) => {
+                    if (stdout.length < MAX_STDOUT) {
+                        const need = MAX_STDOUT - stdout.length;
+                        stdout += d.toString().slice(0, need);
+                        if (stdout.length >= MAX_STDOUT)
+                            stdoutOversize = true;
+                    }
+                });
+                child.stderr?.on("data", (d) => {
+                    if (stderr.length < 500) {
+                        stderr += d.toString().slice(0, 500 - stderr.length);
+                    }
+                });
+                // Timeout guard: SIGTERM first, then SIGKILL after grace period.
+                let sigkillTimer;
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                    // SIGKILL fallback if process ignores SIGTERM.
+                    sigkillTimer = setTimeout(() => {
+                        try {
+                            child.kill("SIGKILL");
+                        }
+                        catch { /* already dead */ }
+                    }, SIGKILL_GRACE_MS);
+                }, SCRIPT_TIMEOUT_MS);
+                child.on("error", (err) => {
+                    clearTimeout(timer);
+                    clearTimeout(sigkillTimer);
+                    reject(err);
+                });
+                child.on("close", (code) => {
+                    clearTimeout(timer);
+                    clearTimeout(sigkillTimer);
+                    resolve({ stdout, stderr, code, stdoutOversize, timedOut });
+                });
+                if (stdinInput !== undefined) {
+                    child.stdin?.on("error", () => { }); // swallow EPIPE when child closes stdin early
+                    child.stdin?.write(stdinInput);
+                    child.stdin?.end();
+                }
+            });
+            if (result.code !== 0 || result.timedOut) {
+                const ps = {
+                    id: phase.id,
+                    status: "failed",
+                    output: result.stdout,
+                    error: result.timedOut
+                        ? `Script timed out after ${SCRIPT_TIMEOUT_MS}ms`
+                        : `Script exited with code ${result.code}${result.stderr ? ": " + result.stderr.slice(0, 500) : ""}${result.stdoutOversize ? " [stdout truncated at 1 MB]" : ""}`,
+                    timedOut: result.timedOut || undefined,
+                    usage: emptyUsage(),
+                    inputHash,
+                    endedAt: Date.now(),
+                };
+                if (readRefs.length)
+                    ps.reads = readRefsToReads(readRefs, state);
+                // Non-zero exit: cache (deterministic failure). Timeout: don't cache (transient, like spawn errors).
+                if (!result.timedOut)
+                    recordCache(cc, ps);
+                return ps;
+            }
+            const ps = {
+                id: phase.id,
+                status: "done",
+                output: result.stdout.trimEnd() + (result.stdoutOversize ? "\n[stdout truncated at 1 MB]" : ""),
+                usage: emptyUsage(),
+                inputHash,
+                endedAt: Date.now(),
+            };
+            if (readRefs.length)
+                ps.reads = readRefsToReads(readRefs, state);
+            recordCache(cc, ps);
+            return ps;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Note: intentionally NOT cached — spawn errors (ENOENT, permission denied, etc.)
+            // are treated as transient. The phase will re-execute on resume/retry.
+            const ps = {
+                id: phase.id,
+                status: "failed",
+                error: `Script error: ${msg}`,
+                usage: emptyUsage(),
+                inputHash,
+                endedAt: Date.now(),
+            };
+            if (readRefs.length)
+                ps.reads = readRefsToReads(readRefs, state);
+            return ps;
+        }
+    }
     if (type === "parallel") {
         const branches = (phase.branches ?? []).map((b) => {
             const r = interpolate(b.task, ctx);
@@ -1390,14 +1861,17 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         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 reflexionOn = phase.reflexion === true;
         // Canonical first-iteration body for the cache key. It must fold in the
         // interpolated task/upstream refs so that a changed upstream changes the
         // key and recompute no longer silently reuses a stale loop (critic finding).
+        // Reflexion loops resolve {reflexion} to the SENTINEL here so the key
+        // reflects the true first prompt (not a literal placeholder).
         const firstBodyCtx = buildInterpolationContext(state, previousOutput, {
             loop: { iteration: 1, lastOutput: "", maxIterations: maxIters },
-        }, (ref) => readRefs.push(ref));
+        }, (ref) => readRefs.push(ref), reflexionOn ? REFLEXION_SENTINEL : undefined);
         const firstBody = preRead + interpolate(phase.task ?? "", firstBodyCtx).text;
-        const inputHash = hashInput(phase.id, "loop", phase.until ?? "", firstBody, String(maxIters));
+        const inputHash = hashInput(phase.id, "loop", phase.until ?? "", firstBody, String(maxIters), reflexionOn ? "reflexion" : "");
         const usages = [];
         const loopWarnings = [];
         let lastOutput = "";
@@ -1405,24 +1879,103 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         let iterations = 0;
         let stop = "maxIterations";
         let failedResult;
+        // Bounded history of failed iterations (issue #17): when a reflexion loop
+        // continues past failures, only the terminal one survives in `error` — keep
+        // the rest for post-hoc debugging. Capped to avoid unbounded state growth.
+        const LOOP_FAILURE_HISTORY_CAP = 20;
+        const loopFailures = [];
+        const recordLoopFailure = (iteration, r) => {
+            const err = isContractViolation(r.errorMessage)
+                ? r.errorMessage
+                : sanitizeErrorMessage(r.errorMessage || r.stderr || "") || `iteration ${iteration} failed`;
+            loopFailures.push({ iteration, error: err });
+            if (loopFailures.length > LOOP_FAILURE_HISTORY_CAP)
+                loopFailures.shift();
+        };
+        // Reflexion state: what the NEXT iteration should be told about THIS one.
+        let reflexionNext;
+        let lastReflexion;
+        let reflexionAppendWarned = false;
+        // With reflexion on, a failed iteration continues (as feedback) instead of
+        // terminating — track whether the LAST iteration failed so an exhausted
+        // loop still fails (reflexion defers failure, it does not erase it).
+        let lastIterationFailed = false;
         for (let i = 1; i <= maxIters; i++) {
             if (deps.signal?.aborted) {
                 stop = "aborted";
                 break;
             }
             iterations = i;
+            // Assemble the reflexion summary for this iteration (fail-open: a
+            // reflexion assembly bug must never sink the phase).
+            let reflexionStr;
+            if (reflexionOn) {
+                if (i === 1 || !reflexionNext) {
+                    reflexionStr = REFLEXION_SENTINEL;
+                }
+                else {
+                    try {
+                        reflexionStr = buildReflexionSummary(reflexionNext);
+                    }
+                    catch (e) {
+                        reflexionStr = REFLEXION_SENTINEL;
+                        loopWarnings.push(`reflexion summary failed to assemble (iteration ${i}): ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                    lastReflexion = reflexionStr;
+                }
+            }
             // The body sees its iteration number and the prior iteration's output.
             const bodyCtx = buildInterpolationContext(state, previousOutput, {
                 loop: { iteration: i, lastOutput, maxIterations: maxIters },
-            }, (ref) => readRefs.push(ref));
-            const body = preRead + interpolate(phase.task ?? "", bodyCtx).text;
-            const r = await runOne(agentName, body, liveSink(state, phase.id, emitProgress));
+            }, (ref) => readRefs.push(ref), reflexionStr);
+            let body = preRead + interpolate(phase.task ?? "", bodyCtx).text;
+            // Auto-append: reflexion is on but the task never mentions {reflexion} —
+            // inject the summary anyway (opt-in via the flag IS the author's intent)
+            // and tell them once how to control placement.
+            if (reflexionOn && reflexionStr && reflexionStr !== REFLEXION_SENTINEL && !(phase.task ?? "").includes("{reflexion}")) {
+                body = `${body}\n\n---\n\n${reflexionStr}`;
+                if (!reflexionAppendWarned) {
+                    reflexionAppendWarned = true;
+                    loopWarnings.push("reflexion: true but the task has no {reflexion} placeholder — the summary was auto-appended; add {reflexion} to control placement");
+                }
+            }
+            const r = await runOne(agentName, body, liveSink(state, phase.id, emitProgress), undefined, contractCheck);
             usages.push(r.usage);
+            // Fold cumulative loop spend into the live phase state so the run-level
+            // budget guard (overBudget reads state.phases[*].usage) sees the loop's
+            // accrual mid-phase — otherwise each iteration would overwrite the last
+            // and a reflexion loop could spend past the ceiling unnoticed.
+            const livePs = state.phases[phase.id];
+            if (livePs)
+                livePs.usage = aggregateUsage(usages);
             if (isFailed(r)) {
+                // Reflexion mode: a body failure becomes feedback for the next
+                // iteration instead of terminating the loop. Timeout, abort, and an
+                // exhausted budget still hard-stop (consistent with "timedOut is never
+                // retried"; continuing past the budget would spend past the ceiling).
+                const hardStop = !reflexionOn || r.phaseTimeout === true || deps.signal?.aborted === true || overBudget(state).over;
+                if (hardStop) {
+                    failedResult = r;
+                    stop = "failed";
+                    recordLoopFailure(i, r);
+                    break;
+                }
                 failedResult = r;
-                stop = "failed";
-                break;
+                lastIterationFailed = true;
+                recordLoopFailure(i, r);
+                // Sanitize before injecting into the next prompt: raw provider errors
+                // can carry HTML/transport noise (same policy as the transcript path).
+                const rawErr = r.errorMessage || r.stderr || undefined;
+                reflexionNext = {
+                    iteration: i,
+                    outcome: isContractViolation(r.errorMessage) ? "contract-violation" : "subagent-error",
+                    output: r.output,
+                    errorMessage: isContractViolation(r.errorMessage) ? r.errorMessage : rawErr ? sanitizeErrorMessage(rawErr) : undefined,
+                };
+                continue;
             }
+            lastIterationFailed = false;
+            failedResult = undefined;
             prevOutput = lastOutput;
             lastOutput = r.output;
             // Expose this iteration's output as {steps.<thisId>.output|json} so the
@@ -1449,16 +2002,28 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 stop = "converged";
                 break;
             }
+            // Succeeded but not done — the next iteration reflects on the unmet
+            // stop condition (until-not-met is a signal too, not just failures).
+            if (reflexionOn) {
+                reflexionNext = { iteration: i, outcome: "until-not-met", output: lastOutput, until: phase.until };
+            }
         }
         const aggUsage = usages.length ? aggregateUsage(usages) : emptyUsage();
-        if (failedResult || stop === "failed" || stop === "aborted") {
+        // Reflexion: an exhausted loop whose LAST iteration failed is a failure —
+        // reflexion defers termination for feedback, it does not convert a failing
+        // loop into a success.
+        if (reflexionOn && stop === "maxIterations" && lastIterationFailed) {
+            stop = "failed";
+        }
+        if (stop === "failed" || stop === "aborted") {
             return {
                 id: phase.id,
                 status: "failed",
                 output: lastOutput || undefined,
                 usage: aggUsage,
+                timedOut: failedResult?.phaseTimeout || undefined,
                 error: failedResult?.errorMessage || failedResult?.stderr || (stop === "aborted" ? "Aborted" : `loop '${phase.id}' iteration ${iterations} failed`),
-                loop: { iterations, stop },
+                loop: { iterations, stop, ...(lastReflexion ? { reflexion: lastReflexion } : {}), ...(loopFailures.length ? { failures: [...loopFailures] } : {}) },
                 warnings: loopWarnings.length ? loopWarnings : undefined,
                 inputHash,
                 reads: readRefsToReads(readRefs, state),
@@ -1471,7 +2036,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             output: lastOutput,
             json: parseJson ? safeParse(lastOutput) : undefined,
             usage: aggUsage,
-            loop: { iterations, stop },
+            loop: { iterations, stop, ...(lastReflexion ? { reflexion: lastReflexion } : {}), ...(loopFailures.length ? { failures: [...loopFailures] } : {}) },
             warnings: loopWarnings.length ? loopWarnings : undefined,
             inputHash,
             reads: readRefsToReads(readRefs, state),
@@ -1518,6 +2083,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 status: "failed",
                 usage: variantUsage,
                 error: `tournament '${phase.id}': all ${competitors.length} variants failed`,
+                timedOut: ran.some((r) => r.phaseTimeout) || undefined,
                 budgetTruncated: budgetSkipCount > 0 || undefined,
                 tournament: { variants: competitors.length, winner: 0, mode },
                 inputHash,