taskflow-core 0.2.0 → 0.2.1

package/dist/runtime.js

@@ -11,7 +11,7 @@
  */
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { coerceArray, evaluateCondition, interpolate, safeParse, tryEvaluateCondition } from "./interpolate.js";
+import { coerceArray, evaluateCondition, interpolate, interpolateValue, safeParse, tryEvaluateCondition } from "./interpolate.js";
 import { contractViolations } from "./contract.js";
 import { isFailed, isTransientError, mapWithConcurrencyLimit, PHASE_TIMEOUT_ABORT_GRACE_MS, sanitizeErrorMessage } from "./runner-core.js";
 /** Default runner used when no host injected one: fail loudly rather than
@@ -28,7 +28,7 @@ const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
 });
 export { PHASE_TIMEOUT_ABORT_GRACE_MS } from "./runner-core.js";
 import { aggregateUsage, emptyUsage } from "./usage.js";
-import { dependenciesOf, finalPhase, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, MAX_DYNAMIC_PHASES, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateTaskflow } from "./schema.js";
+import { 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 } from "./scorers.js";
 import { parseGateVerdict, overBudget as overBudgetCheck, parseTournamentWinner } from "./deterministic.js";
@@ -45,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). */
@@ -443,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 "";
@@ -482,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}`);
         }
     }
@@ -537,19 +548,85 @@ function spawnedOverBudget(state, local) {
  * two isolation-leak bugs in the 0.0.23 review).
  */
 function resolveEffCwd(deps, phase) {
-    return deps._cwdOverride ?? (isWorkspaceKeyword(phase.cwd) ? deps.cwd : phase.cwd ?? deps.cwd);
+    if (deps._cwdOverride)
+        return deps._cwdOverride;
+    if (!phase.cwd || isWorkspaceKeyword(phase.cwd))
+        return deps.cwd;
+    // Node resolves a relative spawn cwd against the Taskflow process cwd. That
+    // is not necessarily the invocation root, so anchor legacy literals here.
+    return path.resolve(deps.cwd, phase.cwd);
+}
+function flowTreeUsesCwdBridge(def, loadFlow, seenUses = new Set()) {
+    if (def.phases.some((phase) => cwdArgName(phase.cwd) !== undefined))
+        return true;
+    if (!loadFlow)
+        return false;
+    for (const phase of def.phases) {
+        if ((phase.type ?? "agent") !== "flow" || !phase.use)
+            continue;
+        if (seenUses.has(phase.use))
+            continue;
+        seenUses.add(phase.use);
+        try {
+            const child = loadFlow(phase.use);
+            if (child && flowTreeUsesCwdBridge(child, loadFlow, seenUses))
+                return true;
+        }
+        catch {
+            // Unknown is treated as capability-bearing: disable reuse, then let the
+            // normal phase execution path report the loader failure coherently.
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Freeze the saved-flow namespace for one top-level execution. Capability
+ * discovery and phase execution must observe the same definition, including
+ * the same loader error, or a mutable loader could introduce a bridge only
+ * after the root binding and cache policy were decided.
+ */
+function snapshotFlowLoader(deps) {
+    if (!deps.loadFlow || deps._flowLoaderSnapshot)
+        return deps;
+    const source = deps.loadFlow;
+    const snapshot = new Map();
+    const loadFlow = (name) => {
+        let entry = snapshot.get(name);
+        if (!entry) {
+            try {
+                const loaded = source(name);
+                // Loader-owned objects may be mutated asynchronously. Capability scan
+                // and execution operate on a detached structured snapshot, never the
+                // loader's live reference.
+                entry = { ok: true, value: loaded === undefined ? undefined : structuredClone(loaded) };
+            }
+            catch (error) {
+                entry = { ok: false, error };
+            }
+            snapshot.set(name, entry);
+        }
+        if (!entry.ok)
+            throw entry.error;
+        return entry.value;
+    };
+    return { ...deps, loadFlow, _flowLoaderSnapshot: snapshot };
+}
+function sameDirectoryIdentity(a, b) {
+    return !!a && !!b && a.canonicalPath === b.canonicalPath && a.device === b.device && a.inode === b.inode;
 }
 async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, deps, state, localSpawnUsage) {
     const stack = deps._stack ?? [];
     const inlineDepth = stack.filter((s) => s.startsWith("def:")).length;
     if (inlineDepth >= MAX_DYNAMIC_NESTING) {
-        return { output: `(spawned subflow rejected: nesting exceeded MAX_DYNAMIC_NESTING (${MAX_DYNAMIC_NESTING}))`, usage: emptyUsage() };
+        const error = `spawned subflow rejected: nesting exceeded MAX_DYNAMIC_NESTING (${MAX_DYNAMIC_NESTING})`;
+        return { output: `(${error})`, usage: emptyUsage(), failed: true, error };
     }
     const wrapped = normalizeInlineDef(subflowSpec, childNodeId);
     if (!wrapped)
-        return { output: "(spawned subflow is not a Taskflow / phases array)", usage: emptyUsage() };
+        return { output: "(spawned subflow is not a Taskflow / phases array)", usage: emptyUsage(), failed: true, error: "spawned subflow is not a Taskflow / phases array" };
     if (wrapped.phases.length === 0)
-        return { output: "(spawned subflow had zero phases — no-op)", usage: emptyUsage() };
+        return { output: "(spawned subflow had zero phases — no-op)", usage: emptyUsage(), failed: false };
     // Inner phases without their own agent inherit the assignment's defaultAgent.
     if (defaultAgent) {
         for (const p of wrapped.phases)
@@ -559,12 +636,15 @@ async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, d
     const spawnCwd = resolveEffCwd(deps, phase);
     const dynCwd = spawnCwd;
     const v = validateTaskflow(wrapped, { dynamic: true, cwd: dynCwd });
-    if (!v.ok)
-        return { output: `(spawned subflow failed validation: ${v.errors.join("; ")})`, usage: emptyUsage() };
+    if (!v.ok) {
+        const error = `spawned subflow failed validation: ${v.errors.join("; ")}`;
+        return { output: `(${error})`, usage: emptyUsage(), failed: true, error };
+    }
     const ver = verifyTaskflow({ name: wrapped.name, phases: wrapped.phases, budget: wrapped.budget, concurrency: wrapped.concurrency });
     if (!ver.ok) {
         const errs = ver.issues.filter((i) => i.severity === "error").map((i) => i.message);
-        return { output: `(spawned subflow failed verification: ${errs.join("; ")})`, usage: emptyUsage() };
+        const error = `spawned subflow failed verification: ${errs.join("; ")}`;
+        return { output: `(${error})`, usage: emptyUsage(), failed: true, error };
     }
     // The generated sub-flow gets only what remains after both already-folded
     // parent spend and siblings/ancestors in this still-running spawn batch.  USD
@@ -591,6 +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
@@ -606,16 +688,23 @@ async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, d
         // Sum every sub-phase's usage so the parent's budget guard sees spawn spend
         // (verdict Issue 2).
         const usage = aggregateUsage(Object.values(subResult.state.phases).map((p) => p.usage ?? emptyUsage()));
-        return { output: subResult.finalOutput ?? "", usage };
+        return {
+            output: subResult.finalOutput ?? "",
+            usage,
+            failed: !subResult.ok,
+            ...(!subResult.ok ? { error: sanitizeErrorMessage(subResult.finalOutput || "spawned subflow failed") } : {}),
+        };
     }
     catch (e) {
-        return { output: `(spawned subflow failed: ${e instanceof Error ? e.message : String(e)})`, usage: emptyUsage() };
+        const error = sanitizeErrorMessage(e instanceof Error ? e.message : String(e));
+        return { output: `(spawned subflow failed: ${error})`, usage: emptyUsage(), failed: true, error };
     }
 }
 async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps, state, run, ledger = { usage: emptyUsage() }) {
     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);
@@ -635,11 +724,43 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
                 out = sub.output;
                 usages.push(sub.usage);
                 ledger.usage = aggregateUsage([ledger.usage, sub.usage]);
-                setNodeStatus(ctxDir, childNodeId, "done");
+                if (sub.failed)
+                    errors.push(sub.error ?? `spawned subflow ${childNodeId} failed`);
+                setNodeStatus(ctxDir, childNodeId, sub.failed ? "failed" : "done");
             }
             else {
-                const r = await run(spawnCwd, deps.agents, agentName, a.task ?? "", { model: phase.model, thinking: phase.thinking, tools: phase.tools, cwd: spawnCwd, signal: deps.signal, ctxDir, nodeId: childNodeId }, deps.globalThinking);
+                const task = a.task ?? "";
+                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 (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]);
@@ -652,19 +773,27 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
                     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
@@ -732,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 {
@@ -748,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}`;
@@ -800,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);
     };
@@ -809,7 +1092,7 @@ 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 (phase.when !== undefined && opts?.whenPrechecked !== true) {
         const whenResult = evaluateCondition(phase.when, ctx);
         traceDecision(deps, state, phase.id, {
             type: "when-guard",
@@ -827,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.
@@ -851,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,
@@ -869,17 +1158,33 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         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.
     //
@@ -911,6 +1216,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // AbortController chains: run signal + optional extra (race cancel) + phase timeout.
             // Deterministic: a timed-out call is never retried (would double-spend).
             let timedOut = false;
+            let terminalCommitted = false;
             let timer;
             let forceReturnTimer;
             const removers = [];
@@ -936,10 +1242,21 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 }
             }
             try {
-                const invocation = baseRun(agentName, task, onLive, ctxNodeId, callSignal);
+                const onTerminalCommit = () => {
+                    if (timedOut)
+                        return;
+                    terminalCommitted = true;
+                    if (timer) {
+                        clearTimeout(timer);
+                        timer = undefined;
+                    }
+                };
+                const invocation = baseRun(agentName, task, onLive, ctxNodeId, callSignal, onTerminalCommit);
                 if (phaseTimeoutMs && timeoutController) {
                     const timeoutFallback = new Promise((resolve) => {
                         timer = setTimeout(() => {
+                            if (terminalCommitted)
+                                return;
                             timedOut = true;
                             timeoutController?.abort();
                             forceReturnTimer = setTimeout(() => resolve({
@@ -952,6 +1269,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                                 stopReason: "error",
                                 errorMessage: `Phase runner did not stop within ${PHASE_TIMEOUT_ABORT_GRACE_MS}ms after abort`,
                                 phaseTimeout: true,
+                                completionSource: "phase-timeout",
                             }), PHASE_TIMEOUT_ABORT_GRACE_MS);
                         }, phaseTimeoutMs);
                     });
@@ -979,12 +1297,18 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     stopReason: "error",
                     errorMessage: `Phase timed out after ${phaseTimeoutMs}ms (subagent aborted)`,
                     phaseTimeout: true,
+                    completionSource: "phase-timeout",
                 };
                 usages.push(last.usage);
                 traceEmit(deps, {
                     ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "subagent-call",
                     input: { agent: agentName, model: phase.model, task, preRead, nodePath: ctxNodeId ?? phase.id, attempt },
-                    output: { text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason },
+                    output: {
+                        text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason,
+                        completionSource: last.completionSource,
+                        reapedAfterTerminal: last.reapedAfterTerminal,
+                        terminalGraceMs: last.terminalGraceMs,
+                    },
                 });
                 traceFlush(deps, phase.id);
                 break;
@@ -1015,7 +1339,12 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             traceEmit(deps, {
                 ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "subagent-call",
                 input: { agent: agentName, model: phase.model, task, preRead, nodePath: ctxNodeId ?? phase.id, attempt },
-                output: { text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason },
+                output: {
+                    text: last.output, model: last.model, usage: last.usage, stopReason: last.stopReason,
+                    completionSource: last.completionSource,
+                    reapedAfterTerminal: last.reapedAfterTerminal,
+                    terminalGraceMs: last.terminalGraceMs,
+                },
             });
             traceFlush(deps, phase.id);
             if (!isFailed(last))
@@ -1023,6 +1352,20 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // Stop retrying on abort (run-level or race cancel) or once over budget.
             if (deps.signal?.aborted || extraSignal?.aborted || overBudget(state).over)
                 break;
+            if (deps._workspaceBinding) {
+                // A failed RW-capability attempt has an unknown filesystem outcome and
+                // is durably marked dirty. Retrying it cannot be proven idempotent until
+                // workspace snapshots/restoration exist, so preserve the first failure
+                // instead of replacing it with a later TFWS_RESOURCE_DIRTY refusal.
+                const requestedRetry = (retry?.max ?? 0) > 0 || isTransientError(last);
+                if (requestedRetry && last.workspaceMutationStarted) {
+                    last = {
+                        ...last,
+                        errorMessage: `${last.errorMessage ?? last.stderr ?? "workspace execution failed"}\nTFWS_RETRY_UNSAFE: retry suppressed because the prior read-write attempt may have mutated the workspace; reconcile before a new attempt`,
+                    };
+                }
+                break;
+            }
             // Decide whether THIS failure warrants another attempt. Explicit retry
             // policy covers all failures up to its cap; the transient fallback covers
             // only retryable provider errors. A non-transient failure with no explicit
@@ -1224,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;
@@ -1468,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)
@@ -1547,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]);
@@ -1575,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)
@@ -1637,7 +1989,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const SCRIPT_TIMEOUT_MS = phase.timeout ?? 60_000;
         const reads = readRefs.length ? readRefsToReads(readRefs, state) : undefined;
         try {
-            const result = await runScriptCommand({
+            const invoke = () => runScriptCommand({
                 interpRunText,
                 arrayForm: Array.isArray(cmd),
                 cwd: effCwd,
@@ -1645,6 +1997,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 stdinInput,
                 timeoutMs: SCRIPT_TIMEOUT_MS,
             });
+            const result = deps._workspaceBinding
+                ? await deps._workspaceBinding.runScript({ unitId: phase.id, signal: deps.signal, invoke })
+                : await invoke();
             const ps = scriptResultToPhaseState(phase, result, {
                 inputHash,
                 timeoutMs: SCRIPT_TIMEOUT_MS,
@@ -1961,16 +2316,29 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         // Resolve sub-flow args (interpolate string values), then apply declared defaults.
         const provided = {};
         for (const [k, v] of Object.entries(phase.with ?? {})) {
-            provided[k] = typeof v === "string" ? interpolate(v, ctx).text : v;
+            provided[k] = interpolateValue(v, ctx);
         }
         const subArgs = resolveArgs(subDef, provided);
+        if (deps._dynamic === true) {
+            const dynamicChild = validateTaskflow(subDef, { dynamic: true, cwd: effCwd, args: subArgs });
+            if (!dynamicChild.ok) {
+                return failPhase(phase.id, `dynamic nested flow '${subDef.name}' is invalid: ${dynamicChild.errors.join("; ")}`);
+            }
+        }
+        // Re-check the exact loaded definition at the cache boundary. A loader may
+        // change between the root pre-scan and this phase (or return aliases), and
+        // a bridge-bearing child must never be skipped by a cached parent result.
+        const nestedBridgeTree = flowTreeUsesCwdBridge(subDef, deps.loadFlow);
+        if (nestedBridgeTree)
+            deps._disableCache = true;
+        const flowCc = nestedBridgeTree ? { ...cc, scope: "off" } : cc;
         // Every sub-flow cache identity includes the resolved definition. A saved
         // flow's name alone is insufficient: its contents can change without the
         // parent definition moving.
         const flowIdentity = `${hasDef ? "def" : "flow"}:${name}:${JSON.stringify(subDef)}`;
-        const ck = cacheKeys(cc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
+        const ck = cacheKeys(flowCc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
         const inputHash = ck.key;
-        const cached = cachedPhase(cc, ck);
+        const cached = cachedPhase(flowCc, ck);
         if (cached) {
             if (type === "expand" && expandMode === "graft" && cached.promotedPhases) {
                 const promo = promoteGraftPhases(state, cached.promotedPhases);
@@ -2012,6 +2380,8 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // phases without an explicit cwd derive their subagents from the
             // flow's cwd (not the caller's cwd).
             cwd: effCwd,
+            _cacheCwdIdentity: phase.cwd !== undefined || deps._cacheCwdIdentity !== undefined ? effCwd : undefined,
+            _dynamic: hasDef || deps._dynamic === true ? true : undefined,
             // The workspace override applies only to THIS flow phase, not to the
             // nested sub-phases (each resolves its own cwd). Clear it so the child
             // phases don't all inherit this phase's isolated dir as an override.
@@ -2040,6 +2410,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             },
         });
         const sp = Object.values(subState.phases);
+        const nestedFailure = sp.find((nested) => nested.status === "failed")?.error;
         // expand graft promote — pure helper (see runtime/phases/expand.ts)
         const warnings = [];
         let graftPromotedIds = [];
@@ -2073,7 +2444,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 running: 0,
                 failed: sp.filter((p) => p.status === "failed").length,
             },
-            error: subResult.ok ? undefined : `sub-flow '${name}' ${subResult.state.status}`,
+            error: subResult.ok
+                ? undefined
+                : `sub-flow '${name}' ${subResult.state.status}${nestedFailure ? `: ${nestedFailure}` : ""}`,
             inputHash,
             reads: readRefsToReads(readRefs, state),
             endedAt: Date.now(),
@@ -2082,7 +2455,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 ? { promotedPhases: Object.fromEntries(graftPromotedIds.map((id) => [id, { ...subState.phases[id] }])) }
                 : {}),
         };
-        recordCache(cc, flowPs);
+        recordCache(flowCc, flowPs);
         return flowPs;
     }
     // loop-until-done: run the body repeatedly until `until` is truthy, the output
@@ -2503,6 +2876,7 @@ export function cacheKeys(cc, baseParts) {
         `agent-scope:${cc.agentScope ?? "user"}`,
         `context-sharing:${cc.contextSharing === true ? "1" : "0"}`,
         `agents:${cc.agentDefinitions ?? ""}`,
+        ...(cc.executionCwd ? [`cwd:${cc.executionCwd}`] : []),
     ];
     const fold = (parts) => cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
     // Per-phase sub-fingerprint; falls back to the whole-flow hash when absent
@@ -2738,9 +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
@@ -2868,7 +3260,7 @@ opts = { dryRun: true }) {
             newState.phases[id] = ps;
             // A phase counts as "rerun" if it was a forced seed OR its result moved;
             // otherwise it hit its cache (inputHash unchanged) → early cutoff.
-            if (isSeed || ps.inputHash !== before) {
+            if (isSeed || !ps.cacheHit || ps.inputHash !== before) {
                 rerun.push(id);
                 outputMoved.add(id);
                 decisions.push(isSeed
@@ -2924,7 +3316,106 @@ opts = { dryRun: true }) {
     };
 }
 export async function executeTaskflow(state, deps) {
+    deps = snapshotFlowLoader(deps);
     const def = state.def;
+    // Normalize defaults at the engine boundary too. Adapters already do this,
+    // but direct Core callers, resume, and detached execution must behave the same.
+    state.args = resolveArgs(def, state.args);
+    const invocationErrors = validateInvocationArgs(def, state.args);
+    if (invocationErrors.length > 0) {
+        state.status = "failed";
+        safeEmit(deps, state);
+        return {
+            state,
+            finalOutput: `Taskflow '${def.name}' invocation is invalid: ${invocationErrors.join("; ")}`,
+            ok: false,
+            totalUsage: emptyUsage(),
+        };
+    }
+    if (deps._dynamic === true) {
+        const dynamicValidation = validateTaskflow(def, { dynamic: true, cwd: deps.cwd, args: state.args });
+        if (!dynamicValidation.ok) {
+            state.status = "failed";
+            safeEmit(deps, state);
+            return {
+                state,
+                finalOutput: `Dynamic taskflow '${def.name}' is invalid: ${dynamicValidation.errors.join("; ")}`,
+                ok: false,
+                totalUsage: emptyUsage(),
+            };
+        }
+    }
+    // A cwd bridge carries compatibility read-write authority. Until workspace
+    // state restoration exists, output-only cache hits could skip required file
+    // mutations or let downstream phases observe stale files. Disable cache and
+    // within-run resume reuse across the complete reachable flow tree.
+    const bridgeTree = flowTreeUsesCwdBridge(def, deps.loadFlow);
+    // Persisted binding is a permanent taint bit: saved-flow definitions can
+    // change between resumes, but prior outputs may already depend on filesystem
+    // mutations. Never regain cache/rebind privileges merely because the current
+    // snapshot no longer declares the bridge.
+    const bridgeTainted = bridgeTree || state.cwdRootBinding !== undefined;
+    if (bridgeTainted) {
+        const invocationRoot = directoryIdentity(deps.cwd);
+        const statePathRoot = directoryIdentity(state.cwd);
+        const launchRoot = state.invocationRootSnapshot;
+        const recordedRoot = state.cwdRootBinding;
+        const executablePhaseIds = new Set(def.phases.map((phase) => phase.id));
+        const hasExecutablePriorState = Object.keys(state.phases).some((id) => executablePhaseIds.has(id));
+        // Pre-seeded external dependencies are inputs, not evidence that a bridge
+        // phase previously executed without a persisted root binding. Conversely,
+        // a host's launch snapshot proves root continuity, not prior bridge
+        // authorization: adding a bridge after ordinary phases ran still fails.
+        const isLegacyResume = bridgeTree && recordedRoot === undefined && hasExecutablePriorState;
+        if (isLegacyResume ||
+            !sameDirectoryIdentity(statePathRoot, invocationRoot) ||
+            (launchRoot !== undefined && !sameDirectoryIdentity(launchRoot, invocationRoot)) ||
+            (recordedRoot !== undefined && !sameDirectoryIdentity(recordedRoot, invocationRoot))) {
+            state.status = "failed";
+            safeEmit(deps, state);
+            return {
+                state,
+                finalOutput: `Taskflow '${def.name}' cwd-bridge invocation root does not match the run's persisted root; start a new run instead of rebinding on resume`,
+                ok: false,
+                totalUsage: emptyUsage(),
+            };
+        }
+        state.cwdRootBinding ??= invocationRoot;
+        // Freeze the invocation root to the canonical identity we just bound. In
+        // particular, do not resolve phase cwd through a caller-provided symlink a
+        // second time after the root-binding check.
+        if (invocationRoot)
+            deps = { ...deps, cwd: invocationRoot.canonicalPath };
+    }
+    if (!deps._disableCache && bridgeTainted) {
+        deps = { ...deps, _disableCache: true };
+    }
+    // The explicit 0.2.1 resolve-only opt-in uses a W1a-compatible partial
+    // control/durability scaffold. This does not upgrade its assurance: the
+    // session is deliberately labelled resolve-only and no OS sandbox claim is
+    // made. A native session must come from an exact approved host baseline cell.
+    if (bridgeTree && deps.cwdBridgeMode === "resolve-only" && !deps.workspaceSession) {
+        try {
+            deps = {
+                ...deps,
+                workspaceSession: await createResolveOnlyWorkspaceSession({
+                    invocationRoot: deps.cwd,
+                    controlDirectory: deps.workspaceControlDirectory,
+                    signal: deps.signal,
+                }),
+            };
+        }
+        catch (error) {
+            state.status = "failed";
+            safeEmit(deps, state);
+            return {
+                state,
+                finalOutput: `Taskflow '${def.name}' workspace capability initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+                ok: false,
+                totalUsage: emptyUsage(),
+            };
+        }
+    }
     const runnerUsageAccounting = deps.runTask
         ?.usageAccounting;
     if (!deps.usageAccounting && runnerUsageAccounting) {
@@ -2948,7 +3439,7 @@ export async function executeTaskflow(state, deps) {
         // not yet persist compatible input hashes, so it must never blindly trust a
         // prior `done` row.
         const hasPriorState = Object.keys(state.phases).length > 0;
-        if (eventKernelEnabled(deps) && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
+        if (eventKernelEnabled(deps) && deps._cwdBoundary === undefined && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
             if (!deps.runTask) {
                 throw new Error("event kernel requires RuntimeDeps.runTask");
             }
@@ -2966,6 +3457,7 @@ export async function executeTaskflow(state, deps) {
                 requestApproval: deps.requestApproval,
                 loadFlow: deps.loadFlow,
                 _stack: deps._stack,
+                _dynamic: deps._dynamic,
             });
         }
         return await runTaskflowLayers(state, deps);