taskflow-core 0.1.8 → 0.2.1

package/dist/runtime.js

@@ -11,9 +11,9 @@
  */
 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, sanitizeErrorMessage } from "./runner-core.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
  *  silently spawn anything (core is host-neutral and cannot spawn pi/codex). */
 const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
@@ -26,11 +26,13 @@ const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
     errorMessage: "No subagent runner injected",
     stopReason: "error",
 });
+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, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateTaskflow } from "./schema.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, validateInvocationArgs, validateTaskflow } from "./schema.js";
 import { verifyTaskflow } from "./verify.js";
-import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors, WINNER_TOKEN_RE } from "./scorers.js";
-import { parseGateVerdict, overBudget as overBudgetCheck } from "./deterministic.js";
+import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors } from "./scorers.js";
+import { parseGateVerdict, overBudget as overBudgetCheck, parseTournamentWinner } from "./deterministic.js";
+export { parseTournamentWinner } from "./deterministic.js";
 import {} from "./trace.js";
 // Re-export so existing `import { parseGateVerdict } from "./runtime.ts"` callers
 // (and tests) keep working; the implementation now lives in deterministic.ts.
@@ -43,6 +45,8 @@ 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";
 /** 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). */
@@ -252,13 +256,17 @@ function normalizeInlineDef(parsed, phaseId) {
  * than the parent's, never looser. A generated def cannot raise the spend cap by
  * declaring its own large budget. Each dimension becomes min(child, parent).
  */
-function clampSubFlowBudget(sub, parentBudget) {
+function clampSubFlowBudget(sub, parentBudget, spent = emptyUsage()) {
     if (!parentBudget)
         return sub;
     const child = sub.budget;
+    const remainingUSD = parentBudget.maxUSD === undefined ? Infinity : Math.max(0, parentBudget.maxUSD - spent.cost);
+    const remainingTokens = parentBudget.maxTokens === undefined
+        ? Infinity
+        : Math.max(0, parentBudget.maxTokens - (spent.input + spent.output));
     const clamped = {
-        maxUSD: Math.min(child?.maxUSD ?? Infinity, parentBudget.maxUSD ?? Infinity),
-        maxTokens: Math.min(child?.maxTokens ?? Infinity, parentBudget.maxTokens ?? Infinity),
+        maxUSD: Math.min(child?.maxUSD ?? Infinity, remainingUSD),
+        maxTokens: Math.min(child?.maxTokens ?? Infinity, remainingTokens),
     };
     // Drop Infinity dimensions (no cap on that axis).
     const budget = {};
@@ -344,6 +352,37 @@ function traceEmit(deps, event) {
         /* trace is best-effort; never run-breaking */
     }
 }
+/** Emit a `decision` event (S1: full decision coverage for fold/replay). Fail-open. */
+function traceDecision(deps, state, phaseId, decision) {
+    traceEmit(deps, {
+        ts: Date.now(),
+        runId: state.runId,
+        phaseId,
+        kind: "decision",
+        decision,
+    });
+}
+/** Emit gate decision as gate-score when scores present, else gate-verdict. */
+function traceGateDecision(deps, state, phaseId, gate, judgeOutput) {
+    if (gate.scores) {
+        traceDecision(deps, state, phaseId, {
+            type: "gate-score",
+            target: "",
+            results: gate.scores.results,
+            combined: gate.scores.combined,
+            threshold: gate.scores.threshold,
+            verdict: gate.verdict,
+            judgeOutput,
+        });
+    }
+    else {
+        traceDecision(deps, state, phaseId, {
+            type: "gate-verdict",
+            value: gate.verdict,
+            reason: gate.reason,
+        });
+    }
+}
 /** Fail-open trace flush at phase-end. */
 function traceFlush(deps, phaseId) {
     try {
@@ -355,7 +394,7 @@ function traceFlush(deps, phaseId) {
 }
 /** Emit a `decision: unreplayable` marker for a phase whose inputs the trace
  *  cannot fully capture (Shared Context Tree, inner sub-flows, context files,
- *  unobservable interpolation deps). A future replay marks such phases
+ *  unobservable interpolation deps). Offline replay marks such phases
  *  `needs-live-rerun` instead of silently reusing a recorded output.
  *  Single-phase analog of `hasUnobservedDependencies`. Fail-open. */
 function emitUnreplayableMarker(deps, state, phase) {
@@ -371,7 +410,7 @@ function emitUnreplayableMarker(deps, state, phase) {
 function unreplayableReason(state, phase) {
     if (phase.shareContext === true || state.def.contextSharing === true)
         return "context-sharing";
-    if (phase.type === "flow")
+    if (phase.type === "flow" || phase.type === "expand")
         return "inner-flow";
     if (phase.context && phase.context.length > 0)
         return "context-files";
@@ -406,7 +445,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 "";
@@ -445,20 +484,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}`);
         }
     }
@@ -469,6 +517,16 @@ async function resolvePhaseContext(phase, ctx) {
     }
     return result;
 }
+function spawnedOverBudget(state, local) {
+    const budget = state.def.budget;
+    if (!budget)
+        return false;
+    return overBudgetCheck({
+        maxUSD: budget.maxUSD,
+        maxTokens: budget.maxTokens,
+        usages: [...Object.values(state.phases).map((p) => p.usage ?? emptyUsage()), local],
+    }).over;
+}
 /**
  * Run an inline sub-flow queued via `ctx_spawn({subflow})`. Reuses the SAME
  * validation + execution machinery as a `flow{def}` phase (normalizeInlineDef →
@@ -490,19 +548,85 @@ async function resolvePhaseContext(phase, ctx) {
  * 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);
 }
-async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, deps, state) {
+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)
@@ -512,14 +636,26 @@ 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 subDef = clampSubFlowBudget(wrapped, state.def.budget);
+        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
+    // and tokens are clamped independently by clampSubFlowBudget.  Like the main
+    // runtime, this is an atomic-call ceiling: one call may cross the cap, then no
+    // subsequent call is admitted.
+    const parentAndBatchSpent = aggregateUsage([
+        ...Object.values(state.phases).map((p) => p.usage ?? emptyUsage()),
+        localSpawnUsage,
+    ]);
+    const subDef = clampSubFlowBudget(wrapped, state.def.budget, parentAndBatchSpent);
     const subState = {
         runId: newRunId(subDef.name),
         flowName: subDef.name,
@@ -535,6 +671,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
@@ -550,22 +688,29 @@ 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) {
+async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps, state, run, ledger = { usage: emptyUsage() }) {
     const capped = assignments.slice(0, MAX_DYNAMIC_MAP_ITEMS);
     const lines = [];
     const usages = [];
+    const errors = [];
     // 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);
     let idx = 0;
     for (const a of capped) {
-        if (deps.signal?.aborted || overBudget(state).over)
+        if (deps.signal?.aborted || spawnedOverBudget(state, ledger.usage))
             break;
         idx++;
         const childNodeId = `${parentNodeId}--c${idx}`.replace(/[^A-Za-z0-9._-]+/g, "_");
@@ -575,42 +720,92 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
         let out = "";
         try {
             if (isSubflow) {
-                const sub = await runInlineSubflow(a.subflow, a.defaultAgent ?? phase.agent, childNodeId, phase, deps, state);
+                const sub = await runInlineSubflow(a.subflow, a.defaultAgent ?? phase.agent, childNodeId, phase, deps, state, ledger.usage);
                 out = sub.output;
                 usages.push(sub.usage);
-                setNodeStatus(ctxDir, childNodeId, "done");
+                ledger.usage = aggregateUsage([ledger.usage, sub.usage]);
+                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 ?? "";
+                const runOptions = {
+                    model: phase.model,
+                    thinking: phase.thinking,
+                    tools: phase.tools,
+                    cwd: spawnCwd,
+                    signal: deps.signal,
+                    ctxDir,
+                    nodeId: childNodeId,
+                };
+                const invoke = () => run(spawnCwd, deps.agents, agentName, task, runOptions, deps.globalThinking);
+                // ctx_spawn is part of the phase's execution tree, not bookkeeping.
+                // Inherit the exact cwd capability and give every descendant a unique
+                // unit owner so no child can bypass lease/WAL/permit coordination.
+                const r = deps._workspaceBinding
+                    ? await deps._workspaceBinding.runAgent({
+                        agents: deps.agents,
+                        agentName,
+                        task,
+                        opts: runOptions,
+                        globalThinking: deps.globalThinking,
+                        unitId: childNodeId,
+                        invoke,
+                    })
+                    : await invoke();
                 out = r.output ?? "";
-                if (r.usage)
+                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]);
+                }
                 setNodeStatus(ctxDir, childNodeId, isFailed(r) ? "failed" : "done");
                 // 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 && !overBudget(state).over) {
-                    const rec = await runSpawnedChildren(grand, ctxDir, childNodeId, phase, deps, state, run);
+                if (grand.length > 0 && !deps.signal?.aborted && !spawnedOverBudget(state, ledger.usage)) {
+                    const rec = await runSpawnedChildren(grand, ctxDir, childNodeId, phase, deps, state, run, 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
-    // up front so a future replay can short-circuit it without walking events.
-    traceEmit(deps, { ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "phase-start" });
+    // up front so replay can short-circuit it without guessing from output.
+    traceEmit(deps, {
+        ts: Date.now(),
+        runId: state.runId,
+        phaseId: phase.id,
+        kind: "phase-start",
+        dependencies: dependenciesOf(phase),
+        optional: phase.optional === true,
+    });
     if (deps.trace)
         emitUnreplayableMarker(deps, state, phase);
     let result;
@@ -630,6 +825,13 @@ async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth
     }
     if (threw)
         return result; // unreachable; satisfies TS
+    // S1: cache-hit decision (within-run or cross-run) for fold/replay.
+    if (result.cacheHit) {
+        traceDecision(deps, state, phase.id, {
+            type: "cache-hit",
+            scope: result.cacheHit === "cross-run" ? "cross-run" : "run-only",
+        });
+    }
     // Trace: phase-end with the real status, then flush buffered events.
     traceEmit(deps, {
         ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "phase-end",
@@ -644,6 +846,8 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
     // every type branch inside executePhaseInner is covered. A skipped phase ran
     // nothing — no side effect to record.
     const stamp = (ps) => {
+        if (phase.optional === true)
+            ps.optional = true;
         if (phase.idempotent === false && ps.status !== "skipped") {
             ps.sideEffect = true;
             // Resume double-fire warning (issue #20): a non-idempotent phase is never
@@ -657,9 +861,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 {
@@ -673,9 +1031,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}`;
@@ -725,7 +1083,7 @@ 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);
     };
@@ -734,8 +1092,14 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     // 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 (!evaluateCondition(phase.when, ctx)) {
+    if (phase.when !== undefined && opts?.whenPrechecked !== true) {
+        const whenResult = evaluateCondition(phase.when, ctx);
+        traceDecision(deps, state, phase.id, {
+            type: "when-guard",
+            expression: phase.when,
+            result: whenResult,
+        });
+        if (!whenResult) {
             return {
                 id: phase.id,
                 status: "skipped",
@@ -746,7 +1110,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.
@@ -755,7 +1122,7 @@ 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", "script"]);
+    const CROSS_RUN_BLOCKED_TYPES = new Set(["gate", "approval", "loop", "tournament", "script", "race", "expand"]);
     if (cacheScope === "cross-run" && CROSS_RUN_BLOCKED_TYPES.has(type)) {
         cacheScope = "run-only";
     }
@@ -770,6 +1137,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,
@@ -785,17 +1155,36 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         thinking: phase.thinking,
         tools: phase.tools,
         preRead,
+        agentScope: state.def.agentScope,
+        contextSharing: state.def.contextSharing === true,
+        agentDefinitions: agentDefinitionsIdentity(deps.agents),
+        executionCwd: phase.cwd !== undefined || deps._cacheCwdIdentity !== undefined ? effCwd : undefined,
+    };
+    const baseRun = (agentName, task, onLive, ctxNodeId, signal, onTerminalCommit) => {
+        const runOptions = {
+            model: phase.model,
+            thinking: phase.thinking,
+            tools: phase.tools,
+            cwd: effCwd,
+            signal: signal ?? deps.signal,
+            onLive,
+            ctxDir: ctxDir,
+            nodeId: ctxDir ? ctxNodeId : undefined,
+            onTerminalCommit,
+        };
+        const invoke = () => run(effCwd, 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.
     //
@@ -813,44 +1202,90 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     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 runOne = async (agentName, task, onLive, ctxNodeId, check, 
+    /** Extra abort (e.g. race branch cancelLosers) — chained with run + phase timeout. */
+    extraSignal) => {
         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);
         const usages = [];
         let last;
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            if (deps.signal?.aborted)
+            if (deps.signal?.aborted || extraSignal?.aborted)
                 break;
-            // 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).
+            // 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 onParentAbort;
+            let forceReturnTimer;
+            const removers = [];
             let callSignal;
-            if (phaseTimeoutMs) {
+            let timeoutController;
+            if (phaseTimeoutMs || extraSignal) {
                 const ac = new AbortController();
+                timeoutController = ac;
                 callSignal = ac.signal;
-                if (deps.signal?.aborted)
+                if (deps.signal?.aborted || extraSignal?.aborted)
                     ac.abort();
-                else if (deps.signal) {
-                    onParentAbort = () => ac.abort();
-                    deps.signal.addEventListener("abort", onParentAbort, { once: true });
+                else {
+                    if (deps.signal) {
+                        const fn = () => ac.abort();
+                        deps.signal.addEventListener("abort", fn, { once: true });
+                        removers.push(() => deps.signal?.removeEventListener("abort", fn));
+                    }
+                    if (extraSignal) {
+                        const fn = () => ac.abort();
+                        extraSignal.addEventListener("abort", fn, { once: true });
+                        removers.push(() => extraSignal.removeEventListener("abort", fn));
+                    }
                 }
-                timer = setTimeout(() => {
-                    timedOut = true;
-                    ac.abort();
-                }, phaseTimeoutMs);
             }
             try {
-                last = await 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, onTerminalCommit);
+                if (phaseTimeoutMs && timeoutController) {
+                    const timeoutFallback = new Promise((resolve) => {
+                        timer = setTimeout(() => {
+                            if (terminalCommitted)
+                                return;
+                            timedOut = true;
+                            timeoutController?.abort();
+                            forceReturnTimer = setTimeout(() => resolve({
+                                agent: agentName,
+                                task,
+                                exitCode: 1,
+                                output: "",
+                                stderr: "",
+                                usage: emptyUsage(),
+                                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);
+                    });
+                    last = await Promise.race([invocation, timeoutFallback]);
+                }
+                else {
+                    last = await invocation;
+                }
             }
             finally {
                 if (timer)
                     clearTimeout(timer);
-                if (onParentAbort)
-                    deps.signal?.removeEventListener("abort", onParentAbort);
+                if (forceReturnTimer)
+                    clearTimeout(forceReturnTimer);
+                for (const r of removers)
+                    r();
             }
             if (timedOut) {
                 // Reclassify the abort as a phase timeout: a distinct, deterministic
@@ -862,8 +1297,20 @@ 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,
+                        completionSource: last.completionSource,
+                        reapedAfterTerminal: last.reapedAfterTerminal,
+                        terminalGraceMs: last.terminalGraceMs,
+                    },
+                });
+                traceFlush(deps, phase.id);
                 break;
             }
             usages.push(last.usage);
@@ -886,11 +1333,39 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             const liveRetry = state.phases[phase.id];
             if (liveRetry)
                 liveRetry.usage = aggregateUsage(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,
+                    completionSource: last.completionSource,
+                    reapedAfterTerminal: last.reapedAfterTerminal,
+                    terminalGraceMs: last.terminalGraceMs,
+                },
+            });
+            traceFlush(deps, phase.id);
             if (!isFailed(last))
                 break;
-            // Stop retrying on abort or once the run is over budget.
-            if (deps.signal?.aborted || overBudget(state).over)
+            // 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
@@ -919,8 +1394,29 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // backoff.
             const factor = retry ? (retry.factor ?? 1) : DEFAULT_TRANSIENT_FACTOR;
             const wait = Math.min(60000, Math.round(baseMs * factor ** attempt));
-            if (wait > 0)
-                await delay(wait, deps.signal);
+            if (wait > 0) {
+                // Honor run abort and/or race-branch cancel during backoff.
+                if (deps.signal && extraSignal) {
+                    const ac = new AbortController();
+                    const ab = () => ac.abort();
+                    if (deps.signal.aborted || extraSignal.aborted)
+                        ac.abort();
+                    else {
+                        deps.signal.addEventListener("abort", ab, { once: true });
+                        extraSignal.addEventListener("abort", ab, { once: true });
+                    }
+                    try {
+                        await delay(wait, ac.signal);
+                    }
+                    finally {
+                        deps.signal.removeEventListener("abort", ab);
+                        extraSignal.removeEventListener("abort", ab);
+                    }
+                }
+                else {
+                    await delay(wait, extraSignal ?? deps.signal);
+                }
+            }
         }
         // Aborted before any attempt ran → return a clean aborted result (no crash).
         if (!last) {
@@ -939,29 +1435,6 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         if (usages.length > 1)
             last.usage = aggregateUsage(usages);
         last.attempts = usages.length;
-        // Trace: record this subagent call (the load-bearing record a future
-        // replay consumes). Fail-open. nodePath carries the item/variant
-        // discriminator (e.g. "review", "review-item-3", "gate-judge").
-        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: usages.length > 0 ? usages.length - 1 : undefined,
-            },
-            output: {
-                text: last.output,
-                model: last.model,
-                usage: last.usage,
-                stopReason: last.stopReason,
-            },
-        });
         return last;
     };
     const parseJson = phase.output === "json";
@@ -1000,7 +1473,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             emitProgress();
         };
         refresh();
-        return mapWithConcurrencyLimit(items, concurrency, async (it, idx) => {
+        // Usage is only authoritative after a call reports it. Serial admission for
+        // budgeted fan-out prevents N siblings from all observing the same remaining
+        // allowance and overshooting it concurrently.
+        const admissionConcurrency = state.def.budget ? 1 : concurrency;
+        return mapWithConcurrencyLimit(items, admissionConcurrency, async (it, idx) => {
             // Budget guard: stop spawning new fan-out items once the run is over budget.
             if (overBudget(state).over) {
                 done++;
@@ -1090,6 +1567,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                         const child = await runSpawnedChildren(spawned, ctxDir, itemNid, phase, deps, state, run);
                         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;
@@ -1227,6 +1709,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                         };
                         if (readRefs.length)
                             ps.reads = readRefsToReads(readRefs, state);
+                        traceGateDecision(deps, state, phase.id, ps.gate, undefined);
                         return ps;
                     }
                     const report = targetResolved
@@ -1259,6 +1742,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                             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 });
+                            traceGateDecision(deps, state, phase.id, ps.gate, r.output);
                         }
                         if (readRefs.length)
                             ps.reads = readRefsToReads(readRefs, state);
@@ -1332,7 +1816,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)
@@ -1394,13 +1878,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             ps.warnings = [...(ps.warnings ?? []), refWarning];
         if (type === "gate" && ps.status === "done") {
             ps.gate = parseGateVerdict(r.output);
-            // Trace: record the gate verdict decision (fail-open). A future replay
-            // re-adjudicates this against a changed threshold.
+            // Trace: gate decision (fail-open). Replay re-adjudicates thresholds.
             if (ps.gate)
-                traceEmit(deps, {
-                    ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "decision",
-                    decision: { type: "gate-verdict", value: ps.gate.verdict, reason: ps.gate.reason },
-                });
+                traceGateDecision(deps, state, phase.id, ps.gate);
         }
         // Shared Context Tree: register this node, mark its terminal status, and
         // pick up any ctx_spawn intents the subagent queued. The spawned child
@@ -1415,6 +1895,10 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     const child = await runSpawnedChildren(spawned, ctxDir, nid, phase, deps, state, run);
                     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]);
@@ -1443,7 +1927,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)
@@ -1470,9 +1954,9 @@ 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.
+    // script — zero-token shell (spawn/timeout/size caps in runtime/phases/script.ts)
     if (type === "script") {
+        const { runScriptCommand, scriptResultToPhaseState, scriptSpawnErrorToPhaseState } = await import("./runtime/phases/script.js");
         const cmd = phase.run;
         if (!cmd) {
             return {
@@ -1483,19 +1967,16 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 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);
@@ -1505,123 +1986,39 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         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
+        const SCRIPT_TIMEOUT_MS = phase.timeout ?? 60_000;
+        const reads = readRefs.length ? readRefsToReads(readRefs, state) : undefined;
         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();
-                }
+            const invoke = () => runScriptCommand({
+                interpRunText,
+                arrayForm: Array.isArray(cmd),
+                cwd: effCwd,
+                signal: deps.signal,
+                stdinInput,
+                timeoutMs: SCRIPT_TIMEOUT_MS,
             });
-            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(),
+            const result = deps._workspaceBinding
+                ? await deps._workspaceBinding.runScript({ unitId: phase.id, signal: deps.signal, invoke })
+                : await invoke();
+            const ps = scriptResultToPhaseState(phase, result, {
                 inputHash,
-                endedAt: Date.now(),
-            };
-            if (readRefs.length)
-                ps.reads = readRefsToReads(readRefs, state);
-            recordCache(cc, ps);
+                timeoutMs: SCRIPT_TIMEOUT_MS,
+                reads,
+            });
+            // Non-zero exit: cache (deterministic). Timeout/spawn: don't cache (transient).
+            if (ps.status === "done" || (ps.status === "failed" && !ps.timedOut)) {
+                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;
+            // Spawn errors intentionally NOT cached — re-execute on resume/retry.
+            return scriptSpawnErrorToPhaseState(phase.id, err, { inputHash, reads });
         }
     }
+    // parallel — all branches; merge via shared mergePhaseState (phases/parallel.ts)
     if (type === "parallel") {
+        const { executeParallelBranches } = await import("./runtime/phases/parallel.js");
         const branches = (phase.branches ?? []).map((b) => {
             const r = interpolate(b.task, ctx);
             return {
@@ -1634,10 +2031,36 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const cached = cachedPhase(cc, ck);
         if (cached)
             return cached;
-        const results = await runFanout(branches);
-        const ps = mergePhaseState(phase.id, results, inputHash, parseJson);
-        if (readRefs.length)
-            ps.reads = readRefsToReads(readRefs, state);
+        const ps = await executeParallelBranches(phase, branches, runFanout, mergePhaseState, {
+            inputHash,
+            parseJson,
+            reads: readRefs.length ? readRefsToReads(readRefs, state) : undefined,
+        });
+        recordCache(cc, ps);
+        return ps;
+    }
+    // Horizon B: race — implementation lives in runtime/phases/race.ts
+    if (type === "race") {
+        const { executeRaceBranches } = await import("./runtime/phases/race.js");
+        const branches = (phase.branches ?? []).map((b) => {
+            const r = interpolate(b.task, ctx);
+            return {
+                agent: resolveAgent(b.agent ?? phase.agent, deps, state),
+                task: preRead + r.text,
+            };
+        });
+        const ck = cacheKeys(cc, [phase.id, "race", phase.model ?? "", JSON.stringify(branches)]);
+        const inputHash = ck.key;
+        const cached = cachedPhase(cc, ck);
+        if (cached)
+            return cached;
+        const raceRunOne = (agent, task, branchSignal) => runOne(agent, task, undefined, undefined, undefined, branchSignal);
+        const ps = await executeRaceBranches(phase, branches, raceRunOne, isFailed, {
+            inputHash,
+            parseJson,
+            readRefs: readRefs.length ? readRefsToReads(readRefs, state) : undefined,
+            parentSignal: deps.signal,
+        });
         recordCache(cc, ps);
         return ps;
     }
@@ -1735,7 +2158,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         recordCache(cc, ps);
         return ps;
     }
+    // approval — HITL pause (decision → PhaseState in runtime/phases/approval.ts)
     if (type === "approval") {
+        const { approvalDecisionToPhaseState } = await import("./runtime/phases/approval.js");
         const readRefs = [];
         const ctx = buildInterpolationContext(state, previousOutput, undefined, (ref) => readRefs.push(ref));
         const message = interpolate(phase.task ?? "Approve to continue?", ctx).text;
@@ -1744,48 +2169,51 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const cached = cachedPhase(cc, ck);
         if (cached)
             return cached;
-        // Non-interactive (headless/CI/detached): auto-REJECT, fail-open, but record it.
-        // Approval gates are safety boundaries — bypassing them silently in CI would
-        // let unreviewed work ship. Detached/CI runs must not bypass approval gates.
+        const reads = readRefsToReads(readRefs, state);
+        // Non-interactive (headless/CI/detached): auto-REJECT — safety boundary, never bypass.
         if (!deps.requestApproval) {
-            return {
-                id: phase.id,
-                status: "done",
-                output: "(auto-rejected: no interactive approver available)",
-                approval: { decision: "reject", auto: true },
-                gate: { verdict: "block", reason: "(auto-rejected: no interactive approver available)" },
-                usage: emptyUsage(),
+            return approvalDecisionToPhaseState(phase.id, { decision: "reject" }, {
                 inputHash,
-                reads: readRefsToReads(readRefs, state),
-                endedAt: Date.now(),
-            };
-        }
-        const decision = await deps.requestApproval({ phaseId: phase.id, message, upstream: previousOutput });
-        const note = decision.note?.trim();
-        const ps = {
-            id: phase.id,
-            status: "done",
-            output: note || `(${decision.decision})`,
-            approval: { decision: decision.decision, note },
-            usage: emptyUsage(),
-            inputHash,
-            reads: readRefsToReads(readRefs, state),
-            endedAt: Date.now(),
-        };
-        // A rejection halts the flow via the same mechanism as a blocking gate.
-        if (decision.decision === "reject") {
-            ps.gate = { verdict: "block", reason: note || "Rejected by user" };
+                reads,
+                auto: true,
+            });
         }
-        return ps;
+        const decision = await deps.requestApproval({
+            phaseId: phase.id,
+            message,
+            upstream: previousOutput,
+        });
+        return approvalDecisionToPhaseState(phase.id, decision, { inputHash, reads });
     }
-    if (type === "flow") {
+    if (type === "flow" || type === "expand") {
         const readRefs = [];
         const ctx = buildInterpolationContext(state, previousOutput, undefined, (ref) => readRefs.push(ref));
-        const hasDef = phase.def !== undefined;
+        // expand always requires `def`; flow may use `use` or `def`.
+        const hasDef = type === "expand" ? phase.def !== undefined : phase.def !== undefined;
         const stack = deps._stack ?? [];
+        const { resolveExpandMode, resolveMaxNodes, prefixGraftFragment, promoteGraftPhases } = await import("./runtime/phases/expand.js");
+        const expandMode = type === "expand" ? resolveExpandMode(phase) : "nested";
+        const maxNodes = type === "expand" ? resolveMaxNodes(phase, MAX_DYNAMIC_PHASES) : 50;
+        if (type === "expand" && expandMode === "graft") {
+            // Rerun replacement semantics: prior promoted children belong to the old
+            // fragment and must disappear before ANY new resolution path. This is
+            // intentionally before parse/validation/empty/sub-flow failure returns so
+            // stale children and their usage cannot survive a failed or empty v2 plan.
+            const declaredIds = new Set(state.def.phases.map((p) => p.id));
+            for (const oldId of Object.keys(prior?.promotedPhases ?? {})) {
+                // Definition evolution may promote an old dynamic id into a real
+                // authored parent phase. That declared phase owns its state now and must
+                // never be deleted by stale graft metadata.
+                if (!declaredIds.has(oldId))
+                    delete state.phases[oldId];
+            }
+        }
         let subDef;
         let name;
         let recursionKey; // identity used for cache key + recursion guard
+        if (type === "expand" && !hasDef) {
+            return failPhase(phase.id, `expand phase '${phase.id}' requires 'def'`);
+        }
         if (hasDef) {
             // --- Inline `def`: resolve at runtime, validate, fail-OPEN on any error. ---
             // Fail-open contract: a bad def NEVER aborts the run. The phase resolves
@@ -1822,7 +2250,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 parsed = rawDef;
             }
             // Accept a full Taskflow, a bare phases array, or {phases:[...]}; wrap the latter two.
-            const wrapped = normalizeInlineDef(parsed, phase.id);
+            let wrapped = normalizeInlineDef(parsed, phase.id);
             if (!wrapped) {
                 return defFailOpen("inline def is not a Taskflow, phases array, or {phases:[...]}");
             }
@@ -1835,11 +2263,20 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     output: "",
                     json: parseJson ? safeParse("") : undefined,
                     usage: emptyUsage(),
-                    inputHash: hashInput(phase.id, "flow-def-empty"),
+                    inputHash: hashInput(phase.id, type === "expand" ? "expand-def-empty" : "flow-def-empty"),
                     reads: readRefsToReads(readRefs, state),
                     endedAt: Date.now(),
                 };
             }
+            // expand: cap fragment size + prefix ids for graft (helpers in phases/expand.ts).
+            if (type === "expand") {
+                if (wrapped.phases.length > maxNodes) {
+                    return defFailOpen(`expand fragment has ${wrapped.phases.length} phases (maxNodes=${maxNodes})`);
+                }
+                if (expandMode === "graft") {
+                    wrapped = prefixGraftFragment(wrapped, phase.id);
+                }
+            }
             // Validate with `dynamic` hardening (breadth caps + cwd containment) since
             // this content is LLM-authored / untrusted. cwd anchors containment checks.
             const dynCwd = effCwd;
@@ -1879,23 +2316,46 @@ 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);
-        // For inline defs the cache identity must include the resolved def content so
-        // that a different generated plan yields a different key (and an identical plan
-        // hits cache). For saved flows the name is the identity (historical behavior).
-        const flowIdentity = hasDef ? `def:${JSON.stringify(subDef)}` : `flow:${name}`;
-        const ck = cacheKeys(cc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
+        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(flowCc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
         const inputHash = ck.key;
-        const cached = cachedPhase(cc, ck);
-        if (cached)
+        const cached = cachedPhase(flowCc, ck);
+        if (cached) {
+            if (type === "expand" && expandMode === "graft" && cached.promotedPhases) {
+                const promo = promoteGraftPhases(state, cached.promotedPhases);
+                if (promo.promotedIds.length > 0) {
+                    cached.promotedPhases = Object.fromEntries(promo.promotedIds.map((id) => [id, { ...cached.promotedPhases[id] }]));
+                }
+                else {
+                    delete cached.promotedPhases;
+                }
+            }
             return cached;
+        }
         const live = state.phases[phase.id];
-        // Sub-flows enforce their own budget; if they declare none, inherit the
-        // parent cap as a soft per-flow ceiling (best-effort — spend does not cross
-        // flow boundaries, so the parent's already-spent total is not subtracted).
-        const subDefEffective = subDef.budget || !state.def.budget ? subDef : { ...subDef, budget: state.def.budget };
+        // A nested flow receives only the parent's remaining allowance, then its
+        // own cap (if any) may tighten each dimension independently.
+        const parentSpent = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
+        const subDefEffective = clampSubFlowBudget(subDef, state.def.budget, parentSpent);
         const subState = {
             runId: newRunId(subDef.name),
             flowName: subDef.name,
@@ -1913,10 +2373,15 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const subRunTask = (cwd, agents, agentName, subTask, opts, globalThinking) => baseRunTask(cwd, agents, agentName, preRead + subTask, opts, globalThinking);
         const subResult = await executeTaskflow(subState, {
             ...deps,
+            // A trace file is scoped to one runId. The parent flow phase carries an
+            // unreplayable marker; nested events must not be mixed into that file.
+            trace: undefined,
             // Override deps.cwd with the flow phase's own cwd so that sub-flow
             // 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.
@@ -1945,12 +2410,31 @@ 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 = [];
+        if (type === "expand" && expandMode === "graft" && subResult.ok) {
+            const promo = promoteGraftPhases(state, subState.phases);
+            warnings.push(...promo.warnings);
+            graftPromotedIds = promo.promotedIds;
+        }
+        // Graft accounting is ownership-based. Successfully promoted children carry
+        // their own usage in parent state; children skipped on id collision remain
+        // owned by the expand phase and their residual usage must stay here. This
+        // yields: all promoted => 0, all collision => all child usage, mixed => only
+        // collision residual (no loss and no double count).
+        const phaseUsage = type === "expand" && expandMode === "graft" && subResult.ok
+            ? aggregateUsage(Object.entries(subState.phases)
+                .filter(([id]) => !graftPromotedIds.includes(id))
+                .map(([, ps]) => ps.usage ?? emptyUsage()))
+            : subResult.totalUsage;
         const flowPs = {
             id: phase.id,
             status: subResult.ok ? "done" : "failed",
             output: subResult.finalOutput,
             json: parseJson ? safeParse(subResult.finalOutput) : undefined,
-            usage: subResult.totalUsage,
+            usage: phaseUsage,
             // B-F015: include failed in `done` so the renderer's
             // `done - failed` formula gives the success count (matches the
             // map/parallel runner's overlapping-counter convention).
@@ -1960,12 +2444,18 @@ 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(),
+            ...(warnings.length ? { warnings } : {}),
+            ...(type === "expand" && expandMode === "graft" && subResult.ok && graftPromotedIds.length > 0
+                ? { 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
@@ -2208,6 +2698,12 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         }
         // Only one competitor survived → no contest; it wins by default (skip judge).
         if (ok.length === 1) {
+            const w = ranIdx(ok[0]);
+            traceDecision(deps, state, phase.id, {
+                type: "tournament-winner",
+                value: w,
+                reason: "only surviving variant",
+            });
             return {
                 id: phase.id,
                 status: "done",
@@ -2216,7 +2712,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 usage: variantUsage,
                 model: ok[0].model,
                 budgetTruncated: budgetSkipCount > 0 || undefined,
-                tournament: { variants: competitors.length, winner: ranIdx(ok[0]), mode, reason: "only surviving variant" },
+                tournament: { variants: competitors.length, winner: w, mode, reason: "only surviving variant" },
                 inputHash,
                 reads: readRefsToReads(readRefs, state),
                 endedAt: Date.now(),
@@ -2278,6 +2774,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const chosen = winnerIneligible ? ok[0] : winnerResult;
         const winnerIdx = ranIdx(chosen);
         const output = mode === "aggregate" ? judgeRes.output : chosen.output;
+        traceDecision(deps, state, phase.id, {
+            type: "tournament-winner",
+            value: winnerIdx,
+            reason,
+        });
         return {
             id: phase.id,
             status: "done",
@@ -2334,9 +2835,24 @@ function lastCompletedOutput(state, phase) {
     }
     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) {
+    return JSON.stringify(agents
+        .map((a) => ({
+        name: a.name,
+        description: a.description,
+        systemPrompt: a.systemPrompt,
+        model: a.model ?? "",
+        thinking: a.thinking ?? "",
+        tools: [...(a.tools ?? [])].sort(),
+        source: a.source,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name) || a.source.localeCompare(b.source)));
+}
 /** Fold the phase fingerprint into the base hash parts to form the cache keys.
  *
- *  Four keys are produced for backward compatibility (see
+     *  Four keys are derived for tooling/backward compatibility (see
  *  docs/internal/cache-migration.md):
  *    - `key`      : `v3:phasefp:<subfp>` — the current write key (per-phase
  *      structural sub-fingerprint; falls back to the whole-flow hash when
@@ -2344,9 +2860,9 @@ function lastCompletedOutput(state, phase) {
  *    - `v2Key`    : `v2:flowdef:<flowDefHash>` — pre-M6 whole-flow key.
  *    - `bareKey`  : bare `flowdef:<flowDefHash>` (unversioned) — pre-H1 entries.
  *    - `legacyKey`: the flowdef line omitted — pre-flowDefHash entries.
- *  `cachedPhase` consults all four READ-ONLY on a miss; `recordCache` writes
- *  only `key`. This means an upgrade never produces a miss-storm: existing
- *  entries (whichever shape) still hit, and new writes converge on `key`. */
+     *  `cachedPhase` consults the first three safe tiers READ-ONLY on a miss;
+     *  `legacyKey` is never read because it has no structural identity.
+     *  `recordCache` writes only `key`. */
 export function cacheKeys(cc, baseParts) {
     // Fold the full cache identity into the hash: flow name (prevents collisions
     // across different flows that share a phase.id + task + model), the per-phase
@@ -2357,6 +2873,10 @@ export function cacheKeys(cc, baseParts) {
         `think:${cc.thinking ?? ""}`,
         `tools:${JSON.stringify(cc.tools ?? [])}`,
         `ctx:${cc.preRead ?? ""}`,
+        `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
@@ -2375,13 +2895,13 @@ export function cacheKeys(cc, baseParts) {
  *   - "off":      never reuse (even within-run).
  *   - "run-only": within-run resume only (historical behavior).
  *   - "cross-run": within-run first, then the persistent cross-run store.
- * On a cross-run hit, usage is zeroed and `cacheHit` records the source.
- *
- * The cross-run read is FOUR-TIER and READ-ONLY for fallback keys: it tries
+     * On a cross-run hit, usage is zeroed and `cacheHit` records the source.
+     *
+ * The cross-run read is three-tier and READ-ONLY for fallback keys: it tries
  * `keys.key` (current `v3:phasefp:` shape) first, then `keys.v2Key` (pre-M6
- * `v2:flowdef:`), then `keys.bareKey` (pre-H1 bare `flowdef:`), then
- * `keys.legacyKey` (pre-flowDefHash, no flowdef line).
- * A hit on ANY tier is restored as a cache hit; we do NOT write-through (no
+ * `v2:flowdef:`), then `keys.bareKey` (pre-H1 bare `flowdef:`). The older
+ * no-flowdef key is deliberately unsafe and ignored.
+ * A hit on any safe tier is restored as a cache hit; we do NOT write-through (no
  * re-store under the new key) so the cache size stays stable and the legacy
  * entry ages out naturally. See docs/internal/cache-migration.md.
  */
@@ -2397,9 +2917,13 @@ function cachedPhase(cc, keys) {
     if (cc.prior && cc.prior.status === "done" && cc.prior.inputHash === keys.key) {
         return { ...cc.prior, status: "done", cacheHit: "run-only" };
     }
-    // 2. cross-run memoization (opt-in) — four-tier read-only fallback.
+    // 2. cross-run memoization (opt-in) — three safe read-only tiers.
     if (cc.scope === "cross-run") {
-        for (const k of [keys.key, keys.v2Key, keys.bareKey, keys.legacyKey]) {
+        // The pre-flow-definition legacy key is intentionally NOT read: it omits
+        // all structural identity and can return stale output after any semantic
+        // flow change. v2/bare remain safe because they include today's definition
+        // hash; old entries whose historical hash omitted new fields simply miss.
+        for (const k of [keys.key, keys.v2Key, keys.bareKey]) {
             const e = cc.store.get(k, cc.ttlMs);
             if (!e)
                 continue;
@@ -2484,12 +3008,8 @@ function defaultAgent(deps) {
  * JSON verdict object whose value is non-blocking (e.g. `{"verdict":"No issues
  * found"}`) is an *explicit* pass, not ambiguity, and still resolves to pass.
  */
-// `parseGateVerdict` is implemented in `deterministic.ts` (a pure seam a
-// future replay can import without dragging in the process-spawning runner).
-// It is imported at the top of this file and re-exported from the barrel.
-function asReason(v) {
-    return typeof v === "string" && v.trim() ? v.trim() : undefined;
-}
+// `parseGateVerdict` / `parseTournamentWinner` live in `deterministic.ts`
+// (pure seam for replay + event kernel). Re-exported via the barrel.
 /**
  * If a gate phase relies on free-text verdict parsing (no `output:"json"` +
  * `expect` contract) and its task does not already demand a `VERDICT:` marker,
@@ -2513,30 +3033,7 @@ function appendGateFormatSuffix(task, phase) {
         `End your response with exactly one line in this exact form (no Markdown, no bold, no extra words):\n` +
         `VERDICT: PASS\nor\nVERDICT: BLOCK`);
 }
-/**
- * Parse a judge's pick of the winning variant. Accepts JSON ({"winner":n} or
- * {"best":n}) or a `WINNER: n` line (last match wins). Clamps to [1, count].
- * Fail-open: an unreadable verdict defaults to variant 1 so the work is never
- * lost. Returns the 1-based index plus an optional reason.
- */
-export function parseTournamentWinner(output, count) {
-    const clamp = (n) => Math.min(Math.max(1, Math.floor(n)), Math.max(1, count));
-    const json = safeParse(output);
-    if (json && typeof json === "object") {
-        const o = json;
-        const raw = o.winner ?? o.best ?? o.choice;
-        const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
-        if (Number.isFinite(n))
-            return { winner: clamp(n), reason: asReason(o.reason) };
-    }
-    const matches = [...output.matchAll(WINNER_TOKEN_RE)];
-    if (matches.length) {
-        const n = Number(matches[matches.length - 1][1]);
-        if (Number.isFinite(n))
-            return { winner: clamp(n) };
-    }
-    return { winner: 1, reason: "no parseable winner; defaulted to variant 1" };
-}
+/* parseTournamentWinner lives in deterministic.ts (shared with event kernel). */
 /**
  * Best-effort invocation of the user-provided `persist` + `onProgress` callbacks.
  *
@@ -2615,9 +3112,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
@@ -2729,10 +3244,23 @@ opts = { dryRun: true }) {
         const changedUpstreams = depsFor(id).filter((u) => outputMoved.has(u));
         try {
             const ps = await executePhase(phase, newState, deps, newState.phases[id], noop, 0, execOpts);
+            if (ps.status === "failed") {
+                // Recompute is speculative. Preserve the last known-good row for the
+                // failed phase and every downstream phase, then stop. Mark the report
+                // aborted so callers cannot persist a partially refreshed graph.
+                rerun.push(id);
+                decisions.push({
+                    phaseId: id,
+                    outcome: "failed",
+                    reason: ps.error ?? "re-execution returned a failed phase",
+                });
+                aborted = true;
+                break;
+            }
             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
@@ -2756,11 +3284,16 @@ opts = { dryRun: true }) {
                 });
             }
         }
-        catch {
+        catch (error) {
             // A failing recompute phase is recorded as rerun (it was attempted).
             rerun.push(id);
-            outputMoved.add(id);
-            decisions.push({ phaseId: id, outcome: "failed", reason: "re-execution attempted but the phase failed" });
+            decisions.push({
+                phaseId: id,
+                outcome: "failed",
+                reason: `re-execution threw: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            aborted = true;
+            break;
         }
     }
     // Frontier-external phases were never touched — record them as reused.
@@ -2783,8 +3316,150 @@ 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) {
+        // Preserve a runner-advertised capability across the wrapper functions used
+        // by nested flow/context execution; those wrappers would otherwise erase a
+        // property attached to the original runTask function.
+        deps = { ...deps, usageAccounting: runnerUsageAccounting };
+    }
     try {
+        if (deps.usageAccounting === "unavailable" && def.budget) {
+            throw new Error(`Usage accounting is unavailable for this host; refusing budgeted flow '${def.name}' because its token/USD ceiling cannot be enforced`);
+        }
+        if (deps.usageAccounting === "tokens-only" && def.budget?.maxUSD !== undefined) {
+            throw new Error("This host reports tokens but not cost, so budget.maxUSD cannot be enforced. " +
+                "Use budget.maxTokens or a host with cost accounting.");
+        }
+        // S2 strangler (default OFF): all phase kinds may use the event kernel when enabled.
+        const { eventKernelEnabled, canUseEventKernel, runEventKernel } = await import("./exec/driver.js");
+        // Existing phase state requires the imperative cache/inputHash machinery to
+        // validate definition and idempotency before reuse. The event kernel does
+        // 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) && deps._cwdBoundary === undefined && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
+            if (!deps.runTask) {
+                throw new Error("event kernel requires RuntimeDeps.runTask");
+            }
+            return await runEventKernel(state, {
+                cwd: deps.cwd,
+                agents: deps.agents,
+                runTask: deps.runTask,
+                signal: deps.signal,
+                globalThinking: deps.globalThinking,
+                usageAccounting: deps.usageAccounting,
+                trace: deps.trace,
+                persist: deps.persist,
+                onProgress: deps.onProgress,
+                eventKernel: deps.eventKernel,
+                requestApproval: deps.requestApproval,
+                loadFlow: deps.loadFlow,
+                _stack: deps._stack,
+                _dynamic: deps._dynamic,
+            });
+        }
         return await runTaskflowLayers(state, deps);
     }
     catch (e) {
@@ -2806,6 +3481,31 @@ export async function executeTaskflow(state, deps) {
 }
 async function runTaskflowLayers(state, deps) {
     const def = state.def;
+    // Ownership migration must happen before ANY phase in the new definition is
+    // scheduled. Definition evolution may remove/rename ordinary phases as well
+    // as graft children; neither their terminal failure nor their usage may leak
+    // into the new run. Dynamic promoted state is intentionally cleared here too
+    // and is restored only by its owning expand phase (from its current result or
+    // cache). An id newly promoted to a real authored phase is preserved because
+    // it is present in `declaredPhaseIds` and the scheduler will validate/rerun it.
+    // Cleaning inside the expand phase would be too late: an unrelated authored
+    // phase may already have been scheduled and stale usage already counted.
+    const declaredPhaseIds = new Set(def.phases.map((p) => p.id));
+    // A pre-seeded state may intentionally supply an external dependency (for
+    // example an embedding host injects `src` and the definition starts at a map
+    // that depends on it). Those ids are part of the new definition's dependency
+    // contract even though they have no executable Phase row, so preserve them.
+    const externalDependencyIds = new Set(def.phases.flatMap((phase) => dependenciesOf(phase)).filter((id) => !declaredPhaseIds.has(id)));
+    for (const oldId of Object.keys(state.phases)) {
+        if (!declaredPhaseIds.has(oldId) && !externalDependencyIds.has(oldId))
+            delete state.phases[oldId];
+    }
+    for (const previous of Object.values(state.phases)) {
+        for (const oldId of Object.keys(previous.promotedPhases ?? {})) {
+            if (!declaredPhaseIds.has(oldId))
+                delete state.phases[oldId];
+        }
+    }
     const layers = topoLayers(def.phases);
     // Content-fingerprint the desugared definition ONCE per run and fold it into
     // every phase's cache key (overstory hash algorithm; see ./flowir/hash.ts).
@@ -2819,16 +3519,20 @@ async function runTaskflowLayers(state, deps) {
     // plane) is persisted for audit/provenance. The declared plane is also
     // derived fresh from `def` in recompute (so old runs get union semantics
     // too); the persisted copy is for display.
-    if (state.flowDefHash === undefined) {
-        try {
-            const ir = await compileTaskflowToIR(def);
-            state.flowDefHash = ir.hash ?? "failed";
-            state.declaredDeps = ir.meta.declaredDeps;
-            if (ir.errors.length) {
-                console.warn(`[taskflow] IR compile errors for '${def.name}': ${ir.errors.map((e) => e.message).join("; ")}`);
-            }
+    try {
+        const ir = await compileTaskflowToIR(def);
+        const nextHash = ir.hash ?? "failed";
+        if (state.flowDefHash !== nextHash) {
+            state.flowDefHash = nextHash;
+            state.phaseFingerprints = undefined;
         }
-        catch (e) {
+        state.declaredDeps = ir.meta.declaredDeps;
+        if (ir.errors.length) {
+            console.warn(`[taskflow] IR compile errors for '${def.name}': ${ir.errors.map((e) => e.message).join("; ")}`);
+        }
+    }
+    catch (e) {
+        if (state.flowDefHash === undefined) {
             // Fail-safe: warn loudly rather than silently degrading to the legacy
             // flowName-only key, which would reopen the cross-flow collision hole.
             console.warn(`[taskflow] flowDefHash failed for '${def.name}': ${e instanceof Error ? e.message : String(e)}. ` +
@@ -2875,7 +3579,11 @@ async function runTaskflowLayers(state, deps) {
             break;
         }
         // Phases within a layer have no inter-dependencies → run concurrently.
-        const layerConcurrency = Math.max(1, def.concurrency ?? 8);
+        // A usage report arrives only after a subagent call. With a declared hard
+        // budget, concurrent layer admission would let every sibling observe the
+        // same remaining allowance. Serialize admission so no additional call can
+        // begin after a previous call has exhausted the cap.
+        const layerConcurrency = def.budget ? 1 : Math.max(1, def.concurrency ?? 8);
         await mapWithConcurrencyLimit(layer, layerConcurrency, async (phase) => {
             // Snapshot prior state BEFORE marking running, so resume cache checks work.
             const prior = state.phases[phase.id];
@@ -2900,8 +3608,27 @@ async function runTaskflowLayers(state, deps) {
             else if (!depsSatisfied)
                 skipReason = join === "any" ? "All dependencies failed or were skipped" : "Upstream dependency not satisfied";
             if (skipReason) {
-                if (skipReason.startsWith("Budget exceeded"))
+                if (skipReason.startsWith("Budget exceeded")) {
                     budgetBlocked = true;
+                    // S1: budget-hit decision so fold/replay can re-tally under new caps.
+                    traceDecision(deps, state, phase.id, {
+                        type: "budget-hit",
+                        value: budgetReason || "budget",
+                        reason: skipReason,
+                    });
+                    // executePhase already flushed its phase-end batch. Flush this
+                    // post-completion decision too so FileTraceSink cannot strand it.
+                    traceFlush(deps, phase.id);
+                }
+                // Synthetic phase-start/end so fold sees a complete phase lifecycle.
+                traceEmit(deps, {
+                    ts: Date.now(),
+                    runId: state.runId,
+                    phaseId: phase.id,
+                    kind: "phase-start",
+                    dependencies: dependenciesOf(phase),
+                    optional: phase.optional === true,
+                });
                 state.phases[phase.id] = {
                     id: phase.id,
                     status: "skipped",
@@ -2909,6 +3636,15 @@ async function runTaskflowLayers(state, deps) {
                     endedAt: Date.now(),
                     usage: emptyUsage(),
                 };
+                traceEmit(deps, {
+                    ts: Date.now(),
+                    runId: state.runId,
+                    phaseId: phase.id,
+                    kind: "phase-end",
+                    status: "skipped",
+                    error: skipReason,
+                });
+                traceFlush(deps, phase.id);
                 safeEmit(deps, state);
                 return;
             }
@@ -2952,11 +3688,29 @@ async function runTaskflowLayers(state, deps) {
             // acceptable: budgetBlocked prevents cascading into subsequent layers.
             const ob = overBudget(state);
             if (ob.over) {
+                if (!budgetBlocked) {
+                    // First time we detect the ceiling after a phase completes.
+                    traceDecision(deps, state, phase.id, {
+                        type: "budget-hit",
+                        value: "budget",
+                        reason: ob.reason,
+                    });
+                    traceFlush(deps, phase.id);
+                }
                 budgetBlocked = true;
                 budgetReason = ob.reason;
             }
             safeEmit(deps, state);
         });
+        // The signal can flip while a layer is in flight. Checking only at the
+        // beginning of the next layer lets an abort during the final layer fall
+        // through to `completed` (notably when a non-cooperative race branch later
+        // reports success). Cancellation is terminal for this invocation: preserve
+        // the phase evidence gathered above, but classify the run as resumable.
+        if (deps.signal?.aborted) {
+            aborted = true;
+            break;
+        }
     }
     const fp = finalPhase(def.phases);
     let finalState = state.phases[fp.id];
@@ -2968,7 +3722,7 @@ async function runTaskflowLayers(state, deps) {
             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);
+    const anyFailed = Object.entries(state.phases).some(([id, p]) => p.status === "failed" && !byId.get(id)?.optional && !p.optional);
     state.status = aborted
         ? "paused"
         : gateBlocked || budgetBlocked