taskflow-core 0.2.0 → 0.2.2

package/dist/runtime.js

@@ -11,7 +11,7 @@
  */
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { coerceArray, evaluateCondition, interpolate, safeParse, tryEvaluateCondition } from "./interpolate.js";
+import { coerceArray, evaluateCondition, interpolate, interpolateValue, safeParse, tryEvaluateCondition } from "./interpolate.js";
 import { contractViolations } from "./contract.js";
 import { isFailed, isTransientError, mapWithConcurrencyLimit, PHASE_TIMEOUT_ABORT_GRACE_MS, sanitizeErrorMessage } from "./runner-core.js";
 /** Default runner used when no host injected one: fail loudly rather than
@@ -28,7 +28,7 @@ const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
 });
 export { PHASE_TIMEOUT_ABORT_GRACE_MS } from "./runner-core.js";
 import { aggregateUsage, emptyUsage } from "./usage.js";
-import { dependenciesOf, finalPhase, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, MAX_DYNAMIC_PHASES, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateTaskflow } from "./schema.js";
+import { asArray, dependenciesOf, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, MAX_DYNAMIC_PHASES, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateInvocationArgs, validateTaskflow } from "./schema.js";
 import { verifyTaskflow } from "./verify.js";
 import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors } from "./scorers.js";
 import { parseGateVerdict, overBudget as overBudgetCheck, parseTournamentWinner } from "./deterministic.js";
@@ -40,11 +40,19 @@ export { parseGateVerdict };
 import { runCodeCompilesScorer } from "./scorer-runtime.js";
 import { buildReflexionSummary, isContractViolation, REFLEXION_SENTINEL } from "./reflexion.js";
 import { hashInput, newRunId, runsDir } from "./store.js";
+import { resolveFinalOutput } from "./final-output.js";
 import { CacheStore, resolveFingerprint } from "./cache.js";
 import { compileTaskflowToIR, phaseFingerprint } from "./flowir/index.js";
 import { computeStaleFrontier, declaredReadMapOfDef, readMapOf } from "./stale.js";
 import { ctxDirFor, drainPendingSpawns, initCtxDir, registerNode, setNodeStatus } from "./context-store.js";
 import { allocateWorkspace, isWorkspaceKeyword } from "./workspace.js";
+import { cwdArgName, directoryIdentity, isPathWithin, resolveCwdArg, } from "./cwd-bridge.js";
+import { createResolveOnlyWorkspaceSession, } from "./resources/execution.js";
+// Re-export the shared final-output helper + types so callers importing from
+// the runtime barrel get them from one place. The event kernel
+// (`exec/driver.ts`) imports these directly from `./final-output.ts` to avoid
+// a static runtime↔driver import cycle.
+export { resolveFinalOutput, } from "./final-output.js";
 /** Compute the incremental-reuse summary from a run's terminal phase states.
  *  Pure, total, never throws. A phase is "reused" iff it carries a `cacheHit`
  *  marker (set by `cachedPhase` for both within-run resume and cross-run hits). */
@@ -443,7 +451,7 @@ function liveSink(state, phaseId, emitProgress) {
  */
 const CONTEXT_MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
 const MAX_TOTAL_CONTEXT_CHARS = 200_000;
-async function resolvePhaseContext(phase, ctx) {
+async function resolvePhaseContext(phase, ctx, cwd, boundary) {
     const entries = phase.context;
     if (!entries || entries.length === 0)
         return "";
@@ -482,20 +490,29 @@ async function resolvePhaseContext(phase, ctx) {
     const blocks = [];
     for (const p of filtered) {
         try {
-            const abs = path.resolve(p);
-            const stat = fs.statSync(abs);
+            const abs = path.resolve(cwd, p);
+            if (boundary && !isPathWithin(boundary, abs)) {
+                throw new Error(`TF_CWD_BOUNDARY_ESCAPE: context path '${p}' escapes the inherited cwd boundary`);
+            }
+            const canonical = fs.realpathSync(abs);
+            if (boundary && !isPathWithin(boundary, canonical)) {
+                throw new Error(`TF_CWD_BOUNDARY_ESCAPE: context path '${p}' resolves outside the inherited cwd boundary`);
+            }
+            const stat = fs.statSync(canonical);
             if (!stat.isFile())
                 continue;
             if (stat.size > CONTEXT_MAX_FILE_BYTES)
                 continue;
-            const content = fs.readFileSync(abs, "utf-8");
+            const content = fs.readFileSync(canonical, "utf-8");
             const truncated = content.length > limit
                 ? content.slice(0, limit) + `\n... [truncated ${content.length - limit} chars]`
                 : content;
             const ext = path.extname(p).slice(1) || "txt";
             blocks.push(`## File: ${p}\n\n\`\`\`${ext}\n${truncated}\n\`\`\``);
         }
-        catch {
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("TF_CWD_BOUNDARY_ESCAPE:"))
+                throw error;
             console.warn(`[taskflow] Skipped unreadable context file: ${p}`);
         }
     }
@@ -537,19 +554,92 @@ function spawnedOverBudget(state, local) {
  * two isolation-leak bugs in the 0.0.23 review).
  */
 function resolveEffCwd(deps, phase) {
-    return deps._cwdOverride ?? (isWorkspaceKeyword(phase.cwd) ? deps.cwd : phase.cwd ?? deps.cwd);
+    if (deps._cwdOverride)
+        return deps._cwdOverride;
+    if (!phase.cwd || isWorkspaceKeyword(phase.cwd))
+        return deps.cwd;
+    // Node resolves a relative spawn cwd against the Taskflow process cwd. That
+    // is not necessarily the invocation root, so anchor legacy literals here.
+    return path.resolve(deps.cwd, phase.cwd);
+}
+/** Resolve a literal per-branch cwd once for BOTH cache identity and execution.
+ * Existing directories are realpath-canonicalized so aliases/symlinks cannot
+ * collide with a different invocation root under the same raw cwd string. */
+function resolveBranchCwd(deps, cwd) {
+    const resolved = path.resolve(deps.cwd, cwd);
+    return directoryIdentity(resolved)?.canonicalPath ?? resolved;
+}
+function flowTreeUsesCwdBridge(def, loadFlow, seenUses = new Set()) {
+    if (def.phases.some((phase) => cwdArgName(phase.cwd) !== undefined))
+        return true;
+    if (!loadFlow)
+        return false;
+    for (const phase of def.phases) {
+        if ((phase.type ?? "agent") !== "flow" || !phase.use)
+            continue;
+        if (seenUses.has(phase.use))
+            continue;
+        seenUses.add(phase.use);
+        try {
+            const child = loadFlow(phase.use);
+            if (child && flowTreeUsesCwdBridge(child, loadFlow, seenUses))
+                return true;
+        }
+        catch {
+            // Unknown is treated as capability-bearing: disable reuse, then let the
+            // normal phase execution path report the loader failure coherently.
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Freeze the saved-flow namespace for one top-level execution. Capability
+ * discovery and phase execution must observe the same definition, including
+ * the same loader error, or a mutable loader could introduce a bridge only
+ * after the root binding and cache policy were decided.
+ */
+function snapshotFlowLoader(deps) {
+    if (!deps.loadFlow || deps._flowLoaderSnapshot)
+        return deps;
+    const source = deps.loadFlow;
+    const snapshot = new Map();
+    const loadFlow = (name) => {
+        let entry = snapshot.get(name);
+        if (!entry) {
+            try {
+                const loaded = source(name);
+                // Loader-owned objects may be mutated asynchronously. Capability scan
+                // and execution operate on a detached structured snapshot, never the
+                // loader's live reference.
+                entry = { ok: true, value: loaded === undefined ? undefined : structuredClone(loaded) };
+            }
+            catch (error) {
+                entry = { ok: false, error };
+            }
+            snapshot.set(name, entry);
+        }
+        if (!entry.ok)
+            throw entry.error;
+        return entry.value;
+    };
+    return { ...deps, loadFlow, _flowLoaderSnapshot: snapshot };
+}
+function sameDirectoryIdentity(a, b) {
+    return !!a && !!b && a.canonicalPath === b.canonicalPath && a.device === b.device && a.inode === b.inode;
 }
 async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, deps, state, localSpawnUsage) {
     const stack = deps._stack ?? [];
     const inlineDepth = stack.filter((s) => s.startsWith("def:")).length;
     if (inlineDepth >= MAX_DYNAMIC_NESTING) {
-        return { output: `(spawned subflow rejected: nesting exceeded MAX_DYNAMIC_NESTING (${MAX_DYNAMIC_NESTING}))`, usage: emptyUsage() };
+        const error = `spawned subflow rejected: nesting exceeded MAX_DYNAMIC_NESTING (${MAX_DYNAMIC_NESTING})`;
+        return { output: `(${error})`, usage: emptyUsage(), failed: true, error };
     }
     const wrapped = normalizeInlineDef(subflowSpec, childNodeId);
     if (!wrapped)
-        return { output: "(spawned subflow is not a Taskflow / phases array)", usage: emptyUsage() };
+        return { output: "(spawned subflow is not a Taskflow / phases array)", usage: emptyUsage(), failed: true, error: "spawned subflow is not a Taskflow / phases array" };
     if (wrapped.phases.length === 0)
-        return { output: "(spawned subflow had zero phases — no-op)", usage: emptyUsage() };
+        return { output: "(spawned subflow had zero phases — no-op)", usage: emptyUsage(), failed: false };
     // Inner phases without their own agent inherit the assignment's defaultAgent.
     if (defaultAgent) {
         for (const p of wrapped.phases)
@@ -559,12 +649,15 @@ async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, d
     const spawnCwd = resolveEffCwd(deps, phase);
     const dynCwd = spawnCwd;
     const v = validateTaskflow(wrapped, { dynamic: true, cwd: dynCwd });
-    if (!v.ok)
-        return { output: `(spawned subflow failed validation: ${v.errors.join("; ")})`, usage: emptyUsage() };
+    if (!v.ok) {
+        const error = `spawned subflow failed validation: ${v.errors.join("; ")}`;
+        return { output: `(${error})`, usage: emptyUsage(), failed: true, error };
+    }
     const ver = verifyTaskflow({ name: wrapped.name, phases: wrapped.phases, budget: wrapped.budget, concurrency: wrapped.concurrency });
     if (!ver.ok) {
         const errs = ver.issues.filter((i) => i.severity === "error").map((i) => i.message);
-        return { output: `(spawned subflow failed verification: ${errs.join("; ")})`, usage: emptyUsage() };
+        const error = `spawned subflow failed verification: ${errs.join("; ")}`;
+        return { output: `(${error})`, usage: emptyUsage(), failed: true, error };
     }
     // The generated sub-flow gets only what remains after both already-folded
     // parent spend and siblings/ancestors in this still-running spawn batch.  USD
@@ -591,6 +684,8 @@ async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, d
         const subResult = await executeTaskflow(subState, {
             ...deps,
             cwd: dynCwd,
+            _cacheCwdIdentity: phase.cwd !== undefined || deps._cacheCwdIdentity !== undefined ? dynCwd : undefined,
+            _dynamic: true,
             // The parent phase's isolated workspace (if any) applies only to the
             // parent — each spawned sub-phase resolves its own cwd. Clear the
             // override so the whole subflow doesn't inherit the parent's dir
@@ -606,19 +701,23 @@ async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, d
         // Sum every sub-phase's usage so the parent's budget guard sees spawn spend
         // (verdict Issue 2).
         const usage = aggregateUsage(Object.values(subResult.state.phases).map((p) => p.usage ?? emptyUsage()));
-        return { output: subResult.finalOutput ?? "", usage };
+        return {
+            output: subResult.finalOutput ?? "",
+            usage,
+            failed: !subResult.ok,
+            ...(!subResult.ok ? { error: sanitizeErrorMessage(subResult.finalOutput || "spawned subflow failed") } : {}),
+        };
     }
     catch (e) {
-        return { output: `(spawned subflow failed: ${e instanceof Error ? e.message : String(e)})`, usage: emptyUsage() };
+        const error = sanitizeErrorMessage(e instanceof Error ? e.message : String(e));
+        return { output: `(spawned subflow failed: ${error})`, usage: emptyUsage(), failed: true, error };
     }
 }
-async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps, state, run, ledger = { usage: emptyUsage() }) {
+async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps, state, runChild, ledger = { usage: emptyUsage() }) {
     const capped = assignments.slice(0, MAX_DYNAMIC_MAP_ITEMS);
     const lines = [];
     const usages = [];
-    // Effective cwd for flat spawned tasks: honour a workspace override and never
-    // pass a reserved keyword through to the runner.
-    const spawnCwd = resolveEffCwd(deps, phase);
+    const errors = [];
     let idx = 0;
     for (const a of capped) {
         if (deps.signal?.aborted || spawnedOverBudget(state, ledger.usage))
@@ -635,11 +734,24 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
                 out = sub.output;
                 usages.push(sub.usage);
                 ledger.usage = aggregateUsage([ledger.usage, sub.usage]);
-                setNodeStatus(ctxDir, childNodeId, "done");
+                if (sub.failed)
+                    errors.push(sub.error ?? `spawned subflow ${childNodeId} failed`);
+                setNodeStatus(ctxDir, childNodeId, sub.failed ? "failed" : "done");
             }
             else {
-                const r = await run(spawnCwd, deps.agents, agentName, a.task ?? "", { model: phase.model, thinking: phase.thinking, tools: phase.tools, cwd: spawnCwd, signal: deps.signal, ctxDir, nodeId: childNodeId }, deps.globalThinking);
+                const task = a.task ?? "";
+                // Flat ctx_spawn children use the SAME runOne policy as their parent:
+                // phase timeout, idle watchdog, retries, budget accounting, tracing,
+                // prompt diagnostics, cwd capability, and workspace binding.
+                const usageBefore = ledger.usage;
+                const r = await runChild(agentName, task, childNodeId, usageBefore);
                 out = r.output ?? "";
+                if (isFailed(r)) {
+                    const detail = sanitizeErrorMessage(r.errorMessage ?? r.stderr ?? "spawned child failed");
+                    errors.push(detail);
+                    if (!out)
+                        out = `(spawned child failed: ${detail})`;
+                }
                 if (r.usage) {
                     usages.push(r.usage);
                     ledger.usage = aggregateUsage([ledger.usage, r.usage]);
@@ -648,23 +760,31 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
                 // A child may itself have queued spawns — recurse (depth-capped by the tool).
                 const grand = drainPendingSpawns(ctxDir, childNodeId);
                 if (grand.length > 0 && !deps.signal?.aborted && !spawnedOverBudget(state, ledger.usage)) {
-                    const rec = await runSpawnedChildren(grand, ctxDir, childNodeId, phase, deps, state, run, ledger);
+                    const rec = await runSpawnedChildren(grand, ctxDir, childNodeId, phase, deps, state, runChild, ledger);
                     if (rec.reports)
                         out += rec.reports;
                     usages.push(rec.usage);
+                    errors.push(...rec.errors);
                 }
             }
         }
         catch (e) {
             setNodeStatus(ctxDir, childNodeId, "failed");
-            out = `(spawned child failed: ${e instanceof Error ? e.message : String(e)})`;
+            const detail = sanitizeErrorMessage(e instanceof Error ? e.message : String(e));
+            errors.push(detail);
+            out = `(spawned child failed: ${detail})`;
         }
         lines.push(`### spawned child ${idx} (${agentName})\n${out}`);
     }
     const usage = aggregateUsage(usages);
     if (lines.length === 0)
-        return { reports: undefined, usage };
-    return { reports: `\n\n<!-- ctx_spawn: ${lines.length} child report(s) -->\n${lines.join("\n\n")}`, usage };
+        return { reports: undefined, usage, failed: errors.length > 0, errors };
+    return {
+        reports: `\n\n<!-- ctx_spawn: ${lines.length} child report(s) -->\n${lines.join("\n\n")}`,
+        usage,
+        failed: errors.length > 0,
+        errors,
+    };
 }
 async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth = 0, opts) {
     // Trace: phase-start (fail-open). Record whether this phase is replayable
@@ -681,8 +801,10 @@ async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth
         emitUnreplayableMarker(deps, state, phase);
     let result;
     let threw = false;
+    const promptCalls = [];
+    const trackedOpts = { ...opts, promptCalls };
     try {
-        result = await executePhaseImpl(phase, state, deps, prior, emitProgress, _retryDepth, opts);
+        result = await executePhaseImpl(phase, state, deps, prior, emitProgress, _retryDepth, trackedOpts);
     }
     catch (e) {
         threw = true;
@@ -696,6 +818,9 @@ async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth
     }
     if (threw)
         return result; // unreachable; satisfies TS
+    if (promptCalls.length > 0 && !result.cacheHit) {
+        setPromptStats(result, promptCalls);
+    }
     // S1: cache-hit decision (within-run or cross-run) for fold/replay.
     if (result.cacheHit) {
         traceDecision(deps, state, phase.id, {
@@ -732,9 +857,163 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
         }
         return ps;
     };
+    const cwdArg = cwdArgName(phase.cwd);
+    let innerOpts = { ...opts, upstreamDeps: deps };
+    if ((cwdArg !== undefined || deps._dynamic === true || deps._cwdBoundary !== undefined) && phase.when !== undefined) {
+        const whenReadRefs = [];
+        const whenCtx = buildInterpolationContext(state, lastCompletedOutput(state, phase), undefined, (ref) => whenReadRefs.push(ref));
+        const whenResult = evaluateCondition(phase.when, whenCtx);
+        traceDecision(deps, state, phase.id, {
+            type: "when-guard",
+            expression: phase.when,
+            result: whenResult,
+        });
+        if (!whenResult) {
+            return stamp({
+                id: phase.id,
+                status: "skipped",
+                error: `Condition not met: ${phase.when}`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+                reads: readRefsToReads(whenReadRefs, state),
+            });
+        }
+        innerOpts = { ...innerOpts, whenPrechecked: true, whenReadRefs };
+    }
+    if (deps._dynamic === true && ((phase.context?.length ?? 0) > 0 || phase.cwd !== undefined)) {
+        return stamp({
+            id: phase.id,
+            status: "failed",
+            error: "TF_DYNAMIC_RESOURCE_FORBIDDEN: generated sub-flows cannot declare cwd or context file pre-reads",
+            endedAt: Date.now(),
+            usage: emptyUsage(),
+        });
+    }
+    if (cwdArg !== undefined) {
+        const spec = state.def.args?.[cwdArg];
+        if (spec?.type !== "relative-path") {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: `TF_CWD_ARG_INVALID: cwd argument '${cwdArg}' is not declared with type 'relative-path'`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        const bridgeMode = deps.workspaceSession ? "resolve-only" : deps.cwdBridgeMode;
+        const bound = resolveCwdArg(deps.cwd, cwdArg, state.args[cwdArg], bridgeMode);
+        if (!bound.ok) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: `${bound.code}: ${bound.message}`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        if (deps._cwdBoundary && !isPathWithin(deps._cwdBoundary, bound.value.absolutePath)) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: `TF_CWD_BOUNDARY_ESCAPE: cwd argument '${cwdArg}' resolves outside the inherited cwd boundary`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        let workspaceBinding;
+        try {
+            workspaceBinding = await deps.workspaceSession?.bindPhase({
+                invocationRoot: deps.cwd,
+                runId: state.runId,
+                phaseId: phase.id,
+                argName: cwdArg,
+                argDefinitions: state.def.args ?? {},
+                argValues: state.args,
+            });
+        }
+        catch (error) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        if (workspaceBinding && workspaceBinding.absolutePath !== bound.value.absolutePath) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: "TFWS_IDENTITY_MISMATCH: compatibility resolver and capability resolver selected different cwd identities",
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        const innerDeps = {
+            ...deps,
+            _cwdOverride: bound.value.absolutePath,
+            _cwdBoundary: bound.value.absolutePath,
+            _cacheCwdIdentity: bound.value.absolutePath,
+            _disableCache: true,
+            _workspaceBinding: workspaceBinding,
+        };
+        const ps = await executePhaseInner(phase, state, innerDeps, prior, emitProgress, _retryDepth, innerOpts);
+        ps.warnings = [
+            ...(ps.warnings ?? []),
+            `cwd bridge: resolve-only {args.${cwdArg}} -> ${bound.value.logicalPath}; principal/root authorization, cross-process lease, and write journal are active, but filesystem access outside this directory is not sandbox-enforced`,
+        ];
+        return stamp(ps);
+    }
+    if (deps._cwdBoundary && phase.cwd) {
+        if (isWorkspaceKeyword(phase.cwd)) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: `TF_CWD_BOUNDARY_ESCAPE: workspace provider '${phase.cwd}' cannot expand an inherited cwd boundary`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        const selected = directoryIdentity(path.resolve(deps.cwd, phase.cwd));
+        if (!selected || !isPathWithin(deps._cwdBoundary, selected.canonicalPath)) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: `TF_CWD_BOUNDARY_ESCAPE: cwd '${phase.cwd}' must select an existing directory inside the inherited cwd boundary`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        let narrowedBinding;
+        try {
+            narrowedBinding = await deps.workspaceSession?.bindPhase({
+                invocationRoot: selected.canonicalPath,
+                runId: state.runId,
+                phaseId: phase.id,
+                argDefinitions: state.def.args ?? {},
+                argValues: state.args,
+            });
+        }
+        catch (error) {
+            return stamp({
+                id: phase.id,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            });
+        }
+        return stamp(await executePhaseInner(phase, state, {
+            ...deps,
+            _cwdOverride: selected.canonicalPath,
+            _cwdBoundary: selected.canonicalPath,
+            _cacheCwdIdentity: selected.canonicalPath,
+            _workspaceBinding: narrowedBinding,
+        }, prior, emitProgress, _retryDepth, innerOpts));
+    }
     // Non-keyword cwd (or none): no workspace lifecycle — run directly.
     if (!isWorkspaceKeyword(phase.cwd)) {
-        return stamp(await executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth, opts));
+        return stamp(await executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth, innerOpts));
     }
     let ws;
     try {
@@ -748,9 +1027,9 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
     catch {
         ws = undefined; // fail-open: run in the base cwd
     }
-    const innerDeps = ws ? { ...deps, _cwdOverride: ws.dir } : deps;
+    const innerDeps = ws ? { ...deps, _cwdOverride: ws.dir, _cacheCwdIdentity: ws.dir } : deps;
     try {
-        const ps = await executePhaseInner(phase, state, innerDeps, prior, emitProgress, _retryDepth, opts);
+        const ps = await executePhaseInner(phase, state, innerDeps, prior, emitProgress, _retryDepth, innerOpts);
         if (ws && (ws.kind !== "inherited" || ws.note)) {
             const tag = ws.kind === "inherited" ? "workspace" : `workspace:${ws.kind}`;
             const msg = ws.note ? `${tag} — ${ws.note}` : `${tag} at ${ws.dir}`;
@@ -770,7 +1049,13 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
 async function executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth = 0, opts) {
     const type = phase.type ?? "agent";
     const concurrency = phase.concurrency ?? state.def.concurrency ?? 8;
-    const previousOutput = lastCompletedOutput(state, phase);
+    // BREAKING (dogfood issue 1): a reduce phase's {previous.output} aggregates
+    // ALL completed `from[]` outputs in from-array order (one → raw, many →
+    // `### <id>\n\n<output>` joined by `\n\n---\n\n`). Other phase types keep the
+    // historical "last completed dependency" behavior. The aggregated from-ids
+    // are recorded as observed reads (below) so staleness tracks them.
+    const reduceAgg = type === "reduce" ? aggregateReduceFrom(state, phase) : undefined;
+    const previousOutput = reduceAgg ? reduceAgg.value : lastCompletedOutput(state, phase);
     const run = deps.runTask ?? noRunnerInjected;
     // Effective working directory for THIS phase's execution. When an isolated
     // workspace was allocated (worktree isolation), `_cwdOverride` is its dir and
@@ -800,16 +1085,24 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     // M3 observed-readSet: collect every upstream ref this phase resolves, so we
     // can record what its result ACTUALLY depended on (not just its declared
     // dependsOn). Shared by every interpolation in this phase (task / when / …).
-    const readRefs = [];
+    const readRefs = [...(opts?.whenReadRefs ?? [])];
     const onRead = (ref) => {
         readRefs.push(ref);
     };
+    // Record the reduce-aggregated from-ids as observed reads: the phase consumed
+    // these upstream outputs (folded into {previous.output}) even when the task
+    // references {previous.output} once (a single placeholder read would otherwise
+    // record only "previous.output", not the real upstream ids).
+    if (reduceAgg) {
+        for (const id of reduceAgg.ids)
+            readRefs.push(`steps.${id}.output`);
+    }
     const ctx = buildInterpolationContext(state, previousOutput, undefined, onRead);
     // M3 observed-readSet: when conditions are part of the phase's real
     // dependencies. Evaluate them inside executePhaseInner so every upstream
     // interpolation is captured by the shared onRead hook, not silently dropped
     // by a separate out-of-band context.
-    if (phase.when !== undefined) {
+    if (phase.when !== undefined && opts?.whenPrechecked !== true) {
         const whenResult = evaluateCondition(phase.when, ctx);
         traceDecision(deps, state, phase.id, {
             type: "when-guard",
@@ -827,7 +1120,10 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             };
         }
     }
-    const preRead = await resolvePhaseContext(phase, ctx);
+    // `context` keeps its historical invocation-root meaning. Phase cwd may be a
+    // temporary/worktree directory; rebasing context there would silently stop
+    // existing flows from reading authored source files.
+    const preRead = await resolvePhaseContext(phase, ctx, deps.cwd, deps._cwdBoundary);
     // 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.
@@ -851,6 +1147,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     if (phase.idempotent === false) {
         cacheScope = "off";
     }
+    if (deps._disableCache) {
+        cacheScope = "off";
+    }
     const cc = {
         scope: cacheScope,
         ttlMs: phase.cache?.ttl ? (parseTtlMs(phase.cache.ttl) ?? undefined) : undefined,
@@ -869,17 +1168,72 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         agentScope: state.def.agentScope,
         contextSharing: state.def.contextSharing === true,
         agentDefinitions: agentDefinitionsIdentity(deps.agents),
+        executionCwd: directoryIdentity(effCwd)?.canonicalPath ?? path.resolve(effCwd),
+    };
+    // Effective idle watchdog (ms): phase overrides flow; host default (300000)
+    // applies when neither sets it. `0` disables the watchdog (validation already
+    // required a finite wall `timeout` in that case). Threaded into RunOptions so
+    // every host runner that delegates to runSubagentProcess honors it.
+    const effIdleTimeoutMs = resolveIdleTimeoutMs(phase, state.def);
+    const baseRun = (agentName, task, onLive, ctxNodeId, signal, callCwd, onTerminalCommit) => {
+        const invocationCwd = callCwd ? path.resolve(deps.cwd, callCwd) : effCwd;
+        // A per-branch cwd cannot replace a phase-level workspace/cwd-bridge
+        // binding: that would bypass the binding's containment/dirty-state
+        // lifecycle. Validation rejects this shape; keep a runtime fail-closed
+        // guard for direct callers or legacy persisted definitions.
+        if (callCwd && (deps._workspaceBinding || isWorkspaceKeyword(phase.cwd))) {
+            return Promise.resolve({
+                agent: agentName,
+                task,
+                exitCode: 1,
+                output: "",
+                stderr: "TF_CWD_BRANCH_BINDING_CONFLICT: per-branch cwd cannot override a phase workspace binding",
+                usage: emptyUsage(),
+                stopReason: "error",
+                errorMessage: "TF_CWD_BRANCH_BINDING_CONFLICT: per-branch cwd cannot override a phase workspace binding",
+            });
+        }
+        if (callCwd && deps._cwdBoundary) {
+            const selected = directoryIdentity(invocationCwd);
+            if (!selected || !isPathWithin(deps._cwdBoundary, selected.canonicalPath)) {
+                return Promise.resolve({
+                    agent: agentName,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: "TF_CWD_BOUNDARY_ESCAPE: per-branch cwd must select an existing directory inside the inherited cwd boundary",
+                    usage: emptyUsage(),
+                    stopReason: "error",
+                    errorMessage: "TF_CWD_BOUNDARY_ESCAPE: per-branch cwd must select an existing directory inside the inherited cwd boundary",
+                });
+            }
+        }
+        opts?.promptCalls?.push(task);
+        const runOptions = {
+            model: phase.model,
+            thinking: phase.thinking,
+            tools: phase.tools,
+            cwd: invocationCwd,
+            signal: signal ?? deps.signal,
+            onLive,
+            ctxDir: ctxDir,
+            nodeId: ctxDir ? ctxNodeId : undefined,
+            idleTimeoutMs: effIdleTimeoutMs,
+            onTerminalCommit,
+        };
+        const invoke = () => run(invocationCwd, deps.agents, agentName, task, runOptions, deps.globalThinking);
+        return deps._workspaceBinding
+            ? deps._workspaceBinding.runAgent({
+                agents: deps.agents,
+                agentName,
+                task,
+                opts: runOptions,
+                globalThinking: deps.globalThinking,
+                unitId: ctxNodeId ?? phase.id,
+                invoke,
+            })
+            : invoke();
     };
-    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: signal ?? deps.signal,
-        onLive,
-        ctxDir: ctxDir,
-        nodeId: ctxDir ? ctxNodeId : undefined,
-    }, deps.globalThinking);
     // Wrap each subagent call in the phase's retry policy. Usage is summed across
     // attempts; the attempt count rides along on the result for the TUI.
     //
@@ -899,7 +1253,18 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         : undefined;
     const runOne = async (agentName, task, onLive, ctxNodeId, check, 
     /** Extra abort (e.g. race branch cancelLosers) — chained with run + phase timeout. */
-    extraSignal) => {
+    extraSignal, 
+    /** Per-call cwd override (e.g. a parallel branch's literal cwd). Falls back
+     *  to the phase effective cwd when absent. Workspace keywords are rejected
+     *  by validation for branches, so this is always a literal path or undefined. */
+    callCwd, 
+    /** Usage already spent by earlier calls inside this same multi-call phase
+     * (tree reduce). Included in live budget accounting, but not returned as
+     * this call's own usage. */
+    usageBefore, 
+    /** Optional hard admission guard invoked immediately before EVERY actual
+     * runner attempt. Return an error message to deny that attempt. */
+    beforeAttempt) => {
         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);
@@ -908,9 +1273,24 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             if (deps.signal?.aborted || extraSignal?.aborted)
                 break;
+            const admissionError = beforeAttempt?.();
+            if (admissionError) {
+                last = {
+                    agent: agentName,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: admissionError,
+                    usage: emptyUsage(),
+                    stopReason: "error",
+                    errorMessage: admissionError,
+                };
+                break;
+            }
             // AbortController chains: run signal + optional extra (race cancel) + phase timeout.
             // Deterministic: a timed-out call is never retried (would double-spend).
             let timedOut = false;
+            let terminalCommitted = false;
             let timer;
             let forceReturnTimer;
             const removers = [];
@@ -936,10 +1316,21 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 }
             }
             try {
-                const invocation = baseRun(agentName, task, onLive, ctxNodeId, callSignal);
+                const onTerminalCommit = () => {
+                    if (timedOut)
+                        return;
+                    terminalCommitted = true;
+                    if (timer) {
+                        clearTimeout(timer);
+                        timer = undefined;
+                    }
+                };
+                const invocation = baseRun(agentName, task, onLive, ctxNodeId, callSignal, callCwd, onTerminalCommit);
                 if (phaseTimeoutMs && timeoutController) {
                     const timeoutFallback = new Promise((resolve) => {
                         timer = setTimeout(() => {
+                            if (terminalCommitted)
+                                return;
                             timedOut = true;
                             timeoutController?.abort();
                             forceReturnTimer = setTimeout(() => resolve({
@@ -952,6 +1343,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                                 stopReason: "error",
                                 errorMessage: `Phase runner did not stop within ${PHASE_TIMEOUT_ABORT_GRACE_MS}ms after abort`,
                                 phaseTimeout: true,
+                                completionSource: "phase-timeout",
                             }), PHASE_TIMEOUT_ABORT_GRACE_MS);
                         }, phaseTimeoutMs);
                     });
@@ -979,12 +1371,18 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     stopReason: "error",
                     errorMessage: `Phase timed out after ${phaseTimeoutMs}ms (subagent aborted)`,
                     phaseTimeout: true,
+                    completionSource: "phase-timeout",
                 };
                 usages.push(last.usage);
                 traceEmit(deps, {
                     ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "subagent-call",
                     input: { agent: agentName, model: phase.model, task, preRead, nodePath: ctxNodeId ?? phase.id, attempt },
-                    output: { text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason },
+                    output: {
+                        text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason,
+                        completionSource: last.completionSource,
+                        reapedAfterTerminal: last.reapedAfterTerminal,
+                        terminalGraceMs: last.terminalGraceMs,
+                    },
                 });
                 traceFlush(deps, phase.id);
                 break;
@@ -1008,14 +1406,19 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // so the TUI / budget guard see the in-flight spend on every attempt.
             const liveRetry = state.phases[phase.id];
             if (liveRetry)
-                liveRetry.usage = aggregateUsage(usages);
+                liveRetry.usage = aggregateUsage(usageBefore ? [usageBefore, ...usages] : usages);
             // Persist every attempt, not only the final aggregate. This is required
             // for honest replay/cost accounting when a transient or explicit retry
             // succeeds after earlier spend.
             traceEmit(deps, {
                 ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "subagent-call",
                 input: { agent: agentName, model: phase.model, task, preRead, nodePath: ctxNodeId ?? phase.id, attempt },
-                output: { text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason },
+                output: {
+                    text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason,
+                    completionSource: last.completionSource,
+                    reapedAfterTerminal: last.reapedAfterTerminal,
+                    terminalGraceMs: last.terminalGraceMs,
+                },
             });
             traceFlush(deps, phase.id);
             if (!isFailed(last))
@@ -1023,6 +1426,20 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // Stop retrying on abort (run-level or race cancel) or once over budget.
             if (deps.signal?.aborted || extraSignal?.aborted || overBudget(state).over)
                 break;
+            if (deps._workspaceBinding) {
+                // A failed RW-capability attempt has an unknown filesystem outcome and
+                // is durably marked dirty. Retrying it cannot be proven idempotent until
+                // workspace snapshots/restoration exist, so preserve the first failure
+                // instead of replacing it with a later TFWS_RESOURCE_DIRTY refusal.
+                const requestedRetry = (retry?.max ?? 0) > 0 || isTransientError(last);
+                if (requestedRetry && last.workspaceMutationStarted) {
+                    last = {
+                        ...last,
+                        errorMessage: `${last.errorMessage ?? last.stderr ?? "workspace execution failed"}\nTFWS_RETRY_UNSAFE: retry suppressed because the prior read-write attempt may have mutated the workspace; reconcile before a new attempt`,
+                    };
+                }
+                break;
+            }
             // Decide whether THIS failure warrants another attempt. Explicit retry
             // policy covers all failures up to its cap; the transient fallback covers
             // only retryable provider errors. A non-transient failure with no explicit
@@ -1089,11 +1506,33 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 attempts: 0,
             };
         }
-        if (usages.length > 1)
+        if (usages.length > 0)
             last.usage = aggregateUsage(usages);
         last.attempts = usages.length;
         return last;
     };
+    const runSpawnedChild = async (agentName, task, childNodeId, spawnedUsageBefore) => {
+        // runOne updates the live phase usage so retry/budget admission sees current
+        // spend. A spawned child is folded into the parent result later, so restore
+        // the parent's pre-child usage after the call to avoid replacing/doubling it.
+        const livePhase = state.phases[phase.id];
+        const parentUsage = livePhase?.usage ? { ...livePhase.usage } : undefined;
+        const totalUsageBefore = aggregateUsage([
+            parentUsage ?? emptyUsage(),
+            spawnedUsageBefore ?? emptyUsage(),
+        ]);
+        try {
+            return await runOne(agentName, task, undefined, childNodeId, undefined, undefined, undefined, totalUsageBefore);
+        }
+        finally {
+            if (livePhase) {
+                if (parentUsage)
+                    livePhase.usage = parentUsage;
+                else
+                    livePhase.usage = undefined;
+            }
+        }
+    };
     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
@@ -1188,12 +1627,16 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 if (l.model)
                     latestModel = l.model;
                 refresh();
-            }, ctxDir ? nodeIdFor(String(idx)) : undefined);
+            }, ctxDir ? nodeIdFor(String(idx)) : undefined, undefined, undefined, it.cwd);
             running--;
             done++;
             if (isFailed(r))
                 failed++;
             liveUsages[idx] = r.usage;
+            // Publish the just-finished sibling's spend before considering any
+            // ctx_spawn intents. Budgeted fan-out allows one atomic call to cross the
+            // ceiling, but must not admit descendants after that overshoot.
+            refresh();
             // Per-item cross-run cache record (map only): persist a successful fresh
             // item so a later run with this item unchanged hits per-item instead of
             // re-running. Failed and budget-skipped items are never cached (a stale
@@ -1221,9 +1664,14 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     // post-run drain below only covers single-agent phases).
                     const spawned = drainPendingSpawns(ctxDir, itemNid);
                     if (spawned.length > 0 && !deps.signal?.aborted && !overBudget(state).over) {
-                        const child = await runSpawnedChildren(spawned, ctxDir, itemNid, phase, deps, state, run);
+                        const child = await runSpawnedChildren(spawned, ctxDir, itemNid, phase, deps, state, runSpawnedChild, { usage: emptyUsage() });
                         if (child.reports)
                             r.output = `${r.output ?? ""}${child.reports}`;
+                        if (child.failed && deps._workspaceBinding) {
+                            r.exitCode = r.exitCode === 0 ? 1 : r.exitCode;
+                            r.stopReason = "error";
+                            r.errorMessage = `Workspace ctx_spawn descendant failed: ${child.errors.join("; ")}`;
+                        }
                         if (child.usage) {
                             r.usage = aggregateUsage([r.usage ?? emptyUsage(), child.usage]);
                             liveUsages[idx] = r.usage;
@@ -1239,6 +1687,96 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     // Single-agent phases: agent, gate, and reduce all run one subagent on an
     // interpolated task. gate additionally parses a verdict; reduce simply pulls
     // its inputs from `from` phases (already exposed via interpolation).
+    //
+    // Tree reduce (`reduceStrategy: "tree"`) is handled FIRST: it runs batched
+    // intermediate reducer calls over the aggregated `from[]` inputs, reusing
+    // `runOne` so retry/timeout/budget/idleTimeout behavior is identical to a
+    // one-shot call. It forces the imperative runtime (the event kernel falls
+    // back via kernelUnsupportedReason). The corrected `{previous.output}`
+    // aggregation (all completed `from[]` sources) applies to EVERY round.
+    if (type === "reduce" && phase.reduceStrategy === "tree") {
+        const stratBs = phase.batchSize;
+        const batchSize = typeof stratBs === "number" && Number.isFinite(stratBs) && stratBs >= 2 ? Math.floor(stratBs) : 2;
+        const { collectTreeReduceInputs, executeTreeReduction, treeReduceCacheParts, } = await import("./runtime/phases/reduce.js");
+        const inputs = collectTreeReduceInputs(state, phase);
+        // 0–1 completed inputs: tree reduction is a no-op — fall through to the
+        // one-shot path (which handles the degenerate case correctly).
+        if (inputs.length >= 2) {
+            const agentName = resolveAgent(phase.agent, deps, state);
+            const cacheKey = cacheKeys(cc, treeReduceCacheParts(state, phase, inputs, batchSize));
+            const cached = cachedPhase(cc, cacheKey);
+            if (cached)
+                return cached;
+            const execution = await executeTreeReduction({
+                phase,
+                inputs,
+                batchSize,
+                agentName,
+                inputHash: cacheKey.key,
+                isAborted: () => deps.signal?.aborted === true,
+                isOverBudget: () => overBudget(state).over,
+                resolveTask: (batchValue) => {
+                    const batchCtx = buildInterpolationContext(state, batchValue, undefined, onRead);
+                    const interp = interpolate(phase.task ?? "", batchCtx);
+                    return {
+                        task: appendGateFormatSuffix(preRead + interp.text, phase),
+                        warning: warnUnresolvedRefs(phase.id, interp.missing),
+                    };
+                },
+                runOne: async (task, usageBefore, beforeAttempt, callId) => {
+                    const batchNodeId = nodeIdFor(`tree-${callId}`);
+                    if (ctxDir) {
+                        try {
+                            registerNode(ctxDir, batchNodeId, phase.id, undefined, "running");
+                        }
+                        catch { /* fail-open */ }
+                    }
+                    const result = await runOne(agentName, task, liveSink(state, phase.id, emitProgress), batchNodeId, contractCheck, undefined, undefined, usageBefore, beforeAttempt);
+                    if (ctxDir) {
+                        try {
+                            const spawned = drainPendingSpawns(ctxDir, batchNodeId);
+                            if (spawned.length > 0 && !deps.signal?.aborted && !overBudget(state).over) {
+                                const child = await runSpawnedChildren(spawned, ctxDir, batchNodeId, phase, deps, state, runSpawnedChild, { usage: emptyUsage() });
+                                if (child.reports)
+                                    result.output = `${result.output ?? ""}${child.reports}`;
+                                if (child.failed && deps._workspaceBinding) {
+                                    result.exitCode = result.exitCode === 0 ? 1 : result.exitCode;
+                                    result.stopReason = "error";
+                                    result.errorMessage = `Workspace ctx_spawn descendant failed: ${child.errors.join("; ")}`;
+                                }
+                                result.usage = aggregateUsage([result.usage ?? emptyUsage(), child.usage]);
+                            }
+                            setNodeStatus(ctxDir, batchNodeId, isFailed(result) ? "failed" : "done");
+                        }
+                        catch { /* fail-open */ }
+                    }
+                    const livePhase = state.phases[phase.id];
+                    if (livePhase) {
+                        livePhase.usage = aggregateUsage([
+                            usageBefore ?? emptyUsage(),
+                            result.usage ?? emptyUsage(),
+                        ]);
+                    }
+                    return result;
+                },
+            });
+            const ps = execution.phaseState;
+            if (parseJson && ps.status === "done")
+                ps.json = safeParse(ps.output ?? "");
+            if (readRefs.length)
+                ps.reads = readRefsToReads(readRefs, state);
+            if (execution.refWarning)
+                ps.warnings = [...(ps.warnings ?? []), execution.refWarning];
+            if (ps.budgetTruncated) {
+                ps.warnings = [...(ps.warnings ?? []), "tree reduction stopped by the run budget; output is partial"];
+            }
+            attachReduceInputStats(ps, state, phase);
+            if (execution.cacheable)
+                recordCache(cc, ps);
+            return ps;
+        }
+        // inputs.length < 2 → fall through to one-shot (below).
+    }
     if (type === "agent" || type === "gate" || type === "reduce") {
         // Eval gate: zero-token machine checks before the LLM gate.
         if (type === "gate" && Array.isArray(phase.eval) && phase.eval.length > 0) {
@@ -1468,7 +2006,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                             break;
                         attempt++;
                         if (_retryDepth < MAX_RETRY_DEPTH) {
-                            const { _cwdOverride: _dropGateWs, ...depsForUpstream } = deps;
+                            const depsForUpstream = opts?.upstreamDeps ?? deps;
                             for (const depId of phase.dependsOn ?? []) {
                                 const d = state.def.phases.find((p) => p.id === depId);
                                 if (!d)
@@ -1528,6 +2066,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             ps.reads = readRefsToReads(readRefs, state);
         if (refWarning)
             ps.warnings = [...(ps.warnings ?? []), refWarning];
+        // Prompt-size diagnostics for the single agent call (durable).
+        attachPromptStats(ps, [fullTask]);
+        // reduce: record aggregate input stats.
+        if (type === "reduce")
+            attachReduceInputStats(ps, state, phase);
         if (type === "gate" && ps.status === "done") {
             ps.gate = parseGateVerdict(r.output);
             // Trace: gate decision (fail-open). Replay re-adjudicates thresholds.
@@ -1544,9 +2087,13 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 registerNode(ctxDir, nid, phase.id, undefined, ps.status === "failed" ? "failed" : "done");
                 const spawned = drainPendingSpawns(ctxDir, nid);
                 if (spawned.length > 0 && !deps.signal?.aborted && !overBudget(state).over) {
-                    const child = await runSpawnedChildren(spawned, ctxDir, nid, phase, deps, state, run);
+                    const child = await runSpawnedChildren(spawned, ctxDir, nid, phase, deps, state, runSpawnedChild, { usage: emptyUsage() });
                     if (child.reports)
                         ps.output = `${ps.output ?? ""}${child.reports}`;
+                    if (child.failed && deps._workspaceBinding) {
+                        ps.status = "failed";
+                        ps.error = `Workspace ctx_spawn descendant failed: ${child.errors.join("; ")}`;
+                    }
                     // Fold spawned spend into this phase's usage so the run-wide budget
                     // guard accounts for it (verdict Issue 2).
                     ps.usage = aggregateUsage([ps.usage ?? emptyUsage(), child.usage]);
@@ -1575,7 +2122,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     // NOTE: we intentionally pass the gate's `prior` (not the dep's own
                     // completed state) so the dep does NOT cache-hit and actually
                     // RE-RUNS — re-running upstream is the whole point of onBlock:retry.
-                    const { _cwdOverride: _dropGateWs, ...depsForUpstream } = deps;
+                    const depsForUpstream = opts?.upstreamDeps ?? deps;
                     for (const depId of phase.dependsOn ?? []) {
                         const d = state.def.phases.find((p) => p.id === depId);
                         if (!d)
@@ -1637,7 +2184,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const SCRIPT_TIMEOUT_MS = phase.timeout ?? 60_000;
         const reads = readRefs.length ? readRefsToReads(readRefs, state) : undefined;
         try {
-            const result = await runScriptCommand({
+            const invoke = () => runScriptCommand({
                 interpRunText,
                 arrayForm: Array.isArray(cmd),
                 cwd: effCwd,
@@ -1645,6 +2192,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 stdinInput,
                 timeoutMs: SCRIPT_TIMEOUT_MS,
             });
+            const result = deps._workspaceBinding
+                ? await deps._workspaceBinding.runScript({ unitId: phase.id, signal: deps.signal, invoke })
+                : await invoke();
             const ps = scriptResultToPhaseState(phase, result, {
                 inputHash,
                 timeoutMs: SCRIPT_TIMEOUT_MS,
@@ -1669,6 +2219,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             return {
                 agent: resolveAgent(b.agent ?? phase.agent, deps, state),
                 task: preRead + r.text,
+                cwd: typeof b.cwd === "string" ? resolveBranchCwd(deps, b.cwd) : undefined,
             };
         });
         const ck = cacheKeys(cc, [phase.id, phase.model ?? "", JSON.stringify(branches)]);
@@ -1961,16 +2512,29 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         // Resolve sub-flow args (interpolate string values), then apply declared defaults.
         const provided = {};
         for (const [k, v] of Object.entries(phase.with ?? {})) {
-            provided[k] = typeof v === "string" ? interpolate(v, ctx).text : v;
+            provided[k] = interpolateValue(v, ctx);
         }
         const subArgs = resolveArgs(subDef, provided);
+        if (deps._dynamic === true) {
+            const dynamicChild = validateTaskflow(subDef, { dynamic: true, cwd: effCwd, args: subArgs });
+            if (!dynamicChild.ok) {
+                return failPhase(phase.id, `dynamic nested flow '${subDef.name}' is invalid: ${dynamicChild.errors.join("; ")}`);
+            }
+        }
+        // Re-check the exact loaded definition at the cache boundary. A loader may
+        // change between the root pre-scan and this phase (or return aliases), and
+        // a bridge-bearing child must never be skipped by a cached parent result.
+        const nestedBridgeTree = flowTreeUsesCwdBridge(subDef, deps.loadFlow);
+        if (nestedBridgeTree)
+            deps._disableCache = true;
+        const flowCc = nestedBridgeTree ? { ...cc, scope: "off" } : cc;
         // Every sub-flow cache identity includes the resolved definition. A saved
         // flow's name alone is insufficient: its contents can change without the
         // parent definition moving.
         const flowIdentity = `${hasDef ? "def" : "flow"}:${name}:${JSON.stringify(subDef)}`;
-        const ck = cacheKeys(cc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
+        const ck = cacheKeys(flowCc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
         const inputHash = ck.key;
-        const cached = cachedPhase(cc, ck);
+        const cached = cachedPhase(flowCc, ck);
         if (cached) {
             if (type === "expand" && expandMode === "graft" && cached.promotedPhases) {
                 const promo = promoteGraftPhases(state, cached.promotedPhases);
@@ -2012,6 +2576,8 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // phases without an explicit cwd derive their subagents from the
             // flow's cwd (not the caller's cwd).
             cwd: effCwd,
+            _cacheCwdIdentity: phase.cwd !== undefined || deps._cacheCwdIdentity !== undefined ? effCwd : undefined,
+            _dynamic: hasDef || deps._dynamic === true ? true : undefined,
             // The workspace override applies only to THIS flow phase, not to the
             // nested sub-phases (each resolves its own cwd). Clear it so the child
             // phases don't all inherit this phase's isolated dir as an override.
@@ -2040,6 +2606,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             },
         });
         const sp = Object.values(subState.phases);
+        const nestedFailure = sp.find((nested) => nested.status === "failed")?.error;
         // expand graft promote — pure helper (see runtime/phases/expand.ts)
         const warnings = [];
         let graftPromotedIds = [];
@@ -2073,7 +2640,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 running: 0,
                 failed: sp.filter((p) => p.status === "failed").length,
             },
-            error: subResult.ok ? undefined : `sub-flow '${name}' ${subResult.state.status}`,
+            error: subResult.ok
+                ? undefined
+                : `sub-flow '${name}' ${subResult.state.status}${nestedFailure ? `: ${nestedFailure}` : ""}`,
             inputHash,
             reads: readRefsToReads(readRefs, state),
             endedAt: Date.now(),
@@ -2082,7 +2651,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 ? { promotedPhases: Object.fromEntries(graftPromotedIds.map((id) => [id, { ...subState.phases[id] }])) }
                 : {}),
         };
-        recordCache(cc, flowPs);
+        recordCache(flowCc, flowPs);
         return flowPs;
     }
     // loop-until-done: run the body repeatedly until `until` is truthy, the output
@@ -2462,6 +3031,147 @@ function lastCompletedOutput(state, phase) {
     }
     return undefined;
 }
+/** A conservative prompt-size warning threshold in estimated tokens. Crossed
+ *  → the phase records a `warnings` entry so an author notices they may be
+ *  approaching a model's context limit. Approximate (ceil(chars/4)), not a
+ *  real tokenizer count. Chosen conservatively well below typical 128K context
+ *  windows so the warning fires with ample headroom. */
+export const PROMPT_SIZE_WARN_TOKENS = 32_000;
+/** Compute durable prompt-size diagnostics for a resolved prompt string:
+ *  exact UTF-8 byte count, character count, and a documented approximate token
+ *  estimate (ceil(chars/4)). Never throws. */
+export function promptSizeStats(text) {
+    let chars = 0;
+    for (const _char of text)
+        chars++; // Unicode code points, not UTF-16 code units
+    const bytes = Buffer.byteLength(text, "utf8");
+    const estTokens = Math.ceil(chars / 4);
+    return { bytes, chars, estTokens };
+}
+/** Replace a phase's call diagnostics with the exact prompts captured by the
+ * shared runner boundary. This covers single calls, retries, fan-out items,
+ * loop/tournament/judge calls, and tree-reduce rounds without per-branch drift. */
+function setPromptStats(ps, prompts) {
+    try {
+        const calls = prompts.map((text) => promptSizeStats(text));
+        const reduceInputs = ps.promptStats?.reduceInputs;
+        ps.promptStats = { calls, ...(reduceInputs ? { reduceInputs } : {}) };
+        ps.warnings = (ps.warnings ?? []).filter((warning) => !warning.startsWith("Prompt size ≈"));
+        for (const call of calls) {
+            if (call.estTokens >= PROMPT_SIZE_WARN_TOKENS) {
+                ps.warnings.push(`Prompt size ≈${call.estTokens} tokens (${call.chars} chars, ${call.bytes} bytes) exceeds the conservative ${PROMPT_SIZE_WARN_TOKENS}-token warning threshold — the prompt may be approaching a model's context limit.`);
+            }
+        }
+        if (ps.warnings.length === 0)
+            delete ps.warnings;
+    }
+    catch {
+        /* diagnostics must never sink the phase */
+    }
+}
+/** Attach durable prompt-size diagnostics to a PhaseState. `prompts` is the list
+ *  of resolved prompt strings actually sent to a subagent (one entry per call —
+ *  one for an agent phase, multiple for a tree reduce). Each becomes a
+ *  `{bytes, chars, estTokens}` record on `ps.promptStats.calls`. When any call
+ *  crosses {@link PROMPT_SIZE_WARN_TOKENS}, a `warnings` entry is appended so an
+ *  author notices they may be approaching a model's context limit (the estimate
+ *  is conservative: ceil(chars/4), not a real tokenizer count). Never throws. */
+function attachPromptStats(ps, prompts) {
+    try {
+        const calls = prompts.map((t) => promptSizeStats(t));
+        const existing = ps.promptStats;
+        ps.promptStats = existing
+            ? { ...existing, calls: [...existing.calls, ...calls] }
+            : { calls };
+        for (const c of calls) {
+            if (c.estTokens >= PROMPT_SIZE_WARN_TOKENS) {
+                ps.warnings = [...(ps.warnings ?? []), `Prompt size ≈${c.estTokens} tokens (${c.chars} chars, ${c.bytes} bytes) exceeds the conservative ${PROMPT_SIZE_WARN_TOKENS}-token warning threshold — the prompt may be approaching a model's context limit.`];
+            }
+        }
+    }
+    catch {
+        /* diagnostics must never sink the phase */
+    }
+}
+/** Attach aggregate input stats for a reduce phase: count + total bytes/chars/
+ *  estTokens over the completed `from[]` inputs being reduced. Stored on
+ *  `ps.promptStats.reduceInputs` so post-hoc inspection can account for input
+ *  size across reduce rounds. Never throws. */
+function attachReduceInputStats(ps, state, phase) {
+    try {
+        const s = reduceInputStats(state, phase);
+        const existing = ps.promptStats;
+        ps.promptStats = existing
+            ? { ...existing, reduceInputs: s }
+            : { calls: [], reduceInputs: s };
+    }
+    catch {
+        /* diagnostics must never sink the phase */
+    }
+}
+/** Format a single reduce-from input as a labeled section. */
+function formatReduceInput(id, output) {
+    return `### ${id}\n\n${output}`;
+}
+/** Aggregate completed `from[]` outputs for a reduce phase's {previous.output}.
+ *
+ *  BREAKING correction (dogfood issue 1): a reduce phase's {previous.output}
+ *  resolves to ALL completed `from[]` outputs in from-array order — not just
+ *  the last completed dependency. One completed input → its raw output.
+ *  Multiple → `### <id>\n\n<output>` sections joined by `\n\n---\n\n`.
+ *  `join:"any"` includes only completed branches (skipped/failed are omitted).
+ *
+ *  Returns `{ value, ids }` where `ids` are the from-ids actually aggregated
+ *  (so the runtime can record them as observed reads). `value` is undefined
+ *  when no `from[]` phase completed (e.g. all skipped under join:any). */
+function aggregateReduceFrom(state, phase) {
+    const fromIds = asArray(phase.from);
+    const completed = [];
+    for (const id of fromIds) {
+        const ps = state.phases[id];
+        if (ps?.status === "done" && ps.output !== undefined) {
+            completed.push({ id, output: ps.output });
+        }
+    }
+    if (completed.length === 0)
+        return { value: undefined, ids: [] };
+    if (completed.length === 1)
+        return { value: completed[0].output, ids: [completed[0].id] };
+    const value = completed.map((c) => formatReduceInput(c.id, c.output)).join("\n\n---\n\n");
+    return { value, ids: completed.map((c) => c.id) };
+}
+/** Aggregate stats over the completed `from[]` inputs for reduce diagnostics. */
+function reduceInputStats(state, phase) {
+    const fromIds = asArray(phase.from);
+    let count = 0;
+    let totalBytes = 0;
+    let totalChars = 0;
+    let totalEstTokens = 0;
+    for (const id of fromIds) {
+        const ps = state.phases[id];
+        if (ps?.status === "done" && ps.output !== undefined) {
+            count++;
+            const s = promptSizeStats(ps.output);
+            totalBytes += s.bytes;
+            totalChars += s.chars;
+            totalEstTokens += s.estTokens;
+        }
+    }
+    return { count, totalBytes, totalChars, totalEstTokens };
+}
+/** Resolve the effective idle-watchdog ms for a phase: phase overrides flow;
+ *  returns `undefined` when neither sets it (host default 300000 applies).
+ *  `0` is passed through (disables the watchdog — validation already ensured a
+ *  finite wall `timeout` exists in that case). */
+export function resolveIdleTimeoutMs(phase, def) {
+    const p = phase.idleTimeout;
+    if (typeof p === "number" && Number.isFinite(p))
+        return p;
+    const f = def.idleTimeout;
+    if (typeof f === "number" && Number.isFinite(f))
+        return f;
+    return undefined;
+}
 /** Stable cache identity for the fully resolved agent pool. File paths are
  * excluded: content/config, not installation location, determines output. */
 export function agentDefinitionsIdentity(agents) {
@@ -2503,6 +3213,7 @@ export function cacheKeys(cc, baseParts) {
         `agent-scope:${cc.agentScope ?? "user"}`,
         `context-sharing:${cc.contextSharing === true ? "1" : "0"}`,
         `agents:${cc.agentDefinitions ?? ""}`,
+        ...(cc.executionCwd ? [`cwd:${cc.executionCwd}`] : []),
     ];
     const fold = (parts) => cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
     // Per-phase sub-fingerprint; falls back to the whole-flow hash when absent
@@ -2738,9 +3449,27 @@ export async function recomputeTaskflow(state, deps, seeds,
 // Fail-safe default: a real recompute overwrites the run and spends tokens.
 // The tool/command wrappers can explicitly opt into dryRun:false.
 opts = { dryRun: true }) {
+    deps = snapshotFlowLoader(deps);
     // Never mutate the caller's RunState in-place. Recompute is a speculative
     // replay; only the caller decides whether to persist the new state.
     const newState = structuredClone(state);
+    newState.args = resolveArgs(newState.def, newState.args);
+    const invocationErrors = validateInvocationArgs(newState.def, newState.args);
+    if (invocationErrors.length > 0) {
+        throw new Error(`Taskflow '${newState.def.name}' invocation is invalid: ${invocationErrors.join("; ")}`);
+    }
+    const bridgeTree = flowTreeUsesCwdBridge(newState.def, deps.loadFlow);
+    // Once a run has exercised the compatibility bridge, its persisted root
+    // binding is permanent provenance. A later definition downgrade must not
+    // silently turn cache/recompute back on for state produced with filesystem
+    // authority.
+    const bridgeTainted = bridgeTree || newState.cwdRootBinding !== undefined;
+    if (bridgeTainted && opts.dryRun === false) {
+        throw new Error("recompute dryRun:false is unavailable for cwd-bridge flows until workspace state restoration exists; run the whole flow instead");
+    }
+    if (!deps._disableCache && bridgeTainted) {
+        deps = { ...deps, _disableCache: true };
+    }
     const reads = readMapOf(newState.phases);
     // M2: derive the declared read-map fresh from the def so the frontier uses
     // the UNION (observed ∪ declared). Derived here (not read from the persisted
@@ -2868,7 +3597,7 @@ opts = { dryRun: true }) {
             newState.phases[id] = ps;
             // A phase counts as "rerun" if it was a forced seed OR its result moved;
             // otherwise it hit its cache (inputHash unchanged) → early cutoff.
-            if (isSeed || ps.inputHash !== before) {
+            if (isSeed || !ps.cacheHit || ps.inputHash !== before) {
                 rerun.push(id);
                 outputMoved.add(id);
                 decisions.push(isSeed
@@ -2924,7 +3653,106 @@ opts = { dryRun: true }) {
     };
 }
 export async function executeTaskflow(state, deps) {
+    deps = snapshotFlowLoader(deps);
     const def = state.def;
+    // Normalize defaults at the engine boundary too. Adapters already do this,
+    // but direct Core callers, resume, and detached execution must behave the same.
+    state.args = resolveArgs(def, state.args);
+    const invocationErrors = validateInvocationArgs(def, state.args);
+    if (invocationErrors.length > 0) {
+        state.status = "failed";
+        safeEmit(deps, state);
+        return {
+            state,
+            finalOutput: `Taskflow '${def.name}' invocation is invalid: ${invocationErrors.join("; ")}`,
+            ok: false,
+            totalUsage: emptyUsage(),
+        };
+    }
+    if (deps._dynamic === true) {
+        const dynamicValidation = validateTaskflow(def, { dynamic: true, cwd: deps.cwd, args: state.args });
+        if (!dynamicValidation.ok) {
+            state.status = "failed";
+            safeEmit(deps, state);
+            return {
+                state,
+                finalOutput: `Dynamic taskflow '${def.name}' is invalid: ${dynamicValidation.errors.join("; ")}`,
+                ok: false,
+                totalUsage: emptyUsage(),
+            };
+        }
+    }
+    // A cwd bridge carries compatibility read-write authority. Until workspace
+    // state restoration exists, output-only cache hits could skip required file
+    // mutations or let downstream phases observe stale files. Disable cache and
+    // within-run resume reuse across the complete reachable flow tree.
+    const bridgeTree = flowTreeUsesCwdBridge(def, deps.loadFlow);
+    // Persisted binding is a permanent taint bit: saved-flow definitions can
+    // change between resumes, but prior outputs may already depend on filesystem
+    // mutations. Never regain cache/rebind privileges merely because the current
+    // snapshot no longer declares the bridge.
+    const bridgeTainted = bridgeTree || state.cwdRootBinding !== undefined;
+    if (bridgeTainted) {
+        const invocationRoot = directoryIdentity(deps.cwd);
+        const statePathRoot = directoryIdentity(state.cwd);
+        const launchRoot = state.invocationRootSnapshot;
+        const recordedRoot = state.cwdRootBinding;
+        const executablePhaseIds = new Set(def.phases.map((phase) => phase.id));
+        const hasExecutablePriorState = Object.keys(state.phases).some((id) => executablePhaseIds.has(id));
+        // Pre-seeded external dependencies are inputs, not evidence that a bridge
+        // phase previously executed without a persisted root binding. Conversely,
+        // a host's launch snapshot proves root continuity, not prior bridge
+        // authorization: adding a bridge after ordinary phases ran still fails.
+        const isLegacyResume = bridgeTree && recordedRoot === undefined && hasExecutablePriorState;
+        if (isLegacyResume ||
+            !sameDirectoryIdentity(statePathRoot, invocationRoot) ||
+            (launchRoot !== undefined && !sameDirectoryIdentity(launchRoot, invocationRoot)) ||
+            (recordedRoot !== undefined && !sameDirectoryIdentity(recordedRoot, invocationRoot))) {
+            state.status = "failed";
+            safeEmit(deps, state);
+            return {
+                state,
+                finalOutput: `Taskflow '${def.name}' cwd-bridge invocation root does not match the run's persisted root; start a new run instead of rebinding on resume`,
+                ok: false,
+                totalUsage: emptyUsage(),
+            };
+        }
+        state.cwdRootBinding ??= invocationRoot;
+        // Freeze the invocation root to the canonical identity we just bound. In
+        // particular, do not resolve phase cwd through a caller-provided symlink a
+        // second time after the root-binding check.
+        if (invocationRoot)
+            deps = { ...deps, cwd: invocationRoot.canonicalPath };
+    }
+    if (!deps._disableCache && bridgeTainted) {
+        deps = { ...deps, _disableCache: true };
+    }
+    // The explicit 0.2.1 resolve-only opt-in uses a W1a-compatible partial
+    // control/durability scaffold. This does not upgrade its assurance: the
+    // session is deliberately labelled resolve-only and no OS sandbox claim is
+    // made. A native session must come from an exact approved host baseline cell.
+    if (bridgeTree && deps.cwdBridgeMode === "resolve-only" && !deps.workspaceSession) {
+        try {
+            deps = {
+                ...deps,
+                workspaceSession: await createResolveOnlyWorkspaceSession({
+                    invocationRoot: deps.cwd,
+                    controlDirectory: deps.workspaceControlDirectory,
+                    signal: deps.signal,
+                }),
+            };
+        }
+        catch (error) {
+            state.status = "failed";
+            safeEmit(deps, state);
+            return {
+                state,
+                finalOutput: `Taskflow '${def.name}' workspace capability initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+                ok: false,
+                totalUsage: emptyUsage(),
+            };
+        }
+    }
     const runnerUsageAccounting = deps.runTask
         ?.usageAccounting;
     if (!deps.usageAccounting && runnerUsageAccounting) {
@@ -2948,7 +3776,7 @@ export async function executeTaskflow(state, deps) {
         // not yet persist compatible input hashes, so it must never blindly trust a
         // prior `done` row.
         const hasPriorState = Object.keys(state.phases).length > 0;
-        if (eventKernelEnabled(deps) && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
+        if (eventKernelEnabled(deps) && deps._cwdBoundary === undefined && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
             if (!deps.runTask) {
                 throw new Error("event kernel requires RuntimeDeps.runTask");
             }
@@ -2966,6 +3794,7 @@ export async function executeTaskflow(state, deps) {
                 requestApproval: deps.requestApproval,
                 loadFlow: deps.loadFlow,
                 _stack: deps._stack,
+                _dynamic: deps._dynamic,
             });
         }
         return await runTaskflowLayers(state, deps);
@@ -3075,6 +3904,8 @@ async function runTaskflowLayers(state, deps) {
     let gateBlocked = false;
     let gateReason = "";
     let gateOutput = "";
+    /** Id of the blocking gate/approval phase (source of `gateOutput`). */
+    let gatePhaseId;
     // `budgetBlocked` gates the skipping of remaining phases once the cap is hit
     // and also drives the terminal "blocked" status — a maxUSD ceiling must never
     // silently do nothing.
@@ -3182,6 +4013,7 @@ async function runTaskflowLayers(state, deps) {
                 gateBlocked = true;
                 gateReason = ps.gate.reason ?? "";
                 gateOutput = ps.output ?? "";
+                gatePhaseId = phase.id;
             }
             // A fan-out cut short by the cap is itself a budget skip.
             if (ps.budgetTruncated) {
@@ -3220,15 +4052,6 @@ async function runTaskflowLayers(state, deps) {
             break;
         }
     }
-    const fp = finalPhase(def.phases);
-    let finalState = state.phases[fp.id];
-    // If the designated final phase produced no output (skipped/blocked), fall
-    // back to the last phase (in definition order) that actually completed.
-    if (!finalState || finalState.status !== "done") {
-        const doneInOrder = def.phases.map((p) => state.phases[p.id]).filter((p) => p?.status === "done");
-        if (doneInOrder.length)
-            finalState = doneInOrder[doneInOrder.length - 1];
-    }
     // A failed non-optional phase fails the run; optional failures are tolerated.
     const anyFailed = Object.entries(state.phases).some(([id, p]) => p.status === "failed" && !byId.get(id)?.optional && !p.optional);
     state.status = aborted
@@ -3239,13 +4062,14 @@ async function runTaskflowLayers(state, deps) {
                 ? "failed"
                 : "completed";
     safeEmit(deps, state);
-    let finalOutput = finalState?.output ?? "(no output)";
-    if (gateBlocked) {
-        finalOutput = `Gate blocked the workflow.${gateReason ? `\nReason: ${gateReason}` : ""}${gateOutput ? `\n\n${gateOutput}` : ""}`;
-    }
-    else if (budgetBlocked) {
-        finalOutput = `Budget exceeded — run halted.${budgetReason ? `\nReason: ${budgetReason}` : ""}${finalState?.output ? `\n\n${finalState.output}` : ""}`;
-    }
+    const { finalOutput, outputSourcePhaseId } = resolveFinalOutput(def.phases, state, {
+        gate: gateBlocked,
+        gateReason,
+        gateOutput,
+        gatePhaseId,
+        budget: budgetBlocked,
+        budgetReason,
+    });
     const totalUsage = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
     return {
         state,
@@ -3253,6 +4077,7 @@ async function runTaskflowLayers(state, deps) {
         ok: state.status === "completed",
         totalUsage,
         reuse: summarizeReuse(state),
+        outputSourcePhaseId,
     };
 }
 //# sourceMappingURL=runtime.js.map