@exellix/ai-tasks 8.1.16 → 8.2.0

package/dist/core/task-sdk.js

@@ -6,6 +6,7 @@ import { buildExecutionStrategyRequestPayload, runOptimizerFuncx, runPlannerFunc
 import { resolveSafeExecutionStrategyCatalogDefaultFunctionId } from "../execution-strategies/executionStrategyCatalogMetadata.js";
 import { SYNTHESIZED_CONTEXT } from "../types/index.js";
 import { runAuditPostStep } from "../post-steps/audit/runAudit.js";
+import { buildRunTaskResultMetaFromModelId } from "../invocation/buildRunTaskResultMeta.js";
 import { runPolishPostStep } from "../post-steps/polish/runPolish.js";
 import { getLocalTask } from "../localTasks/registry.js";
 import { registerBuiltInLocalTasks } from "../localTasks/index.js";
@@ -16,6 +17,7 @@ import { DebugLogAbstract, fieldEvidence } from "@x12i/logxer";
 import { configureFuncxLogging } from "@x12i/funcx";
 import { AI_TASKS_DIAGNOSTIC_CODES } from "../logxer/aiTasksDiagnosticCodes.js";
 import { patchRunTaskLogContext, runAiTasksWithObservabilityContext, } from "../logxer/aiTasksLogContext.js";
+import { logAndEnrichRunTaskFailure } from "../observability/logRunTaskFailure.js";
 import { getAiTasksLogxer } from "../logxer/packageLogxers.js";
 import { assertRequiredRunSkillCorrelation } from "../utils/assertRequiredRunSkillCorrelation.js";
 import { compileTaskConfigurationOnRunTaskRequest } from "../compile/compileTaskConfiguration.js";
@@ -449,183 +451,165 @@ export class WorexClientTasks {
             };
         };
         return runAiTasksWithObservabilityContext({ logging: this.stackLogging }, async () => {
-            // `@exellix/ai-skills` requires stable ids on each gateway request; callers may omit for simple runs.
-            const taskId = input.taskId?.trim() ? input.taskId : randomUUID();
-            const jobId = input.jobId?.trim() ? input.jobId : randomUUID();
-            input.taskId = taskId;
-            input.jobId = jobId;
-            // Optional activix tracking (non-fatal).
-            const ax = await getActivixClient().catch(() => null);
-            const correlationId = ax ? taskId : undefined;
-            patchRunTaskLogContext({
-                jobId,
-                taskId,
-                correlationId,
-                graphId: input.graphId,
-                nodeId: input.nodeId,
-            });
-            const coreSkillId = input.coreSkillId;
-            const upstreamIdentity = isRecord(input.identity) ? input.identity : undefined;
-            const executingSkillId = coreSkillId ?? input.skillKey;
-            const effectiveIdentity = {
-                ...(upstreamIdentity ?? {}),
-                ...(upstreamIdentity?.taskId ? {} : { taskId }),
-                ...(upstreamIdentity?.skillId ? {} : { skillId: executingSkillId }),
-            };
-            const normalizedSmartInput = input.smartInput !== undefined && input.smartInput !== null
-                ? normalizeSmartInputConfig(input.smartInput)
-                : undefined;
-            let request = withDefaultDecisionValidation({
-                ...input,
-                identity: effectiveIdentity,
-                ...(normalizedSmartInput !== undefined ? { smartInput: normalizedSmartInput } : {}),
-            });
-            let xynthesizedPatchAccumulator;
-            const knobs = resolveRunTaskRuntimeKnobs(request);
-            const baseTraceMeta = () => ({
-                jobId,
-                taskId,
+            const failContext = () => ({
                 skillKey: input.skillKey,
-                executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
-                narrixMode: knobs.narrixMode,
-                agentId: input.agentId,
+                jobId: input.jobId,
+                taskId: input.taskId,
                 graphId: input.graphId,
                 nodeId: input.nodeId,
-                prevNodeId: input.prevNodeId,
-                masterSkillId: input.masterSkillId,
-                masterSkillActivityId: input.masterSkillActivityId,
-                hasPipeline: Array.isArray(input.executionPipeline) && input.executionPipeline.length > 0,
-                hasNarrix: !!input.narrix,
-                hasNarrixInput: !!input.narrixInput,
+                agentId: input.agentId,
+                modelConfig: input.modelConfig,
             });
-            const modelUsedFromResult = (result) => {
-                if (!result || typeof result !== "object")
-                    return undefined;
-                const r = result;
-                const candidates = [
-                    r?.metadata?.modelUsed,
-                    r?.metadata?.model,
-                    r?.gatewayResponse?.model,
-                    r?.enhancedResponse?.model,
-                    r?.model,
-                ];
-                const found = candidates.find((x) => typeof x === "string" && x.trim().length > 0);
-                return typeof found === "string" ? found : undefined;
-            };
-            const finalize = (result) => {
-                const downstreamIdentity = extractDownstreamIdentity(result);
-                const identityToReturn = downstreamIdentity ??
-                    (upstreamIdentity ? effectiveIdentity : undefined);
-                if (identityToReturn) {
-                    result.identity = identityToReturn;
-                    result.metadata = { ...(result.metadata ?? {}), identity: identityToReturn };
-                }
-                const smartInputRenderResult = extractSmartInputRenderResult(result);
-                if (smartInputRenderResult) {
-                    result.smartInputRenderResult = smartInputRenderResult;
-                }
-                result.metadata = {
-                    ...result.metadata,
+            try {
+                // `@exellix/ai-skills` requires stable ids on each gateway request; callers may omit for simple runs.
+                const taskId = input.taskId?.trim() ? input.taskId : randomUUID();
+                const jobId = input.jobId?.trim() ? input.jobId : randomUUID();
+                input.taskId = taskId;
+                input.jobId = jobId;
+                // Optional activix tracking (non-fatal).
+                const ax = await getActivixClient().catch(() => null);
+                const correlationId = ax ? taskId : undefined;
+                patchRunTaskLogContext({
+                    jobId,
                     taskId,
-                    ...(coreSkillId ? { skillId: coreSkillId } : {}),
-                    identityPresent: (input.identity !== undefined),
-                    ...(smartInputRenderResult ? { smartInputRenderResult } : {}),
+                    correlationId,
+                    graphId: input.graphId,
+                    nodeId: input.nodeId,
+                });
+                const coreSkillId = input.coreSkillId;
+                const upstreamIdentity = isRecord(input.identity) ? input.identity : undefined;
+                const executingSkillId = coreSkillId ?? input.skillKey;
+                const effectiveIdentity = {
+                    ...(upstreamIdentity ?? {}),
+                    ...(upstreamIdentity?.taskId ? {} : { taskId }),
+                    ...(upstreamIdentity?.skillId ? {} : { skillId: executingSkillId }),
                 };
-                const patchJob = xynthesizedPatchAccumulator?.job && Object.keys(xynthesizedPatchAccumulator.job).length > 0;
-                const patchTask = xynthesizedPatchAccumulator?.task && Object.keys(xynthesizedPatchAccumulator.task).length > 0;
-                const patchExecution = xynthesizedPatchAccumulator?.execution &&
-                    Object.keys(xynthesizedPatchAccumulator.execution).length > 0;
-                if (patchJob || patchTask || patchExecution) {
-                    result.xynthesizedPatch = xynthesizedPatchAccumulator;
-                }
-                return result;
-            };
-            const hasPipeline = Array.isArray(input.executionPipeline) && input.executionPipeline.length > 0;
-            const hasNarrix = !!input.narrix;
-            const hasNarrixInput = !!input.narrixInput;
-            // Activix 6+: correlation + task identity belong in `runContext`, not a parallel top-level `identity` field.
-            const runContext = {
-                ...effectiveIdentity,
-                sessionId: taskId,
-            };
-            const baseMeta = {
-                skillKey: input.skillKey,
-                executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
-                narrixMode: knobs.narrixMode,
-                jobId: input.jobId,
-                agentId: input.agentId,
-                graphId: input.graphId,
-                nodeId: input.nodeId,
-                prevNodeId: input.prevNodeId,
-                masterSkillId: input.masterSkillId,
-                masterSkillActivityId: input.masterSkillActivityId,
-                runContext,
-                hasPipeline,
-                hasNarrix,
-                hasNarrixInput,
-            };
-            const runDirect = async (req, options) => {
-                const traceTask = {
-                    taskType: "ai-task",
-                    details: "direct execution (skills/gateway)",
-                    metadata: {
-                        ...baseTraceMeta(),
-                        phase: "direct",
-                        overrideContextProvided: options?.overrideContext !== undefined,
-                        captureContextProvided: options?.captureContext !== undefined,
-                        synthesisContextAuthoritative: options?.synthesisContextAuthoritative === true,
-                        ...(traceCollector
-                            ? {
-                                smartInput: {
-                                    paths: req.smartInput?.paths ?? [],
-                                },
-                            }
-                            : {}),
-                    },
+                const normalizedSmartInput = input.smartInput !== undefined && input.smartInput !== null
+                    ? normalizeSmartInputConfig(input.smartInput)
+                    : undefined;
+                let request = withDefaultDecisionValidation({
+                    ...input,
+                    identity: effectiveIdentity,
+                    ...(normalizedSmartInput !== undefined ? { smartInput: normalizedSmartInput } : {}),
+                });
+                let xynthesizedPatchAccumulator;
+                const knobs = resolveRunTaskRuntimeKnobs(request);
+                const baseTraceMeta = () => ({
+                    jobId,
+                    taskId,
+                    skillKey: input.skillKey,
+                    executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                    narrixMode: knobs.narrixMode,
+                    agentId: input.agentId,
+                    graphId: input.graphId,
+                    nodeId: input.nodeId,
+                    prevNodeId: input.prevNodeId,
+                    masterSkillId: input.masterSkillId,
+                    masterSkillActivityId: input.masterSkillActivityId,
+                    hasPipeline: Array.isArray(input.executionPipeline) && input.executionPipeline.length > 0,
+                    hasNarrix: !!input.narrix,
+                    hasNarrixInput: !!input.narrixInput,
+                });
+                const modelUsedFromResult = (result) => {
+                    if (!result || typeof result !== "object")
+                        return undefined;
+                    const r = result;
+                    const candidates = [
+                        r?.metadata?.modelUsed,
+                        r?.metadata?.model,
+                        r?.gatewayResponse?.model,
+                        r?.enhancedResponse?.model,
+                        r?.model,
+                    ];
+                    const found = candidates.find((x) => typeof x === "string" && x.trim().length > 0);
+                    return typeof found === "string" ? found : undefined;
                 };
-                return traceWrap(traceCollector, traceTask, async () => withPhaseRecord({
-                    ax,
-                    correlationId,
-                    phase: "direct",
-                    meta: {
-                        ...baseMeta,
-                        outer: activixOuterTier({
-                            kind: "runTask.request",
-                            skillKey: req.skillKey,
-                            executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
-                            jobId: req.jobId,
-                            agentId: req.agentId,
-                            graphId: req.graphId,
-                            nodeId: req.nodeId,
-                            masterSkillId: req.masterSkillId,
-                            masterSkillActivityId: req.masterSkillActivityId,
-                            includeContextInPrompt: req.includeContextInPrompt === true,
-                            hasPipeline: Array.isArray(req.executionPipeline) && req.executionPipeline.length > 0,
-                            hasNarrix: !!req.narrix,
-                            hasNarrixInput: !!req.narrixInput,
-                            input: summarizeForOuter(req.input, 4_000),
-                        }, null, { phase: "direct" }),
-                        // pipeline MAIN vs DIRECT is still tracked as the same phase label ("direct")
-                        hasPipeline: !!req.executionPipeline,
-                        hasNarrix: !!req.narrix,
-                        hasNarrixInput: !!req.narrixInput,
-                        overrideContextProvided: options?.overrideContext !== undefined,
-                        captureContextProvided: options?.captureContext !== undefined,
-                        synthesisContextAuthoritative: options?.synthesisContextAuthoritative === true,
-                    },
-                    fn: async () => this._executeDirect(req, {
-                        ...options,
-                        validationCorrelationId: taskId,
-                        traceCollector,
-                    }),
-                    onSuccessUpdates: (result) => {
-                        const steps = result?.intermediateSteps;
-                        return {
-                            instructionVersion: result?.metadata?.instructionVersion,
-                            activityId: result?.metadata?.activityId,
-                            durationMs: result?.metadata?.durationMs,
-                            hasIntermediateSteps: Array.isArray(steps) && steps.length > 0,
-                            stepCount: Array.isArray(steps) ? steps.length : undefined,
+                const finalize = (result) => {
+                    const downstreamIdentity = extractDownstreamIdentity(result);
+                    const identityToReturn = downstreamIdentity ??
+                        (upstreamIdentity ? effectiveIdentity : undefined);
+                    if (identityToReturn) {
+                        result.identity = identityToReturn;
+                        result.metadata = { ...(result.metadata ?? {}), identity: identityToReturn };
+                    }
+                    const smartInputRenderResult = extractSmartInputRenderResult(result);
+                    if (smartInputRenderResult) {
+                        result.smartInputRenderResult = smartInputRenderResult;
+                    }
+                    const resolvedModelForMeta = modelUsedFromResult(result);
+                    const invocationMeta = buildRunTaskResultMetaFromModelId(resolvedModelForMeta, {
+                        requestId: typeof result?.metadata?.requestId === "string"
+                            ? result.metadata.requestId
+                            : typeof result?.metadata?.activityId === "string"
+                                ? result.metadata.activityId
+                                : undefined,
+                    });
+                    result.metadata = {
+                        ...result.metadata,
+                        taskId,
+                        ...(coreSkillId ? { skillId: coreSkillId } : {}),
+                        identityPresent: (input.identity !== undefined),
+                        ...(smartInputRenderResult ? { smartInputRenderResult } : {}),
+                        ...(invocationMeta ?? {}),
+                    };
+                    const patchJob = xynthesizedPatchAccumulator?.job && Object.keys(xynthesizedPatchAccumulator.job).length > 0;
+                    const patchTask = xynthesizedPatchAccumulator?.task && Object.keys(xynthesizedPatchAccumulator.task).length > 0;
+                    const patchExecution = xynthesizedPatchAccumulator?.execution &&
+                        Object.keys(xynthesizedPatchAccumulator.execution).length > 0;
+                    if (patchJob || patchTask || patchExecution) {
+                        result.xynthesizedPatch = xynthesizedPatchAccumulator;
+                    }
+                    return result;
+                };
+                const hasPipeline = Array.isArray(input.executionPipeline) && input.executionPipeline.length > 0;
+                const hasNarrix = !!input.narrix;
+                const hasNarrixInput = !!input.narrixInput;
+                // Activix 6+: correlation + task identity belong in `runContext`, not a parallel top-level `identity` field.
+                const runContext = {
+                    ...effectiveIdentity,
+                    sessionId: taskId,
+                };
+                const baseMeta = {
+                    skillKey: input.skillKey,
+                    executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                    narrixMode: knobs.narrixMode,
+                    jobId: input.jobId,
+                    agentId: input.agentId,
+                    graphId: input.graphId,
+                    nodeId: input.nodeId,
+                    prevNodeId: input.prevNodeId,
+                    masterSkillId: input.masterSkillId,
+                    masterSkillActivityId: input.masterSkillActivityId,
+                    runContext,
+                    hasPipeline,
+                    hasNarrix,
+                    hasNarrixInput,
+                };
+                const runDirect = async (req, options) => {
+                    const traceTask = {
+                        taskType: "ai-task",
+                        details: "direct execution (skills/gateway)",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "direct",
+                            overrideContextProvided: options?.overrideContext !== undefined,
+                            captureContextProvided: options?.captureContext !== undefined,
+                            synthesisContextAuthoritative: options?.synthesisContextAuthoritative === true,
+                            ...(traceCollector
+                                ? {
+                                    smartInput: {
+                                        paths: req.smartInput?.paths ?? [],
+                                    },
+                                }
+                                : {}),
+                        },
+                    };
+                    return traceWrap(traceCollector, traceTask, async () => withPhaseRecord({
+                        ax,
+                        correlationId,
+                        phase: "direct",
+                        meta: {
+                            ...baseMeta,
                             outer: activixOuterTier({
                                 kind: "runTask.request",
                                 skillKey: req.skillKey,
@@ -641,116 +625,75 @@ export class WorexClientTasks {
                                 hasNarrix: !!req.narrix,
                                 hasNarrixInput: !!req.narrixInput,
                                 input: summarizeForOuter(req.input, 4_000),
-                            }, {
-                                kind: "runTask.response",
-                                skillKey: result?.skillKey,
-                                // Keep this intentionally small; rawText / flexMd payloads can be huge.
-                                metadata: summarizeForOuter(result?.metadata, 4_000),
-                                parsed: summarizeForOuter(result?.parsed, 8_000),
-                            }, { phase: "direct" }),
-                        };
-                    },
-                }), (result) => {
-                    const modelUsed = modelUsedFromResult(result);
-                    const r = result;
-                    return {
-                        modelUsed: modelUsed ?? null,
-                        metadata: {
-                            activityId: r?.metadata?.activityId,
-                            instructionVersion: r?.metadata?.instructionVersion,
-                            durationMs: r?.metadata?.durationMs,
-                            outputValidation: r?.metadata?.outputValidation,
+                            }, null, { phase: "direct" }),
+                            // pipeline MAIN vs DIRECT is still tracked as the same phase label ("direct")
+                            hasPipeline: !!req.executionPipeline,
+                            hasNarrix: !!req.narrix,
+                            hasNarrixInput: !!req.narrixInput,
+                            overrideContextProvided: options?.overrideContext !== undefined,
+                            captureContextProvided: options?.captureContext !== undefined,
+                            synthesisContextAuthoritative: options?.synthesisContextAuthoritative === true,
                         },
-                    };
-                });
-            };
-            const runMainWithExecutionStrategies = async (req, options) => {
-                const strat = knobs.resolvedExecutionStrategies;
-                let working = { ...req };
-                const prefixSteps = [];
-                for (let pi = 0; pi < strat.orderedBefore.length; pi++) {
-                    const spec = strat.orderedBefore[pi];
-                    if (spec.strategyKey !== "planner")
-                        continue;
-                    const payload = buildExecutionStrategyRequestPayload({
-                        skillKey: working.skillKey,
-                        input: working.input,
-                        variables: working.variables,
-                        jobContext: working.jobContext,
-                        jobMemory: working.jobMemory,
-                        taskMemory: working.taskMemory,
-                        executionMemory: working.executionMemory,
-                        jobId: working.jobId,
-                        taskId: working.taskId,
-                        agentId: working.agentId,
-                        graphId: working.graphId,
-                        nodeId: working.nodeId,
-                        prevNodeId: working.prevNodeId,
-                        coreSkillId: working.coreSkillId,
-                        includeContextInPrompt: working.includeContextInPrompt,
-                    });
-                    const catalogDefaultFunctionId = resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, spec);
-                    const plannerOut = await runPlannerFuncx({
-                        args: spec.args,
-                        requestPayload: payload,
-                        defaultFunctionId: catalogDefaultFunctionId,
-                    });
-                    working = applyPlannerOutputToRequest(working, plannerOut, pi);
-                    prefixSteps.push({
-                        step: prefixSteps.length + 1,
-                        id: `executionStrategy.planner.${pi}`,
-                        ok: true,
-                        summary: "FuncX planner (execution/plan)",
-                        outputExcerpt: {
-                            hasInstructions: typeof plannerOut.instructions === "string",
-                            hasPrompt: typeof plannerOut.prompt === "string",
-                            variableKeys: plannerOut.variables ? Object.keys(plannerOut.variables).slice(0, 20) : [],
-                            functionIdSource: typeof spec.args?.functionId === "string"
-                                ? "invocation"
-                                : catalogDefaultFunctionId
-                                    ? "catalog"
-                                    : "code-default",
+                        fn: async () => this._executeDirect(req, {
+                            ...options,
+                            validationCorrelationId: taskId,
+                            traceCollector,
+                        }),
+                        onSuccessUpdates: (result) => {
+                            const steps = result?.intermediateSteps;
+                            return {
+                                instructionVersion: result?.metadata?.instructionVersion,
+                                activityId: result?.metadata?.activityId,
+                                durationMs: result?.metadata?.durationMs,
+                                hasIntermediateSteps: Array.isArray(steps) && steps.length > 0,
+                                stepCount: Array.isArray(steps) ? steps.length : undefined,
+                                outer: activixOuterTier({
+                                    kind: "runTask.request",
+                                    skillKey: req.skillKey,
+                                    executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                                    jobId: req.jobId,
+                                    agentId: req.agentId,
+                                    graphId: req.graphId,
+                                    nodeId: req.nodeId,
+                                    masterSkillId: req.masterSkillId,
+                                    masterSkillActivityId: req.masterSkillActivityId,
+                                    includeContextInPrompt: req.includeContextInPrompt === true,
+                                    hasPipeline: Array.isArray(req.executionPipeline) && req.executionPipeline.length > 0,
+                                    hasNarrix: !!req.narrix,
+                                    hasNarrixInput: !!req.narrixInput,
+                                    input: summarizeForOuter(req.input, 4_000),
+                                }, {
+                                    kind: "runTask.response",
+                                    skillKey: result?.skillKey,
+                                    // Keep this intentionally small; rawText / flexMd payloads can be huge.
+                                    metadata: summarizeForOuter(result?.metadata, 4_000),
+                                    parsed: summarizeForOuter(result?.parsed, 8_000),
+                                }, { phase: "direct" }),
+                            };
                         },
-                    });
-                    if (traceCollector) {
-                        traceCollector.push({
-                            taskType: "pre-execution",
-                            details: "execution strategy planner (FuncX)",
+                    }), (result) => {
+                        const modelUsed = modelUsedFromResult(result);
+                        const r = result;
+                        return {
+                            modelUsed: modelUsed ?? null,
                             metadata: {
-                                ...baseTraceMeta(),
-                                phase: "execution_strategy_planner",
-                                plannerIndex: pi,
+                                activityId: r?.metadata?.activityId,
+                                instructionVersion: r?.metadata?.instructionVersion,
+                                durationMs: r?.metadata?.durationMs,
+                                outputValidation: r?.metadata?.outputValidation,
                             },
-                            modelUsed: null,
-                        });
-                    }
-                }
-                const mergePrefixSteps = (result) => {
-                    if (prefixSteps.length === 0)
-                        return result;
-                    const existing = (result.intermediateSteps ?? []);
-                    const shifted = existing.map((s, i) => ({ ...s, step: prefixSteps.length + i + 1 }));
-                    result.intermediateSteps = [...prefixSteps, ...shifted];
-                    return result;
+                        };
+                    });
                 };
-                const primary = strat.primaryOptimizer;
-                const maxIter = strat.effectivePrimaryOptimizerMaxIterations;
-                if (!primary) {
-                    return mergePrefixSteps(await runDirect(working, options));
-                }
-                let last;
-                for (let iter = 0; iter < maxIter; iter++) {
-                    last = await runDirect(working, options);
-                    const mainSummary = {
-                        rawText: typeof last.rawText === "string" ? String(last.rawText).slice(0, 12_000) : undefined,
-                        parsed: last.parsed,
-                        skillKey: last.skillKey,
-                        metadata: last.metadata ? summarizeForOuter(last.metadata, 6_000) : undefined,
-                    };
-                    const evalOut = await runOptimizerFuncx({
-                        args: primary.args,
-                        defaultFunctionId: resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, primary),
-                        requestPayload: buildExecutionStrategyRequestPayload({
+                const runMainWithExecutionStrategies = async (req, options) => {
+                    const strat = knobs.resolvedExecutionStrategies;
+                    let working = { ...req };
+                    const prefixSteps = [];
+                    for (let pi = 0; pi < strat.orderedBefore.length; pi++) {
+                        const spec = strat.orderedBefore[pi];
+                        if (spec.strategyKey !== "planner")
+                            continue;
+                        const payload = buildExecutionStrategyRequestPayload({
                             skillKey: working.skillKey,
                             input: working.input,
                             variables: working.variables,
@@ -766,757 +709,864 @@ export class WorexClientTasks {
                             prevNodeId: working.prevNodeId,
                             coreSkillId: working.coreSkillId,
                             includeContextInPrompt: working.includeContextInPrompt,
-                        }),
-                        mainResultSummary: mainSummary,
-                        iterationIndex: iter,
-                    });
-                    if (traceCollector) {
-                        traceCollector.push({
-                            taskType: "ai-task",
-                            details: "execution strategy optimizer (FuncX)",
-                            metadata: {
-                                ...baseTraceMeta(),
-                                phase: "execution_strategy_optimizer",
-                                iterationIndex: iter,
-                                satisfied: evalOut.satisfied === true,
+                        });
+                        const catalogDefaultFunctionId = resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, spec);
+                        const plannerOut = await runPlannerFuncx({
+                            args: spec.args,
+                            requestPayload: payload,
+                            defaultFunctionId: catalogDefaultFunctionId,
+                        });
+                        working = applyPlannerOutputToRequest(working, plannerOut, pi);
+                        prefixSteps.push({
+                            step: prefixSteps.length + 1,
+                            id: `executionStrategy.planner.${pi}`,
+                            ok: true,
+                            summary: "FuncX planner (execution/plan)",
+                            outputExcerpt: {
+                                hasInstructions: typeof plannerOut.instructions === "string",
+                                hasPrompt: typeof plannerOut.prompt === "string",
+                                variableKeys: plannerOut.variables ? Object.keys(plannerOut.variables).slice(0, 20) : [],
+                                functionIdSource: typeof spec.args?.functionId === "string"
+                                    ? "invocation"
+                                    : catalogDefaultFunctionId
+                                        ? "catalog"
+                                        : "code-default",
                             },
-                            modelUsed: modelUsedFromResult(last) ?? null,
                         });
+                        if (traceCollector) {
+                            traceCollector.push({
+                                taskType: "pre-execution",
+                                details: "execution strategy planner (FuncX)",
+                                metadata: {
+                                    ...baseTraceMeta(),
+                                    phase: "execution_strategy_planner",
+                                    plannerIndex: pi,
+                                },
+                                modelUsed: null,
+                            });
+                        }
                     }
-                    if (evalOut.satisfied) {
-                        return mergePrefixSteps(last);
+                    const mergePrefixSteps = (result) => {
+                        if (prefixSteps.length === 0)
+                            return result;
+                        const existing = (result.intermediateSteps ?? []);
+                        const shifted = existing.map((s, i) => ({ ...s, step: prefixSteps.length + i + 1 }));
+                        result.intermediateSteps = [...prefixSteps, ...shifted];
+                        return result;
+                    };
+                    const primary = strat.primaryOptimizer;
+                    const maxIter = strat.effectivePrimaryOptimizerMaxIterations;
+                    if (!primary) {
+                        return mergePrefixSteps(await runDirect(working, options));
                     }
-                    if (iter === maxIter - 1) {
-                        return mergePrefixSteps(last);
+                    let last;
+                    for (let iter = 0; iter < maxIter; iter++) {
+                        last = await runDirect(working, options);
+                        const mainSummary = {
+                            rawText: typeof last.rawText === "string" ? String(last.rawText).slice(0, 12_000) : undefined,
+                            parsed: last.parsed,
+                            skillKey: last.skillKey,
+                            metadata: last.metadata ? summarizeForOuter(last.metadata, 6_000) : undefined,
+                        };
+                        const evalOut = await runOptimizerFuncx({
+                            args: primary.args,
+                            defaultFunctionId: resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, primary),
+                            requestPayload: buildExecutionStrategyRequestPayload({
+                                skillKey: working.skillKey,
+                                input: working.input,
+                                variables: working.variables,
+                                jobContext: working.jobContext,
+                                jobMemory: working.jobMemory,
+                                taskMemory: working.taskMemory,
+                                executionMemory: working.executionMemory,
+                                jobId: working.jobId,
+                                taskId: working.taskId,
+                                agentId: working.agentId,
+                                graphId: working.graphId,
+                                nodeId: working.nodeId,
+                                prevNodeId: working.prevNodeId,
+                                coreSkillId: working.coreSkillId,
+                                includeContextInPrompt: working.includeContextInPrompt,
+                            }),
+                            mainResultSummary: mainSummary,
+                            iterationIndex: iter,
+                        });
+                        if (traceCollector) {
+                            traceCollector.push({
+                                taskType: "ai-task",
+                                details: "execution strategy optimizer (FuncX)",
+                                metadata: {
+                                    ...baseTraceMeta(),
+                                    phase: "execution_strategy_optimizer",
+                                    iterationIndex: iter,
+                                    satisfied: evalOut.satisfied === true,
+                                },
+                                modelUsed: modelUsedFromResult(last) ?? null,
+                            });
+                        }
+                        if (evalOut.satisfied) {
+                            return mergePrefixSteps(last);
+                        }
+                        if (iter === maxIter - 1) {
+                            return mergePrefixSteps(last);
+                        }
+                        working = applyOptimizerFeedbackToRequest(working, evalOut, iter + 1);
                     }
-                    working = applyOptimizerFeedbackToRequest(working, evalOut, iter + 1);
-                }
-                return mergePrefixSteps(last);
-            };
-            // NARRIX task-level pre-processor + structured handler: `narrixMode` (+ inference) via `resolveRunTaskRuntimeKnobs`.
-            if (knobs.narrixMode === "preprocessor" && request.narrix) {
-                const narrixCfg = request.narrix;
-                await traceWrap(traceCollector, {
-                    taskType: "pre-execution",
-                    details: "narrix preprocessor",
-                    metadata: {
-                        ...baseTraceMeta(),
-                        phase: "narrix",
-                        datasetId: narrixCfg.datasetId,
-                        attachToField: narrixCfg.attachToField ?? "_narrix",
-                        enableWebScope: narrixCfg.enableWebScope === true,
-                    },
-                }, async () => withPhaseRecord({
-                    ax,
-                    correlationId,
-                    phase: "narrix",
-                    meta: {
-                        ...baseMeta,
-                        narrixAttachToField: narrixCfg.attachToField ?? "_narrix",
-                        outer: activixOuterTier({
-                            kind: "narrix.preProcessor.request",
+                    return mergePrefixSteps(last);
+                };
+                // NARRIX task-level pre-processor + structured handler: `narrixMode` (+ inference) via `resolveRunTaskRuntimeKnobs`.
+                if (knobs.narrixMode === "preprocessor" && request.narrix) {
+                    const narrixCfg = request.narrix;
+                    await traceWrap(traceCollector, {
+                        taskType: "pre-execution",
+                        details: "narrix preprocessor",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "narrix",
                             datasetId: narrixCfg.datasetId,
                             attachToField: narrixCfg.attachToField ?? "_narrix",
                             enableWebScope: narrixCfg.enableWebScope === true,
-                            webScoping: narrixCfg.webScoping ? summarizeForOuter(narrixCfg.webScoping, 2_000) : undefined,
-                            requestInput: summarizeForOuter(request.input, 4_000),
-                        }, null, { phase: "narrix" }),
-                    },
-                    fn: async () => {
-                        const adaptResult = adaptMemorixToNarrixInput({
-                            datasetId: narrixCfg.datasetId,
-                            mediumHint: "record",
-                            memorix: {
+                        },
+                    }, async () => withPhaseRecord({
+                        ax,
+                        correlationId,
+                        phase: "narrix",
+                        meta: {
+                            ...baseMeta,
+                            narrixAttachToField: narrixCfg.attachToField ?? "_narrix",
+                            outer: activixOuterTier({
+                                kind: "narrix.preProcessor.request",
+                                datasetId: narrixCfg.datasetId,
+                                attachToField: narrixCfg.attachToField ?? "_narrix",
+                                enableWebScope: narrixCfg.enableWebScope === true,
+                                webScoping: narrixCfg.webScoping ? summarizeForOuter(narrixCfg.webScoping, 2_000) : undefined,
+                                requestInput: summarizeForOuter(request.input, 4_000),
+                            }, null, { phase: "narrix" }),
+                        },
+                        fn: async () => {
+                            const adaptResult = adaptMemorixToNarrixInput({
+                                datasetId: narrixCfg.datasetId,
+                                mediumHint: "record",
+                                memorix: {
+                                    jobMemory: request.jobMemory,
+                                    executionMemory: request.executionMemory,
+                                    input: request.input,
+                                },
+                            }, {
+                                record: {
+                                    minKeys: 1,
+                                    preferPaths: [
+                                        "executionMemory.input.raw",
+                                        "executionMemory.inputs.*.raw",
+                                        "jobMemory.record",
+                                        "jobMemory.currentRecord",
+                                        "executionMemory.input.record",
+                                        "executionMemory.record",
+                                        "taskMemory.currentRecord",
+                                        "*.currentRecord",
+                                        "*.record",
+                                    ],
+                                },
+                            });
+                            if (!adaptResult.ok) {
+                                const attempted = adaptResult.attempted?.length ? ` Attempted: ${adaptResult.attempted.join(", ")}.` : "";
+                                const summary = adaptResult.foundSummary ? ` Seen: ${adaptResult.foundSummary}` : "";
+                                throw new Error(`NARRIX pre-processor: no usable input. ${adaptResult.message}.${attempted}${summary}`);
+                            }
+                            const ctx = {
+                                skillKey: request.skillKey,
                                 jobMemory: request.jobMemory,
+                                taskMemory: request.taskMemory,
                                 executionMemory: request.executionMemory,
-                                input: request.input,
-                            },
-                        }, {
-                            record: {
-                                minKeys: 1,
-                                preferPaths: [
-                                    "executionMemory.input.raw",
-                                    "executionMemory.inputs.*.raw",
-                                    "jobMemory.record",
-                                    "jobMemory.currentRecord",
-                                    "executionMemory.input.record",
-                                    "executionMemory.record",
-                                    "taskMemory.currentRecord",
-                                    "*.currentRecord",
-                                    "*.record",
-                                ],
-                            },
-                        });
-                        if (!adaptResult.ok) {
-                            const attempted = adaptResult.attempted?.length ? ` Attempted: ${adaptResult.attempted.join(", ")}.` : "";
-                            const summary = adaptResult.foundSummary ? ` Seen: ${adaptResult.foundSummary}` : "";
-                            throw new Error(`NARRIX pre-processor: no usable input. ${adaptResult.message}.${attempted}${summary}`);
+                                variables: input.variables,
+                                xynthesized: request.xynthesized,
+                                smartInput: request.smartInput,
+                                jobId: input.jobId,
+                                taskId: request.taskId,
+                                agentId: input.agentId,
+                                graphId: input.graphId,
+                                nodeId: input.nodeId,
+                                prevNodeId: input.prevNodeId,
+                                coreSkillId: input.coreSkillId,
+                                masterSkillId: request.masterSkillId,
+                                masterSkillActivityId: request.masterSkillActivityId,
+                            };
+                            const narrixResult = await narrixRunHandler({ input: adaptResult.narrixInput, ctx });
+                            if (!narrixResult.ok) {
+                                const fail = narrixResult;
+                                throw new Error(`NARRIX pre-processor failed: ${fail.error}${fail.message ? ` - ${fail.message}` : ""}`);
+                            }
+                            const attachment = buildNarrixAttachment(narrixResult);
+                            const attachToField = narrixCfg.attachToField ?? "_narrix";
+                            let webContextEntry = undefined;
+                            let webContextAvailable;
+                            let webContextReason;
+                            const externalWebMdPreNarrix = typeof request.executionMemory?.webContextMarkdown === "string" &&
+                                request.executionMemory.webContextMarkdown.trim().length > 0;
+                            const skipWebScopeForExternalMd = narrixCfg.skipWebScopeWhenExternalWebMarkdownPresent === true && externalWebMdPreNarrix;
+                            if (narrixCfg.enableWebScope === true && !skipWebScopeForExternalMd) {
+                                const successResult = narrixResult;
+                                const entity = adaptResult.narrixInput.medium === "record"
+                                    ? adaptResult.narrixInput.record
+                                    : undefined;
+                                const scopeFields = resolveWebScopeQuestionAndTemplates({
+                                    narrix: narrixCfg,
+                                    requestInput: request.input,
+                                    successResult,
+                                    entity,
+                                });
+                                const webScopeOpts = hasNonEmptyWebScoping(narrixCfg.webScoping)
+                                    ? { scoping: narrixCfg.webScoping }
+                                    : undefined;
+                                const activixPatch = webScopeActivixCorrelationPatch({
+                                    jobId: request.jobId,
+                                    taskId: request.taskId,
+                                    sessionId: request.taskId,
+                                });
+                                const packQs = scopeFields.packQuestions;
+                                if (Array.isArray(packQs) && packQs.length > 0) {
+                                    webContextEntry = await runWebScopeQuestionPack({
+                                        datasetId: narrixCfg.datasetId,
+                                        subjectId: successResult.entity.entityKey,
+                                        entityKind: successResult.entity.entityKind,
+                                        entity,
+                                        cni: successResult.cni,
+                                        ...activixPatch,
+                                        questions: packQs,
+                                    }, webScopeOpts);
+                                }
+                                else {
+                                    const { packQuestions: _pq, ...genericScope } = scopeFields;
+                                    void _pq;
+                                    webContextEntry = await runWebScope({
+                                        datasetId: narrixCfg.datasetId,
+                                        subjectId: successResult.entity.entityKey,
+                                        entityKind: successResult.entity.entityKind,
+                                        entity,
+                                        cni: successResult.cni,
+                                        ...activixPatch,
+                                        ...genericScope,
+                                    }, webScopeOpts);
+                                }
+                                if (webContextEntry && typeof webContextEntry === "object") {
+                                    const wc = webContextEntry;
+                                    webContextAvailable = typeof wc.available === "boolean" ? wc.available : undefined;
+                                    webContextReason = typeof wc.reason === "string" ? wc.reason : undefined;
+                                }
+                                if (webContextEntry &&
+                                    typeof webContextEntry === "object" &&
+                                    webContextEntry.available === false) {
+                                    const miss = webContextEntry;
+                                    if (process.env.NARRIX_DEBUG === "1") {
+                                        getAiTasksLogxer().warnCode(AI_TASKS_DIAGNOSTIC_CODES.NARRIX_WEB_SCOPE_MISS, {
+                                            source: "@exellix/ai-tasks",
+                                            debugKind: DebugLogAbstract.ANOMALY,
+                                            diagnostics: {
+                                                summary: "Narrix web scope miss",
+                                                actual: miss.error ?? miss.reason ?? "web context unavailable",
+                                            },
+                                            evidence: [
+                                                fieldEvidence("webContext.reason", miss.reason ?? null),
+                                                fieldEvidence("webContext.error", miss.error ?? null),
+                                            ],
+                                        });
+                                    }
+                                    if (traceCollector) {
+                                        traceCollector.push({
+                                            taskType: "pre-execution",
+                                            details: "narrix web scope miss",
+                                            metadata: {
+                                                ...baseTraceMeta(),
+                                                phase: "narrix",
+                                                webContext: { available: false, reason: miss.reason, error: miss.error },
+                                            },
+                                            modelUsed: null,
+                                        });
+                                    }
+                                }
+                            }
+                            request = {
+                                ...request,
+                                executionMemory: {
+                                    ...(request.executionMemory || {}),
+                                    [attachToField]: attachment,
+                                    ...(webContextEntry !== undefined ? { webContext: webContextEntry } : {}),
+                                },
+                                jobMemory: request.jobMemory ? { ...request.jobMemory, _narrix: attachment } : { _narrix: attachment },
+                            };
+                            const scopingSignalsCount = Array.isArray(attachment?.scoping?.signals) ? attachment.scoping.signals.length : undefined;
+                            const scopingStoriesCount = Array.isArray(attachment?.scoping?.stories) ? attachment.scoping.stories.length : undefined;
+                            const discoverySignalsCount = Array.isArray(attachment?.discovery?.signals) ? attachment.discovery.signals.length : undefined;
+                            const discoveryStoriesCount = Array.isArray(attachment?.discovery?.stories) ? attachment.discovery.stories.length : undefined;
+                            const entityKey = narrixResult?.entity?.entityKey;
+                            const entityKind = narrixResult?.entity?.entityKind;
+                            return {
+                                datasetId: narrixCfg.datasetId,
+                                attachToField,
+                                enableWebScope: narrixCfg.enableWebScope === true,
+                                webContextAvailable,
+                                webContextReason,
+                                attachmentMeta: isRecord(attachment?.meta) ? attachment.meta : undefined,
+                                scopingSignalsCount,
+                                scopingStoriesCount,
+                                discoverySignalsCount,
+                                discoveryStoriesCount,
+                                entityKey: typeof entityKey === "string" ? entityKey : undefined,
+                                entityKind: typeof entityKind === "string" ? entityKind : undefined,
+                                medium: typeof adaptResult.narrixInput?.medium === "string" ? adaptResult.narrixInput.medium : undefined,
+                            };
+                        },
+                        onSuccessUpdates: (r) => ({
+                            outer: activixOuterTier({
+                                kind: "narrix.preProcessor.request",
+                                datasetId: narrixCfg.datasetId,
+                                attachToField: narrixCfg.attachToField ?? "_narrix",
+                                enableWebScope: narrixCfg.enableWebScope === true,
+                                webScoping: narrixCfg.webScoping ? summarizeForOuter(narrixCfg.webScoping, 2_000) : undefined,
+                                requestInput: summarizeForOuter(request.input, 4_000),
+                            }, {
+                                kind: "narrix.preProcessor.result",
+                                datasetId: r.datasetId,
+                                attachToField: r.attachToField,
+                                enableWebScope: r.enableWebScope,
+                                entity: r.entityKey ? { entityKey: r.entityKey, entityKind: r.entityKind } : undefined,
+                                counts: {
+                                    scopingSignals: r.scopingSignalsCount,
+                                    scopingStories: r.scopingStoriesCount,
+                                    discoverySignals: r.discoverySignalsCount,
+                                    discoveryStories: r.discoveryStoriesCount,
+                                },
+                                webContext: r.enableWebScope
+                                    ? { available: r.webContextAvailable, reason: r.webContextReason }
+                                    : undefined,
+                                attachmentMeta: r.attachmentMeta,
+                            }, { phase: "narrix" }),
+                        }),
+                    }));
+                }
+                // Structured Narrix (`narrixInput`): same enrichment as legacy `narrix-then-direct`, but runs before local tasks / pipeline PRE.
+                if (knobs.narrixMode === "handler") {
+                    if (!request.narrixInput) {
+                        throw new Error(`narrixMode "handler" requires narrixInput. ` +
+                            `Provide { medium, datasetId, ... } or { $path: "jobMemory.currentRecord" } on the request.`);
+                    }
+                    const resolvedNarrixInput = resolveNarrixInput(request.narrixInput, request.jobMemory);
+                    if (!resolvedNarrixInput) {
+                        throw new Error(`narrixMode "handler": narrixInput could not be resolved. ` +
+                            `Ensure it has medium and datasetId, or that $path points to a valid object in jobMemory.`);
+                    }
+                    let narrixThenDirectPhaseRecordId = null;
+                    if (ax && correlationId) {
+                        try {
+                            narrixThenDirectPhaseRecordId = (await ax.startRecord({
+                                correlationId,
+                                phase: "narrix_then_direct",
+                                ...baseMeta,
+                                narrixDatasetId: resolvedNarrixInput.datasetId,
+                                narrixMedium: resolvedNarrixInput.medium,
+                                outer: activixOuterTier({
+                                    kind: "narrixThenDirect.request",
+                                    skillKey: request.skillKey,
+                                    jobId: request.jobId,
+                                    agentId: request.agentId,
+                                    narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
+                                }, null, { phase: "narrix_then_direct" }),
+                            })).recordId;
+                        }
+                        catch {
+                            narrixThenDirectPhaseRecordId = null;
                         }
-                        const ctx = {
+                    }
+                    try {
+                        const narrixStarted = Date.now();
+                        const narrixHandlerCtx = {
                             skillKey: request.skillKey,
                             jobMemory: request.jobMemory,
                             taskMemory: request.taskMemory,
                             executionMemory: request.executionMemory,
-                            variables: input.variables,
+                            variables: request.variables,
                             xynthesized: request.xynthesized,
                             smartInput: request.smartInput,
-                            jobId: input.jobId,
+                            jobId: request.jobId,
                             taskId: request.taskId,
-                            agentId: input.agentId,
-                            graphId: input.graphId,
-                            nodeId: input.nodeId,
-                            prevNodeId: input.prevNodeId,
-                            coreSkillId: input.coreSkillId,
+                            agentId: request.agentId,
+                            graphId: request.graphId,
+                            nodeId: request.nodeId,
+                            prevNodeId: request.prevNodeId,
+                            coreSkillId: request.coreSkillId,
                             masterSkillId: request.masterSkillId,
                             masterSkillActivityId: request.masterSkillActivityId,
                         };
-                        const narrixResult = await narrixRunHandler({ input: adaptResult.narrixInput, ctx });
+                        const narrixResult = await traceWrap(traceCollector, {
+                            taskType: "pre-execution",
+                            details: "narrix structured handler (narrixInput)",
+                            metadata: {
+                                ...baseTraceMeta(),
+                                phase: "narrix_then_direct",
+                                datasetId: resolvedNarrixInput.datasetId,
+                                medium: resolvedNarrixInput.medium,
+                            },
+                        }, async () => narrixRunHandler({ input: resolvedNarrixInput, ctx: narrixHandlerCtx }), (r) => ({
+                            metadata: { ok: r?.ok === true },
+                            modelUsed: null,
+                        }));
+                        const narrixDurationMs = Date.now() - narrixStarted;
                         if (!narrixResult.ok) {
                             const fail = narrixResult;
-                            throw new Error(`NARRIX pre-processor failed: ${fail.error}${fail.message ? ` - ${fail.message}` : ""}`);
-                        }
-                        const attachment = buildNarrixAttachment(narrixResult);
-                        const attachToField = narrixCfg.attachToField ?? "_narrix";
-                        let webContextEntry = undefined;
-                        let webContextAvailable;
-                        let webContextReason;
-                        const externalWebMdPreNarrix = typeof request.executionMemory?.webContextMarkdown === "string" &&
-                            request.executionMemory.webContextMarkdown.trim().length > 0;
-                        const skipWebScopeForExternalMd = narrixCfg.skipWebScopeWhenExternalWebMarkdownPresent === true && externalWebMdPreNarrix;
-                        if (narrixCfg.enableWebScope === true && !skipWebScopeForExternalMd) {
-                            const successResult = narrixResult;
-                            const entity = adaptResult.narrixInput.medium === "record"
-                                ? adaptResult.narrixInput.record
-                                : undefined;
-                            const scopeFields = resolveWebScopeQuestionAndTemplates({
-                                narrix: narrixCfg,
-                                requestInput: request.input,
-                                successResult,
-                                entity,
-                            });
-                            const webScopeOpts = hasNonEmptyWebScoping(narrixCfg.webScoping)
-                                ? { scoping: narrixCfg.webScoping }
-                                : undefined;
-                            const activixPatch = webScopeActivixCorrelationPatch({
-                                jobId: request.jobId,
-                                taskId: request.taskId,
-                                sessionId: request.taskId,
-                            });
-                            const packQs = scopeFields.packQuestions;
-                            if (Array.isArray(packQs) && packQs.length > 0) {
-                                webContextEntry = await runWebScopeQuestionPack({
-                                    datasetId: narrixCfg.datasetId,
-                                    subjectId: successResult.entity.entityKey,
-                                    entityKind: successResult.entity.entityKind,
-                                    entity,
-                                    cni: successResult.cni,
-                                    ...activixPatch,
-                                    questions: packQs,
-                                }, webScopeOpts);
-                            }
-                            else {
-                                const { packQuestions: _pq, ...genericScope } = scopeFields;
-                                void _pq;
-                                webContextEntry = await runWebScope({
-                                    datasetId: narrixCfg.datasetId,
-                                    subjectId: successResult.entity.entityKey,
-                                    entityKind: successResult.entity.entityKind,
-                                    entity,
-                                    cni: successResult.cni,
-                                    ...activixPatch,
-                                    ...genericScope,
-                                }, webScopeOpts);
-                            }
-                            if (webContextEntry && typeof webContextEntry === "object") {
-                                const wc = webContextEntry;
-                                webContextAvailable = typeof wc.available === "boolean" ? wc.available : undefined;
-                                webContextReason = typeof wc.reason === "string" ? wc.reason : undefined;
-                            }
-                            if (webContextEntry &&
-                                typeof webContextEntry === "object" &&
-                                webContextEntry.available === false) {
-                                const miss = webContextEntry;
-                                if (process.env.NARRIX_DEBUG === "1") {
-                                    getAiTasksLogxer().warnCode(AI_TASKS_DIAGNOSTIC_CODES.NARRIX_WEB_SCOPE_MISS, {
-                                        source: "@exellix/ai-tasks",
-                                        debugKind: DebugLogAbstract.ANOMALY,
-                                        diagnostics: {
-                                            summary: "Narrix web scope miss",
-                                            actual: miss.error ?? miss.reason ?? "web context unavailable",
-                                        },
-                                        evidence: [
-                                            fieldEvidence("webContext.reason", miss.reason ?? null),
-                                            fieldEvidence("webContext.error", miss.error ?? null),
-                                        ],
-                                    });
-                                }
-                                if (traceCollector) {
-                                    traceCollector.push({
-                                        taskType: "pre-execution",
-                                        details: "narrix web scope miss",
-                                        metadata: {
-                                            ...baseTraceMeta(),
-                                            phase: "narrix",
-                                            webContext: { available: false, reason: miss.reason, error: miss.error },
-                                        },
-                                        modelUsed: null,
-                                    });
-                                }
+                            if (ax && correlationId && narrixThenDirectPhaseRecordId) {
+                                await ax
+                                    .failRecord(narrixThenDirectPhaseRecordId, new Error(`Narrix handler failed: ${fail.error}${fail.message ? ` - ${fail.message}` : ""}`), {
+                                    errorMessage: fail.message ? `${fail.error} - ${fail.message}` : fail.error,
+                                    errorCode: fail.code,
+                                    narrixDurationMs,
+                                })
+                                    .catch(() => undefined);
                             }
+                            return withTrace({
+                                skillKey: request.skillKey,
+                                rawText: JSON.stringify(narrixResult, null, 2),
+                                flexMd: { frame: "narrixThenDirect.v1", payloads: { narrix: JSON.stringify(narrixResult) } },
+                                parsed: {
+                                    ok: false,
+                                    error: narrixResult.error,
+                                    phase: "narrix",
+                                    message: narrixResult.message,
+                                },
+                                metadata: {
+                                    instructionVersion: "narrix-then-direct",
+                                    narrix: { ...narrixResult, durationMs: narrixDurationMs },
+                                    narrixMode: knobs.narrixMode,
+                                    inputStrategyKey: knobs.inputStrategyKey,
+                                    executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                                },
+                            });
                         }
+                        const filteredEntry = applyNarrixScope(narrixResult, request.narrixScope);
+                        const existingNarrix = Array.isArray(request.taskMemory?.narrix)
+                            ? request.taskMemory.narrix
+                            : [];
+                        const updatedTaskMemory = {
+                            ...(request.taskMemory ?? {}),
+                            narrix: [...existingNarrix, filteredEntry],
+                        };
+                        const skillInput = typeof request.input === "object" && request.input !== null
+                            ? { ...request.input, narrixContext: filteredEntry }
+                            : { narrixContext: filteredEntry };
                         request = {
                             ...request,
-                            executionMemory: {
-                                ...(request.executionMemory || {}),
-                                [attachToField]: attachment,
-                                ...(webContextEntry !== undefined ? { webContext: webContextEntry } : {}),
-                            },
-                            jobMemory: request.jobMemory ? { ...request.jobMemory, _narrix: attachment } : { _narrix: attachment },
-                        };
-                        const scopingSignalsCount = Array.isArray(attachment?.scoping?.signals) ? attachment.scoping.signals.length : undefined;
-                        const scopingStoriesCount = Array.isArray(attachment?.scoping?.stories) ? attachment.scoping.stories.length : undefined;
-                        const discoverySignalsCount = Array.isArray(attachment?.discovery?.signals) ? attachment.discovery.signals.length : undefined;
-                        const discoveryStoriesCount = Array.isArray(attachment?.discovery?.stories) ? attachment.discovery.stories.length : undefined;
-                        const entityKey = narrixResult?.entity?.entityKey;
-                        const entityKind = narrixResult?.entity?.entityKind;
-                        return {
-                            datasetId: narrixCfg.datasetId,
-                            attachToField,
-                            enableWebScope: narrixCfg.enableWebScope === true,
-                            webContextAvailable,
-                            webContextReason,
-                            attachmentMeta: isRecord(attachment?.meta) ? attachment.meta : undefined,
-                            scopingSignalsCount,
-                            scopingStoriesCount,
-                            discoverySignalsCount,
-                            discoveryStoriesCount,
-                            entityKey: typeof entityKey === "string" ? entityKey : undefined,
-                            entityKind: typeof entityKind === "string" ? entityKind : undefined,
-                            medium: typeof adaptResult.narrixInput?.medium === "string" ? adaptResult.narrixInput.medium : undefined,
+                            taskMemory: updatedTaskMemory,
+                            input: skillInput,
                         };
-                    },
-                    onSuccessUpdates: (r) => ({
-                        outer: activixOuterTier({
-                            kind: "narrix.preProcessor.request",
-                            datasetId: narrixCfg.datasetId,
-                            attachToField: narrixCfg.attachToField ?? "_narrix",
-                            enableWebScope: narrixCfg.enableWebScope === true,
-                            webScoping: narrixCfg.webScoping ? summarizeForOuter(narrixCfg.webScoping, 2_000) : undefined,
-                            requestInput: summarizeForOuter(request.input, 4_000),
-                        }, {
-                            kind: "narrix.preProcessor.result",
-                            datasetId: r.datasetId,
-                            attachToField: r.attachToField,
-                            enableWebScope: r.enableWebScope,
-                            entity: r.entityKey ? { entityKey: r.entityKey, entityKind: r.entityKind } : undefined,
-                            counts: {
-                                scopingSignals: r.scopingSignalsCount,
-                                scopingStories: r.scopingStoriesCount,
-                                discoverySignals: r.discoverySignalsCount,
-                                discoveryStories: r.discoveryStoriesCount,
-                            },
-                            webContext: r.enableWebScope
-                                ? { available: r.webContextAvailable, reason: r.webContextReason }
-                                : undefined,
-                            attachmentMeta: r.attachmentMeta,
-                        }, { phase: "narrix" }),
-                    }),
-                }));
-            }
-            // Structured Narrix (`narrixInput`): same enrichment as legacy `narrix-then-direct`, but runs before local tasks / pipeline PRE.
-            if (knobs.narrixMode === "handler") {
-                if (!request.narrixInput) {
-                    throw new Error(`narrixMode "handler" requires narrixInput. ` +
-                        `Provide { medium, datasetId, ... } or { $path: "jobMemory.currentRecord" } on the request.`);
-                }
-                const resolvedNarrixInput = resolveNarrixInput(request.narrixInput, request.jobMemory);
-                if (!resolvedNarrixInput) {
-                    throw new Error(`narrixMode "handler": narrixInput could not be resolved. ` +
-                        `Ensure it has medium and datasetId, or that $path points to a valid object in jobMemory.`);
-                }
-                let narrixThenDirectPhaseRecordId = null;
-                if (ax && correlationId) {
-                    try {
-                        narrixThenDirectPhaseRecordId = (await ax.startRecord({
-                            correlationId,
-                            phase: "narrix_then_direct",
-                            ...baseMeta,
-                            narrixDatasetId: resolvedNarrixInput.datasetId,
-                            narrixMedium: resolvedNarrixInput.medium,
-                            outer: activixOuterTier({
-                                kind: "narrixThenDirect.request",
-                                skillKey: request.skillKey,
-                                jobId: request.jobId,
-                                agentId: request.agentId,
-                                narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
-                            }, null, { phase: "narrix_then_direct" }),
-                        })).recordId;
-                    }
-                    catch {
-                        narrixThenDirectPhaseRecordId = null;
-                    }
-                }
-                try {
-                    const narrixStarted = Date.now();
-                    const narrixHandlerCtx = {
-                        skillKey: request.skillKey,
-                        jobMemory: request.jobMemory,
-                        taskMemory: request.taskMemory,
-                        executionMemory: request.executionMemory,
-                        variables: request.variables,
-                        xynthesized: request.xynthesized,
-                        smartInput: request.smartInput,
-                        jobId: request.jobId,
-                        taskId: request.taskId,
-                        agentId: request.agentId,
-                        graphId: request.graphId,
-                        nodeId: request.nodeId,
-                        prevNodeId: request.prevNodeId,
-                        coreSkillId: request.coreSkillId,
-                        masterSkillId: request.masterSkillId,
-                        masterSkillActivityId: request.masterSkillActivityId,
-                    };
-                    const narrixResult = await traceWrap(traceCollector, {
-                        taskType: "pre-execution",
-                        details: "narrix structured handler (narrixInput)",
-                        metadata: {
-                            ...baseTraceMeta(),
-                            phase: "narrix_then_direct",
-                            datasetId: resolvedNarrixInput.datasetId,
-                            medium: resolvedNarrixInput.medium,
-                        },
-                    }, async () => narrixRunHandler({ input: resolvedNarrixInput, ctx: narrixHandlerCtx }), (r) => ({
-                        metadata: { ok: r?.ok === true },
-                        modelUsed: null,
-                    }));
-                    const narrixDurationMs = Date.now() - narrixStarted;
-                    if (!narrixResult.ok) {
-                        const fail = narrixResult;
                         if (ax && correlationId && narrixThenDirectPhaseRecordId) {
                             await ax
-                                .failRecord(narrixThenDirectPhaseRecordId, new Error(`Narrix handler failed: ${fail.error}${fail.message ? ` - ${fail.message}` : ""}`), {
-                                errorMessage: fail.message ? `${fail.error} - ${fail.message}` : fail.error,
-                                errorCode: fail.code,
+                                .completeRecord(narrixThenDirectPhaseRecordId, {
                                 narrixDurationMs,
+                                outer: activixOuterTier({
+                                    kind: "narrixThenDirect.request",
+                                    skillKey: request.skillKey,
+                                    jobId: request.jobId,
+                                    agentId: request.agentId,
+                                    narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
+                                }, {
+                                    kind: "narrixThenDirect.result",
+                                    ok: true,
+                                    durationMs: narrixDurationMs,
+                                }, { phase: "narrix_then_direct" }),
                             })
                                 .catch(() => undefined);
                         }
-                        return withTrace({
-                            skillKey: request.skillKey,
-                            rawText: JSON.stringify(narrixResult, null, 2),
-                            flexMd: { frame: "narrixThenDirect.v1", payloads: { narrix: JSON.stringify(narrixResult) } },
-                            parsed: {
-                                ok: false,
-                                error: narrixResult.error,
-                                phase: "narrix",
-                                message: narrixResult.message,
-                            },
-                            metadata: {
-                                instructionVersion: "narrix-then-direct",
-                                narrix: { ...narrixResult, durationMs: narrixDurationMs },
-                                narrixMode: knobs.narrixMode,
-                                inputStrategyKey: knobs.inputStrategyKey,
-                                executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
-                            },
-                        });
                     }
-                    const filteredEntry = applyNarrixScope(narrixResult, request.narrixScope);
-                    const existingNarrix = Array.isArray(request.taskMemory?.narrix)
-                        ? request.taskMemory.narrix
-                        : [];
-                    const updatedTaskMemory = {
-                        ...(request.taskMemory ?? {}),
-                        narrix: [...existingNarrix, filteredEntry],
-                    };
-                    const skillInput = typeof request.input === "object" && request.input !== null
-                        ? { ...request.input, narrixContext: filteredEntry }
-                        : { narrixContext: filteredEntry };
-                    request = {
-                        ...request,
-                        taskMemory: updatedTaskMemory,
-                        input: skillInput,
-                    };
-                    if (ax && correlationId && narrixThenDirectPhaseRecordId) {
-                        await ax
-                            .completeRecord(narrixThenDirectPhaseRecordId, {
-                            narrixDurationMs,
-                            outer: activixOuterTier({
-                                kind: "narrixThenDirect.request",
-                                skillKey: request.skillKey,
-                                jobId: request.jobId,
-                                agentId: request.agentId,
-                                narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
-                            }, {
-                                kind: "narrixThenDirect.result",
-                                ok: true,
-                                durationMs: narrixDurationMs,
-                            }, { phase: "narrix_then_direct" }),
-                        })
-                            .catch(() => undefined);
+                    catch (error) {
+                        if (ax && correlationId && narrixThenDirectPhaseRecordId) {
+                            await ax
+                                .failRecord(narrixThenDirectPhaseRecordId, error instanceof Error ? error : new Error(String(error)), {
+                                errorMessage: error instanceof Error ? error.message : String(error),
+                                errorCode: error?.code,
+                                outer: activixOuterTier({
+                                    kind: "narrixThenDirect.request",
+                                    skillKey: request.skillKey,
+                                    jobId: request.jobId,
+                                    agentId: request.agentId,
+                                    narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
+                                }, {
+                                    kind: "narrixThenDirect.error",
+                                    message: error instanceof Error ? error.message : String(error),
+                                }, { phase: "narrix_then_direct" }),
+                            })
+                                .catch(() => undefined);
+                        }
+                        throw error;
                     }
                 }
-                catch (error) {
-                    if (ax && correlationId && narrixThenDirectPhaseRecordId) {
-                        await ax
-                            .failRecord(narrixThenDirectPhaseRecordId, error instanceof Error ? error : new Error(String(error)), {
-                            errorMessage: error instanceof Error ? error.message : String(error),
-                            errorCode: error?.code,
+                // Local task dispatch: if a handler is registered, run it and return (no enrichment)
+                const handler = getLocalTask(request.skillKey);
+                if (handler) {
+                    const result = await traceWrap(traceCollector, {
+                        taskType: "pre-execution",
+                        details: "local task handler",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "local",
+                            localSkillKey: request.skillKey,
+                        },
+                        modelUsed: null,
+                    }, async () => withPhaseRecord({
+                        ax,
+                        correlationId,
+                        phase: "local",
+                        meta: {
+                            ...baseMeta,
+                            localSkillKey: request.skillKey,
                             outer: activixOuterTier({
-                                kind: "narrixThenDirect.request",
+                                kind: "localTask.request",
                                 skillKey: request.skillKey,
                                 jobId: request.jobId,
                                 agentId: request.agentId,
-                                narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
-                            }, {
-                                kind: "narrixThenDirect.error",
-                                message: error instanceof Error ? error.message : String(error),
-                            }, { phase: "narrix_then_direct" }),
-                        })
-                            .catch(() => undefined);
-                    }
-                    throw error;
-                }
-            }
-            // Local task dispatch: if a handler is registered, run it and return (no enrichment)
-            const handler = getLocalTask(request.skillKey);
-            if (handler) {
-                const result = await traceWrap(traceCollector, {
-                    taskType: "pre-execution",
-                    details: "local task handler",
-                    metadata: {
-                        ...baseTraceMeta(),
-                        phase: "local",
-                        localSkillKey: request.skillKey,
-                    },
-                    modelUsed: null,
-                }, async () => withPhaseRecord({
-                    ax,
-                    correlationId,
-                    phase: "local",
-                    meta: {
-                        ...baseMeta,
-                        localSkillKey: request.skillKey,
-                        outer: activixOuterTier({
-                            kind: "localTask.request",
-                            skillKey: request.skillKey,
-                            jobId: request.jobId,
-                            agentId: request.agentId,
-                            input: summarizeForOuter(request.input, 4_000),
-                        }, null, { phase: "local" }),
-                    },
-                    fn: async () => {
-                        const started = Date.now();
-                        const ctx = {
-                            skillKey: request.skillKey,
-                            jobMemory: request.jobMemory,
-                            taskMemory: request.taskMemory,
-                            executionMemory: request.executionMemory,
-                            variables: input.variables,
-                            xynthesized: request.xynthesized,
-                            smartInput: request.smartInput,
-                            jobId: input.jobId,
-                            taskId: input.taskId,
-                            agentId: input.agentId,
-                            graphId: input.graphId,
-                            nodeId: input.nodeId,
-                            prevNodeId: input.prevNodeId,
-                            coreSkillId: input.coreSkillId,
-                            masterSkillId: request.masterSkillId,
-                            masterSkillActivityId: request.masterSkillActivityId,
-                        };
-                        const value = await handler({ input: request.input, ctx });
-                        const durationMs = Date.now() - started;
-                        let parsed = value;
-                        let intermediateSteps;
-                        if (value !== null &&
-                            typeof value === "object" &&
-                            !Array.isArray(value) &&
-                            "intermediateSteps" in value) {
-                            const steps = value.intermediateSteps;
-                            if (Array.isArray(steps) &&
-                                steps.length > 0 &&
-                                steps.every((s) => typeof s === "object" && s !== null && "step" in s && "id" in s && "ok" in s)) {
-                                intermediateSteps = steps;
-                                const { intermediateSteps: _removed, ...rest } = value;
-                                parsed = (Object.keys(rest).length > 0 ? rest : undefined);
-                            }
-                        }
-                        const response = {
-                            skillKey: request.skillKey,
-                            rawText: JSON.stringify(value, null, 2),
-                            flexMd: {
-                                frame: "localTask.v1",
-                                payloads: { value: JSON.stringify(value, null, 2) },
-                            },
-                            parsed,
-                            metadata: {
-                                instructionVersion: "local",
-                                activityId: undefined,
-                                durationMs,
-                                localSkillKey: request.skillKey,
-                            },
-                        };
-                        if (intermediateSteps)
-                            response.intermediateSteps = intermediateSteps;
-                        if (isStrictDecisionTask(request)) {
-                            const parsedMissing = response.parsed === undefined || response.parsed === null;
-                            if (parsedMissing) {
-                                throw new Error(`Decision task "${request.skillKey}" did not return response.parsed`);
+                                input: summarizeForOuter(request.input, 4_000),
+                            }, null, { phase: "local" }),
+                        },
+                        fn: async () => {
+                            const started = Date.now();
+                            const ctx = {
+                                skillKey: request.skillKey,
+                                jobMemory: request.jobMemory,
+                                taskMemory: request.taskMemory,
+                                executionMemory: request.executionMemory,
+                                variables: input.variables,
+                                xynthesized: request.xynthesized,
+                                smartInput: request.smartInput,
+                                jobId: input.jobId,
+                                taskId: input.taskId,
+                                agentId: input.agentId,
+                                graphId: input.graphId,
+                                nodeId: input.nodeId,
+                                prevNodeId: input.prevNodeId,
+                                coreSkillId: input.coreSkillId,
+                                masterSkillId: request.masterSkillId,
+                                masterSkillActivityId: request.masterSkillActivityId,
+                            };
+                            const value = await handler({ input: request.input, ctx });
+                            const durationMs = Date.now() - started;
+                            let parsed = value;
+                            let intermediateSteps;
+                            if (value !== null &&
+                                typeof value === "object" &&
+                                !Array.isArray(value) &&
+                                "intermediateSteps" in value) {
+                                const steps = value.intermediateSteps;
+                                if (Array.isArray(steps) &&
+                                    steps.length > 0 &&
+                                    steps.every((s) => typeof s === "object" && s !== null && "step" in s && "id" in s && "ok" in s)) {
+                                    intermediateSteps = steps;
+                                    const { intermediateSteps: _removed, ...rest } = value;
+                                    parsed = (Object.keys(rest).length > 0 ? rest : undefined);
+                                }
                             }
-                        }
-                        const outputValidation = request.outputValidation;
-                        if (outputValidation?.schema) {
-                            const validateWhenMissing = outputValidation.validateWhenMissing !== false;
-                            if (validateWhenMissing || response.parsed !== undefined) {
-                                const vr = validateParsedOutput(response.parsed, outputValidation.schema);
-                                vr.correlationId = taskId;
-                                response.metadata = { ...response.metadata, outputValidation: vr };
-                                if (!vr.ok && (outputValidation.mode ?? "fail") === "fail") {
-                                    throw new Error(`outputValidation failed for skillKey ${request.skillKey}: ` +
-                                        vr.errors.map((e) => `${e.path} ${e.message}`).join("; "));
+                            const response = {
+                                skillKey: request.skillKey,
+                                rawText: JSON.stringify(value, null, 2),
+                                flexMd: {
+                                    frame: "localTask.v1",
+                                    payloads: { value: JSON.stringify(value, null, 2) },
+                                },
+                                parsed,
+                                metadata: {
+                                    instructionVersion: "local",
+                                    activityId: undefined,
+                                    durationMs,
+                                    localSkillKey: request.skillKey,
+                                },
+                            };
+                            if (intermediateSteps)
+                                response.intermediateSteps = intermediateSteps;
+                            if (isStrictDecisionTask(request)) {
+                                const parsedMissing = response.parsed === undefined || response.parsed === null;
+                                if (parsedMissing) {
+                                    throw new Error(`Decision task "${request.skillKey}" did not return response.parsed`);
                                 }
-                                if (!vr.ok && (outputValidation.mode ?? "fail") === "warn") {
+                            }
+                            const outputValidation = request.outputValidation;
+                            if (outputValidation?.schema) {
+                                const validateWhenMissing = outputValidation.validateWhenMissing !== false;
+                                if (validateWhenMissing || response.parsed !== undefined) {
+                                    const vr = validateParsedOutput(response.parsed, outputValidation.schema);
+                                    vr.correlationId = taskId;
+                                    response.metadata = { ...response.metadata, outputValidation: vr };
+                                    if (!vr.ok && (outputValidation.mode ?? "fail") === "fail") {
+                                        throw new Error(`outputValidation failed for skillKey ${request.skillKey}: ` +
+                                            vr.errors.map((e) => `${e.path} ${e.message}`).join("; "));
+                                    }
+                                    if (!vr.ok && (outputValidation.mode ?? "fail") === "warn") {
+                                    }
                                 }
                             }
-                        }
-                        return response;
-                    },
-                    onSuccessUpdates: (result) => {
-                        const steps = result?.intermediateSteps;
-                        return {
-                            localSkillKey: result?.metadata?.localSkillKey,
-                            durationMs: result?.metadata?.durationMs,
-                            hasIntermediateSteps: Array.isArray(steps) && steps.length > 0,
-                            stepCount: Array.isArray(steps) ? steps.length : undefined,
-                            outer: activixOuterTier({
-                                kind: "localTask.request",
-                                skillKey: request.skillKey,
-                                jobId: request.jobId,
-                                agentId: request.agentId,
-                                input: summarizeForOuter(request.input, 4_000),
-                            }, {
-                                kind: "localTask.response",
-                                skillKey: result?.skillKey,
-                                metadata: summarizeForOuter(result?.metadata, 4_000),
-                                parsed: summarizeForOuter(result?.parsed, 8_000),
-                            }, { phase: "local" }),
-                        };
-                    },
-                }), (r) => ({
-                    metadata: {
-                        durationMs: r?.metadata?.durationMs,
-                    },
-                    modelUsed: null,
-                }));
-                return withTrace(finalize(result));
-            }
-            // Execution pipeline: when request.executionPipeline is set, run PRE steps then main then POST
-            const pipeline = request.executionPipeline;
-            if (pipeline && Array.isArray(pipeline) && pipeline.length > 0) {
-                const mainSteps = pipeline.filter((s) => s.phase === "main");
-                if (mainSteps.length !== 1) {
-                    throw new Error(`executionPipeline must have exactly one step with phase "main"; got ${mainSteps.length}. skillKey: ${request.skillKey}`);
+                            return response;
+                        },
+                        onSuccessUpdates: (result) => {
+                            const steps = result?.intermediateSteps;
+                            return {
+                                localSkillKey: result?.metadata?.localSkillKey,
+                                durationMs: result?.metadata?.durationMs,
+                                hasIntermediateSteps: Array.isArray(steps) && steps.length > 0,
+                                stepCount: Array.isArray(steps) ? steps.length : undefined,
+                                outer: activixOuterTier({
+                                    kind: "localTask.request",
+                                    skillKey: request.skillKey,
+                                    jobId: request.jobId,
+                                    agentId: request.agentId,
+                                    input: summarizeForOuter(request.input, 4_000),
+                                }, {
+                                    kind: "localTask.response",
+                                    skillKey: result?.skillKey,
+                                    metadata: summarizeForOuter(result?.metadata, 4_000),
+                                    parsed: summarizeForOuter(result?.parsed, 8_000),
+                                }, { phase: "local" }),
+                            };
+                        },
+                    }), (r) => ({
+                        metadata: {
+                            durationMs: r?.metadata?.durationMs,
+                        },
+                        modelUsed: null,
+                    }));
+                    return withTrace(finalize(result));
                 }
-                const preSteps = pipeline.filter((s) => s.phase === "pre");
-                let overrideContext;
-                let synthesizedArtifact;
-                let detectedTemplateCores = [];
-                // Aggregated trace-mode-only LlmCallObservations from PRE synthesis (markdown/structured/questionDriven).
-                // Lifted into `result.metadata.synthesizedContextLlmCalls` once the pipeline finishes.
-                const aggregatedSynthLlmCalls = [];
-                for (const step of preSteps) {
-                    if (step.type !== SYNTHESIZED_CONTEXT) {
-                        throw new Error(`executionPipeline: unsupported PRE step type "${String(step.type)}". Only "${SYNTHESIZED_CONTEXT}" (Xynthesis synthesized-context) is supported.`);
+                // Execution pipeline: when request.executionPipeline is set, run PRE steps then main then POST
+                const pipeline = request.executionPipeline;
+                if (pipeline && Array.isArray(pipeline) && pipeline.length > 0) {
+                    const mainSteps = pipeline.filter((s) => s.phase === "main");
+                    if (mainSteps.length !== 1) {
+                        throw new Error(`executionPipeline must have exactly one step with phase "main"; got ${mainSteps.length}. skillKey: ${request.skillKey}`);
                     }
-                    {
-                        const config = (step.config ?? {});
-                        if (request.includeContextInPrompt !== true && config.autoEnableContext !== true) {
-                            throw new Error("synthesized-context PRE step requires includeContextInPrompt: true or synthesisConfig.autoEnableContext: true");
+                    const preSteps = pipeline.filter((s) => s.phase === "pre");
+                    let overrideContext;
+                    let synthesizedArtifact;
+                    let detectedTemplateCores = [];
+                    // Aggregated trace-mode-only LlmCallObservations from PRE synthesis (markdown/structured/questionDriven).
+                    // Lifted into `result.metadata.synthesizedContextLlmCalls` once the pipeline finishes.
+                    const aggregatedSynthLlmCalls = [];
+                    for (const step of preSteps) {
+                        if (step.type !== SYNTHESIZED_CONTEXT) {
+                            throw new Error(`executionPipeline: unsupported PRE step type "${String(step.type)}". Only "${SYNTHESIZED_CONTEXT}" (Xynthesis synthesized-context) is supported.`);
                         }
-                        const reqWithContext = { ...request, includeContextInPrompt: true };
-                        const cachedSynth = request.executionMemory?.synthesizedContext;
-                        const preStepResult = config.reuseCachedSynthesizedContext === true &&
-                            cachedSynth &&
-                            reuseableSynthesizedArtifact(cachedSynth)
-                            ? {
-                                contextMarkdown: contextMarkdownFromArtifact(cachedSynth),
-                                artifact: cachedSynth,
-                                synthesizedInput: request.executionMemory?.synthesizedInput,
+                        {
+                            const config = (step.config ?? {});
+                            if (request.includeContextInPrompt !== true && config.autoEnableContext !== true) {
+                                throw new Error("synthesized-context PRE step requires includeContextInPrompt: true or synthesisConfig.autoEnableContext: true");
                             }
-                            : await traceWrap(traceCollector, {
-                                taskType: "pre-execution",
-                                details: "synthesized-context pre step",
-                                metadata: {
-                                    ...baseTraceMeta(),
-                                    phase: "pipeline_pre",
-                                    preStepType: "synthesized-context",
-                                    synthesisMode: resolveSynthesisMode(config),
-                                    reusedCache: false,
-                                    ...(config.xynthesizedOutput && traceCollector
-                                        ? {
-                                            xynthesized: {
-                                                inputPathsUsed: [...(config.memoryPaths ?? [])],
-                                                outputDestination: config.xynthesizedOutput.destination,
-                                                outputKey: config.xynthesizedOutput.outputKey,
-                                                patchKeys: [config.xynthesizedOutput.outputKey],
-                                            },
-                                            smartInput: {
-                                                paths: reqWithContext.smartInput?.paths ?? [],
-                                            },
-                                        }
-                                        : traceCollector
+                            const reqWithContext = { ...request, includeContextInPrompt: true };
+                            const cachedSynth = request.executionMemory?.synthesizedContext;
+                            const preStepResult = config.reuseCachedSynthesizedContext === true &&
+                                cachedSynth &&
+                                reuseableSynthesizedArtifact(cachedSynth)
+                                ? {
+                                    contextMarkdown: contextMarkdownFromArtifact(cachedSynth),
+                                    artifact: cachedSynth,
+                                    synthesizedInput: request.executionMemory?.synthesizedInput,
+                                }
+                                : await traceWrap(traceCollector, {
+                                    taskType: "pre-execution",
+                                    details: "synthesized-context pre step",
+                                    metadata: {
+                                        ...baseTraceMeta(),
+                                        phase: "pipeline_pre",
+                                        preStepType: "synthesized-context",
+                                        synthesisMode: resolveSynthesisMode(config),
+                                        reusedCache: false,
+                                        ...(config.xynthesizedOutput && traceCollector
                                             ? {
+                                                xynthesized: {
+                                                    inputPathsUsed: [...(config.memoryPaths ?? [])],
+                                                    outputDestination: config.xynthesizedOutput.destination,
+                                                    outputKey: config.xynthesizedOutput.outputKey,
+                                                    patchKeys: [config.xynthesizedOutput.outputKey],
+                                                },
                                                 smartInput: {
                                                     paths: reqWithContext.smartInput?.paths ?? [],
                                                 },
                                             }
+                                            : traceCollector
+                                                ? {
+                                                    smartInput: {
+                                                        paths: reqWithContext.smartInput?.paths ?? [],
+                                                    },
+                                                }
+                                                : {}),
+                                    },
+                                }, async () => withPhaseRecord({
+                                    ax,
+                                    correlationId,
+                                    phase: "pipeline_pre",
+                                    meta: {
+                                        ...baseMeta,
+                                        preStepType: "synthesized-context",
+                                        outer: activixOuterTier({
+                                            kind: "pipelinePre.synthesizedContext.request",
+                                            skillKey: reqWithContext.skillKey,
+                                            jobId: reqWithContext.jobId,
+                                            agentId: reqWithContext.agentId,
+                                            contextSourcePolicy: config?.contextSourcePolicy,
+                                            synthesisMode: resolveSynthesisMode(config),
+                                            input: summarizeForOuter(reqWithContext.input, 4_000),
+                                        }, null, { phase: "pipeline_pre" }),
+                                    },
+                                    fn: async () => this._runSynthesizedContextPreStep(reqWithContext, config, traceCollector),
+                                    onSuccessUpdates: (r) => ({
+                                        outer: activixOuterTier({
+                                            kind: "pipelinePre.synthesizedContext.request",
+                                            skillKey: reqWithContext.skillKey,
+                                            jobId: reqWithContext.jobId,
+                                            agentId: reqWithContext.agentId,
+                                            contextSourcePolicy: config?.contextSourcePolicy,
+                                            synthesisMode: resolveSynthesisMode(config),
+                                            input: summarizeForOuter(reqWithContext.input, 4_000),
+                                        }, {
+                                            kind: "pipelinePre.synthesizedContext.result",
+                                            contextMarkdown: summarizeForOuter(r.contextMarkdown, 8_000),
+                                            artifact: r.artifact
+                                                ? {
+                                                    mode: r.artifact.mode,
+                                                    templateCores: r.artifact?.templateCores ?? [],
+                                                    question: typeof r.artifact?.question === "string"
+                                                        ? summarizeForOuter(r.artifact.question, 2_000)
+                                                        : undefined,
+                                                }
+                                                : undefined,
+                                        }, { phase: "pipeline_pre" }),
+                                    }),
+                                }), (r) => ({
+                                    metadata: {
+                                        synthesizedContextChars: typeof r.contextMarkdown === "string" ? r.contextMarkdown.length : 0,
+                                        ...(config.xynthesizedOutput && traceCollector
+                                            ? {
+                                                xynthesized: {
+                                                    inputPathsUsed: [...(config.memoryPaths ?? [])],
+                                                    outputDestination: config.xynthesizedOutput.destination,
+                                                    outputKey: config.xynthesizedOutput.outputKey,
+                                                    patchKeys: [config.xynthesizedOutput.outputKey],
+                                                },
+                                            }
                                             : {}),
-                                },
-                            }, async () => withPhaseRecord({
-                                ax,
-                                correlationId,
-                                phase: "pipeline_pre",
-                                meta: {
-                                    ...baseMeta,
-                                    preStepType: "synthesized-context",
-                                    outer: activixOuterTier({
-                                        kind: "pipelinePre.synthesizedContext.request",
-                                        skillKey: reqWithContext.skillKey,
-                                        jobId: reqWithContext.jobId,
-                                        agentId: reqWithContext.agentId,
-                                        contextSourcePolicy: config?.contextSourcePolicy,
-                                        synthesisMode: resolveSynthesisMode(config),
-                                        input: summarizeForOuter(reqWithContext.input, 4_000),
-                                    }, null, { phase: "pipeline_pre" }),
-                                },
-                                fn: async () => this._runSynthesizedContextPreStep(reqWithContext, config, traceCollector),
-                                onSuccessUpdates: (r) => ({
-                                    outer: activixOuterTier({
-                                        kind: "pipelinePre.synthesizedContext.request",
-                                        skillKey: reqWithContext.skillKey,
-                                        jobId: reqWithContext.jobId,
-                                        agentId: reqWithContext.agentId,
-                                        contextSourcePolicy: config?.contextSourcePolicy,
+                                    },
+                                }));
+                            overrideContext = preStepResult.contextMarkdown;
+                            synthesizedArtifact = preStepResult.artifact;
+                            if (traceCollector && preStepResult.synthesizedContextLlmCalls) {
+                                aggregatedSynthLlmCalls.push(...preStepResult.synthesizedContextLlmCalls);
+                            }
+                            if (synthesizedArtifact) {
+                                detectedTemplateCores = synthesizedArtifact?.templateCores ?? [];
+                            }
+                            const xynthOut = config.xynthesizedOutput;
+                            const writeLegacyToExecutionMemory = !xynthOut || xynthOut.alsoWriteLegacySynthesizedContext !== false;
+                            if (synthesizedArtifact && writeLegacyToExecutionMemory) {
+                                request = {
+                                    ...request,
+                                    executionMemory: {
+                                        ...(request.executionMemory ?? {}),
+                                        synthesizedContext: synthesizedArtifact,
+                                        ...(preStepResult.synthesizedInput ? { synthesizedInput: preStepResult.synthesizedInput } : {}),
+                                    },
+                                };
+                            }
+                            if (xynthOut) {
+                                const synthesizedResult = synthesizedResultForXynthesizedPatch(synthesizedArtifact, preStepResult.contextMarkdown);
+                                const { nextXynthesized, patchSlice } = applyXynthesizedOutputWrite(request.xynthesized, xynthOut, synthesizedResult);
+                                request = { ...request, xynthesized: nextXynthesized };
+                                xynthesizedPatchAccumulator = mergeXynthesizedPatchSlices(xynthesizedPatchAccumulator, patchSlice);
+                            }
+                            if (traceCollector &&
+                                config.reuseCachedSynthesizedContext === true &&
+                                cachedSynth &&
+                                reuseableSynthesizedArtifact(cachedSynth)) {
+                                traceCollector.push({
+                                    taskType: "pre-execution",
+                                    details: "synthesized-context pre step (reused cached artifact)",
+                                    metadata: {
+                                        ...baseTraceMeta(),
+                                        phase: "pipeline_pre",
+                                        preStepType: "synthesized-context",
                                         synthesisMode: resolveSynthesisMode(config),
-                                        input: summarizeForOuter(reqWithContext.input, 4_000),
-                                    }, {
-                                        kind: "pipelinePre.synthesizedContext.result",
-                                        contextMarkdown: summarizeForOuter(r.contextMarkdown, 8_000),
-                                        artifact: r.artifact
+                                        reusedCache: true,
+                                        ...(config.xynthesizedOutput
                                             ? {
-                                                mode: r.artifact.mode,
-                                                templateCores: r.artifact?.templateCores ?? [],
-                                                question: typeof r.artifact?.question === "string"
-                                                    ? summarizeForOuter(r.artifact.question, 2_000)
-                                                    : undefined,
+                                                xynthesized: {
+                                                    inputPathsUsed: [...(config.memoryPaths ?? [])],
+                                                    outputDestination: config.xynthesizedOutput.destination,
+                                                    outputKey: config.xynthesizedOutput.outputKey,
+                                                    patchKeys: [config.xynthesizedOutput.outputKey],
+                                                },
+                                                smartInput: {
+                                                    paths: request.smartInput?.paths ?? [],
+                                                },
                                             }
-                                            : undefined,
-                                    }, { phase: "pipeline_pre" }),
-                                }),
-                            }), (r) => ({
-                                metadata: {
-                                    synthesizedContextChars: typeof r.contextMarkdown === "string" ? r.contextMarkdown.length : 0,
-                                    ...(config.xynthesizedOutput && traceCollector
-                                        ? {
-                                            xynthesized: {
-                                                inputPathsUsed: [...(config.memoryPaths ?? [])],
-                                                outputDestination: config.xynthesizedOutput.destination,
-                                                outputKey: config.xynthesizedOutput.outputKey,
-                                                patchKeys: [config.xynthesizedOutput.outputKey],
-                                            },
-                                        }
-                                        : {}),
-                                },
-                            }));
-                        overrideContext = preStepResult.contextMarkdown;
-                        synthesizedArtifact = preStepResult.artifact;
-                        if (traceCollector && preStepResult.synthesizedContextLlmCalls) {
-                            aggregatedSynthLlmCalls.push(...preStepResult.synthesizedContextLlmCalls);
+                                            : {
+                                                smartInput: {
+                                                    paths: request.smartInput?.paths ?? [],
+                                                },
+                                            }),
+                                    },
+                                    modelUsed: null,
+                                });
+                            }
+                            break;
                         }
-                        if (synthesizedArtifact) {
-                            detectedTemplateCores = synthesizedArtifact?.templateCores ?? [];
+                    }
+                    const synthesizedFromExecution = request.executionMemory?.synthesizedContext &&
+                        typeof request.executionMemory.synthesizedContext === "object";
+                    const mainContextSource = synthesizedFromExecution ? "synthesizedContext" : "unsynthesized";
+                    if (mainContextSource === "synthesizedContext") {
+                        const artifact = request.executionMemory?.synthesizedContext;
+                        if (artifact && typeof artifact === "object" && typeof artifact.contextMarkdown === "string") {
+                            overrideContext = artifact.contextMarkdown;
                         }
-                        const xynthOut = config.xynthesizedOutput;
-                        const writeLegacyToExecutionMemory = !xynthOut || xynthOut.alsoWriteLegacySynthesizedContext !== false;
-                        if (synthesizedArtifact && writeLegacyToExecutionMemory) {
-                            request = {
-                                ...request,
-                                executionMemory: {
-                                    ...(request.executionMemory ?? {}),
-                                    synthesizedContext: synthesizedArtifact,
-                                    ...(preStepResult.synthesizedInput ? { synthesizedInput: preStepResult.synthesizedInput } : {}),
+                    }
+                    const postSteps = pipeline.filter((s) => s.phase === "post");
+                    const observability = {
+                        synthesisEnabled: preSteps.some((s) => s.type === SYNTHESIZED_CONTEXT),
+                        effectiveExecutionPipeline: pipeline,
+                        synthesizedContextPresent: synthesizedFromExecution,
+                        mainContextSource,
+                        detectedTemplateCores,
+                        synthesisMode: synthesizedArtifact?.mode === "markdown" || synthesizedArtifact?.mode === "structured"
+                            ? synthesizedArtifact.mode
+                            : undefined,
+                    };
+                    const directOpts = {
+                        overrideContext,
+                        synthesisContextAuthoritative: mainContextSource === "synthesizedContext",
+                    };
+                    if (postSteps.length === 0) {
+                        const result = finalize(await runMainWithExecutionStrategies(request, directOpts));
+                        if (overrideContext !== undefined) {
+                            const synthesisStep = {
+                                step: 1,
+                                id: "synthesis",
+                                ok: true,
+                                summary: "context synthesized",
+                                outputExcerpt: {
+                                    mainContextSource,
+                                    synthesizedContextPresent: observability.synthesizedContextPresent,
+                                    detectedTemplateCores: observability.detectedTemplateCores ?? [],
                                 },
                             };
+                            const existingSteps = result.intermediateSteps ?? [];
+                            result.intermediateSteps = [
+                                synthesisStep,
+                                ...existingSteps.map((s, i) => ({ ...s, step: i + 2 })),
+                            ];
                         }
-                        if (xynthOut) {
-                            const synthesizedResult = synthesizedResultForXynthesizedPatch(synthesizedArtifact, preStepResult.contextMarkdown);
-                            const { nextXynthesized, patchSlice } = applyXynthesizedOutputWrite(request.xynthesized, xynthOut, synthesizedResult);
-                            request = { ...request, xynthesized: nextXynthesized };
-                            xynthesizedPatchAccumulator = mergeXynthesizedPatchSlices(xynthesizedPatchAccumulator, patchSlice);
-                        }
-                        if (traceCollector &&
-                            config.reuseCachedSynthesizedContext === true &&
-                            cachedSynth &&
-                            reuseableSynthesizedArtifact(cachedSynth)) {
-                            traceCollector.push({
-                                taskType: "pre-execution",
-                                details: "synthesized-context pre step (reused cached artifact)",
-                                metadata: {
-                                    ...baseTraceMeta(),
-                                    phase: "pipeline_pre",
-                                    preStepType: "synthesized-context",
-                                    synthesisMode: resolveSynthesisMode(config),
-                                    reusedCache: true,
-                                    ...(config.xynthesizedOutput
-                                        ? {
-                                            xynthesized: {
-                                                inputPathsUsed: [...(config.memoryPaths ?? [])],
-                                                outputDestination: config.xynthesizedOutput.destination,
-                                                outputKey: config.xynthesizedOutput.outputKey,
-                                                patchKeys: [config.xynthesizedOutput.outputKey],
-                                            },
-                                            smartInput: {
-                                                paths: request.smartInput?.paths ?? [],
-                                            },
-                                        }
-                                        : {
-                                            smartInput: {
-                                                paths: request.smartInput?.paths ?? [],
-                                            },
-                                        }),
-                                },
-                                modelUsed: null,
-                            });
+                        attachExecutionStateAndObservability(result, request, observability);
+                        if (traceCollector && aggregatedSynthLlmCalls.length > 0) {
+                            result.metadata = {
+                                ...(result.metadata ?? {}),
+                                synthesizedContextLlmCalls: aggregatedSynthLlmCalls,
+                            };
                         }
-                        break;
-                    }
-                }
-                const synthesizedFromExecution = request.executionMemory?.synthesizedContext &&
-                    typeof request.executionMemory.synthesizedContext === "object";
-                const mainContextSource = synthesizedFromExecution ? "synthesizedContext" : "unsynthesized";
-                if (mainContextSource === "synthesizedContext") {
-                    const artifact = request.executionMemory?.synthesizedContext;
-                    if (artifact && typeof artifact === "object" && typeof artifact.contextMarkdown === "string") {
-                        overrideContext = artifact.contextMarkdown;
+                        return withTrace(result);
                     }
-                }
-                const postSteps = pipeline.filter((s) => s.phase === "post");
-                const observability = {
-                    synthesisEnabled: preSteps.some((s) => s.type === SYNTHESIZED_CONTEXT),
-                    effectiveExecutionPipeline: pipeline,
-                    synthesizedContextPresent: synthesizedFromExecution,
-                    mainContextSource,
-                    detectedTemplateCores,
-                    synthesisMode: synthesizedArtifact?.mode === "markdown" || synthesizedArtifact?.mode === "structured"
-                        ? synthesizedArtifact.mode
-                        : undefined,
-                };
-                const directOpts = {
-                    overrideContext,
-                    synthesisContextAuthoritative: mainContextSource === "synthesizedContext",
-                };
-                if (postSteps.length === 0) {
-                    const result = finalize(await runMainWithExecutionStrategies(request, directOpts));
+                    const capture = { contextMarkdown: "" };
+                    let result = finalize(await runMainWithExecutionStrategies(request, { ...directOpts, captureContext: capture }));
                     if (overrideContext !== undefined) {
                         const synthesisStep = {
                             step: 1,
@@ -1535,212 +1585,190 @@ export class WorexClientTasks {
                             ...existingSteps.map((s, i) => ({ ...s, step: i + 2 })),
                         ];
                     }
-                    attachExecutionStateAndObservability(result, request, observability);
-                    if (traceCollector && aggregatedSynthLlmCalls.length > 0) {
-                        result.metadata = {
-                            ...(result.metadata ?? {}),
-                            synthesizedContextLlmCalls: aggregatedSynthLlmCalls,
-                        };
-                    }
-                    return withTrace(result);
-                }
-                const capture = { contextMarkdown: "" };
-                let result = finalize(await runMainWithExecutionStrategies(request, { ...directOpts, captureContext: capture }));
-                if (overrideContext !== undefined) {
-                    const synthesisStep = {
-                        step: 1,
-                        id: "synthesis",
-                        ok: true,
-                        summary: "context synthesized",
-                        outputExcerpt: {
-                            mainContextSource,
-                            synthesizedContextPresent: observability.synthesizedContextPresent,
-                            detectedTemplateCores: observability.detectedTemplateCores ?? [],
-                        },
-                    };
-                    const existingSteps = result.intermediateSteps ?? [];
-                    result.intermediateSteps = [
-                        synthesisStep,
-                        ...existingSteps.map((s, i) => ({ ...s, step: i + 2 })),
-                    ];
-                }
-                let currentOutput = typeof result.rawText === "string"
-                    ? result.rawText
-                    : JSON.stringify(result.parsed ?? result.rawText ?? "", null, 2);
-                const postStepsMeta = {};
-                let nextStepNumber = (result.intermediateSteps?.length ?? 0) + 1;
-                const reRunMain = (overrideContextWithFeedback) => runDirect(request, { overrideContext: overrideContextWithFeedback });
-                for (const step of postSteps) {
-                    if (step.type === "audit") {
-                        const auditResult = await traceWrap(traceCollector, {
-                            taskType: "post-execution",
-                            details: "audit post step",
-                            metadata: {
-                                ...baseTraceMeta(),
+                    let currentOutput = typeof result.rawText === "string"
+                        ? result.rawText
+                        : JSON.stringify(result.parsed ?? result.rawText ?? "", null, 2);
+                    const postStepsMeta = {};
+                    let nextStepNumber = (result.intermediateSteps?.length ?? 0) + 1;
+                    const reRunMain = (overrideContextWithFeedback) => runDirect(request, { overrideContext: overrideContextWithFeedback });
+                    for (const step of postSteps) {
+                        if (step.type === "audit") {
+                            const auditResult = await traceWrap(traceCollector, {
+                                taskType: "post-execution",
+                                details: "audit post step",
+                                metadata: {
+                                    ...baseTraceMeta(),
+                                    phase: "audit",
+                                    postStepType: "audit",
+                                },
+                            }, async () => withPhaseRecord({
+                                ax,
+                                correlationId,
                                 phase: "audit",
-                                postStepType: "audit",
-                            },
-                        }, async () => withPhaseRecord({
-                            ax,
-                            correlationId,
-                            phase: "audit",
-                            meta: {
-                                ...baseMeta,
-                                postStepType: "audit",
-                                outer: activixOuterTier({
-                                    kind: "postStep.audit.request",
-                                    skillKey: request.skillKey,
-                                    jobId: request.jobId,
-                                    agentId: request.agentId,
-                                    input: summarizeForOuter({
-                                        currentOutput,
-                                        hasContextMarkdown: !!capture.contextMarkdown,
-                                    }, 8_000),
-                                }, null, { phase: "audit" }),
-                            },
-                            fn: async () => runAuditPostStep({
-                                request,
-                                mainResult: result,
-                                contextMarkdown: capture.contextMarkdown,
-                                config: (step.config ?? {}),
-                                reRunMain,
-                                traceCollector,
-                            }),
-                            onSuccessUpdates: (auditResult) => ({
-                                totalCycles: auditResult.metadata?.totalCycles,
-                                allMustPassed: auditResult.metadata?.allMustPassed,
-                                synthesisUsed: auditResult.metadata?.synthesisUsed,
-                                durationMs: auditResult.metadata?.durationMs,
-                                outer: activixOuterTier({
-                                    kind: "postStep.audit.request",
-                                    skillKey: request.skillKey,
-                                    jobId: request.jobId,
-                                    agentId: request.agentId,
-                                    input: summarizeForOuter({
-                                        currentOutput,
-                                        hasContextMarkdown: !!capture.contextMarkdown,
-                                    }, 8_000),
-                                }, {
-                                    kind: "postStep.audit.result",
-                                    outputText: summarizeForOuter(auditResult.outputText, 8_000),
-                                    metadata: summarizeForOuter(auditResult.metadata, 6_000),
-                                }, { phase: "audit" }),
-                            }),
-                        }), (r) => ({
-                            metadata: {
-                                durationMs: r?.metadata?.durationMs,
-                                totalCycles: r?.metadata?.totalCycles,
-                                allMustPassed: r?.metadata?.allMustPassed,
-                            },
-                            modelUsed: r?.metadata?.modelUsed ?? null,
-                        }));
-                        currentOutput = auditResult.outputText;
-                        postStepsMeta.audit = auditResult.metadata;
-                        const stepsWithNumbers = auditResult.intermediateSteps.map((s) => ({
-                            ...s,
-                            step: nextStepNumber++,
-                        }));
-                        result.intermediateSteps = [
-                            ...(result.intermediateSteps ?? []),
-                            ...stepsWithNumbers,
-                        ];
-                    }
-                    else if (step.type === "polish") {
-                        const polishResult = await traceWrap(traceCollector, {
-                            taskType: "post-execution",
-                            details: "polish post step",
-                            metadata: {
-                                ...baseTraceMeta(),
+                                meta: {
+                                    ...baseMeta,
+                                    postStepType: "audit",
+                                    outer: activixOuterTier({
+                                        kind: "postStep.audit.request",
+                                        skillKey: request.skillKey,
+                                        jobId: request.jobId,
+                                        agentId: request.agentId,
+                                        input: summarizeForOuter({
+                                            currentOutput,
+                                            hasContextMarkdown: !!capture.contextMarkdown,
+                                        }, 8_000),
+                                    }, null, { phase: "audit" }),
+                                },
+                                fn: async () => runAuditPostStep({
+                                    request,
+                                    mainResult: result,
+                                    contextMarkdown: capture.contextMarkdown,
+                                    config: (step.config ?? {}),
+                                    reRunMain,
+                                    traceCollector,
+                                }),
+                                onSuccessUpdates: (auditResult) => ({
+                                    totalCycles: auditResult.metadata?.totalCycles,
+                                    allMustPassed: auditResult.metadata?.allMustPassed,
+                                    synthesisUsed: auditResult.metadata?.synthesisUsed,
+                                    durationMs: auditResult.metadata?.durationMs,
+                                    outer: activixOuterTier({
+                                        kind: "postStep.audit.request",
+                                        skillKey: request.skillKey,
+                                        jobId: request.jobId,
+                                        agentId: request.agentId,
+                                        input: summarizeForOuter({
+                                            currentOutput,
+                                            hasContextMarkdown: !!capture.contextMarkdown,
+                                        }, 8_000),
+                                    }, {
+                                        kind: "postStep.audit.result",
+                                        outputText: summarizeForOuter(auditResult.outputText, 8_000),
+                                        metadata: summarizeForOuter(auditResult.metadata, 6_000),
+                                    }, { phase: "audit" }),
+                                }),
+                            }), (r) => ({
+                                metadata: {
+                                    durationMs: r?.metadata?.durationMs,
+                                    totalCycles: r?.metadata?.totalCycles,
+                                    allMustPassed: r?.metadata?.allMustPassed,
+                                },
+                                modelUsed: r?.metadata?.modelUsed ?? null,
+                            }));
+                            currentOutput = auditResult.outputText;
+                            postStepsMeta.audit = auditResult.metadata;
+                            const stepsWithNumbers = auditResult.intermediateSteps.map((s) => ({
+                                ...s,
+                                step: nextStepNumber++,
+                            }));
+                            result.intermediateSteps = [
+                                ...(result.intermediateSteps ?? []),
+                                ...stepsWithNumbers,
+                            ];
+                        }
+                        else if (step.type === "polish") {
+                            const polishResult = await traceWrap(traceCollector, {
+                                taskType: "post-execution",
+                                details: "polish post step",
+                                metadata: {
+                                    ...baseTraceMeta(),
+                                    phase: "polish",
+                                    postStepType: "polish",
+                                },
+                            }, async () => withPhaseRecord({
+                                ax,
+                                correlationId,
                                 phase: "polish",
-                                postStepType: "polish",
-                            },
-                        }, async () => withPhaseRecord({
-                            ax,
-                            correlationId,
-                            phase: "polish",
-                            meta: {
-                                ...baseMeta,
-                                postStepType: "polish",
-                                outer: activixOuterTier({
-                                    kind: "postStep.polish.request",
-                                    skillKey: request.skillKey,
+                                meta: {
+                                    ...baseMeta,
+                                    postStepType: "polish",
+                                    outer: activixOuterTier({
+                                        kind: "postStep.polish.request",
+                                        skillKey: request.skillKey,
+                                        jobId: request.jobId,
+                                        agentId: request.agentId,
+                                        input: summarizeForOuter({ currentOutput }, 8_000),
+                                    }, null, { phase: "polish" }),
+                                },
+                                fn: async () => runPolishPostStep({
+                                    currentOutput,
+                                    config: (step.config ?? {}),
+                                    originalInput: step.config?.includeOriginalContext ? request.input : undefined,
+                                    promptContext: step.config?.includeOriginalContext ? capture.contextMarkdown : undefined,
+                                    traceCollector,
                                     jobId: request.jobId,
-                                    agentId: request.agentId,
-                                    input: summarizeForOuter({ currentOutput }, 8_000),
-                                }, null, { phase: "polish" }),
-                            },
-                            fn: async () => runPolishPostStep({
-                                currentOutput,
-                                config: (step.config ?? {}),
-                                originalInput: step.config?.includeOriginalContext ? request.input : undefined,
-                                promptContext: step.config?.includeOriginalContext ? capture.contextMarkdown : undefined,
-                                traceCollector,
-                                jobId: request.jobId,
-                                taskId: request.taskId,
-                                skillKey: request.skillKey,
-                                agentId: request.agentId,
-                                graphId: request.graphId,
-                                nodeId: request.nodeId,
-                                prevNodeId: request.prevNodeId,
-                                coreSkillId: request.coreSkillId,
-                                masterSkillId: request.masterSkillId,
-                                identity: request.identity,
-                            }),
-                            onSuccessUpdates: (polishResult) => ({
-                                totalPasses: polishResult.metadata?.totalPasses,
-                                durationMs: polishResult.metadata?.durationMs,
-                                outer: activixOuterTier({
-                                    kind: "postStep.polish.request",
+                                    taskId: request.taskId,
                                     skillKey: request.skillKey,
-                                    jobId: request.jobId,
                                     agentId: request.agentId,
-                                    input: summarizeForOuter({ currentOutput }, 8_000),
-                                }, {
-                                    kind: "postStep.polish.result",
-                                    outputText: summarizeForOuter(polishResult.outputText, 8_000),
-                                    metadata: summarizeForOuter(polishResult.metadata, 6_000),
-                                }, { phase: "polish" }),
-                            }),
-                        }), (r) => ({
-                            metadata: {
-                                durationMs: r?.metadata?.durationMs,
-                                totalPasses: r?.metadata?.totalPasses,
-                            },
-                            modelUsed: r?.metadata?.modelUsed ?? null,
-                        }));
-                        currentOutput = polishResult.outputText;
-                        postStepsMeta.polish = polishResult.metadata;
-                        const stepsWithNumbers = polishResult.intermediateSteps.map((s) => ({
-                            ...s,
-                            step: nextStepNumber++,
-                        }));
-                        result.intermediateSteps = [
-                            ...(result.intermediateSteps ?? []),
-                            ...stepsWithNumbers,
-                        ];
+                                    graphId: request.graphId,
+                                    nodeId: request.nodeId,
+                                    prevNodeId: request.prevNodeId,
+                                    coreSkillId: request.coreSkillId,
+                                    masterSkillId: request.masterSkillId,
+                                    identity: request.identity,
+                                }),
+                                onSuccessUpdates: (polishResult) => ({
+                                    totalPasses: polishResult.metadata?.totalPasses,
+                                    durationMs: polishResult.metadata?.durationMs,
+                                    outer: activixOuterTier({
+                                        kind: "postStep.polish.request",
+                                        skillKey: request.skillKey,
+                                        jobId: request.jobId,
+                                        agentId: request.agentId,
+                                        input: summarizeForOuter({ currentOutput }, 8_000),
+                                    }, {
+                                        kind: "postStep.polish.result",
+                                        outputText: summarizeForOuter(polishResult.outputText, 8_000),
+                                        metadata: summarizeForOuter(polishResult.metadata, 6_000),
+                                    }, { phase: "polish" }),
+                                }),
+                            }), (r) => ({
+                                metadata: {
+                                    durationMs: r?.metadata?.durationMs,
+                                    totalPasses: r?.metadata?.totalPasses,
+                                },
+                                modelUsed: r?.metadata?.modelUsed ?? null,
+                            }));
+                            currentOutput = polishResult.outputText;
+                            postStepsMeta.polish = polishResult.metadata;
+                            const stepsWithNumbers = polishResult.intermediateSteps.map((s) => ({
+                                ...s,
+                                step: nextStepNumber++,
+                            }));
+                            result.intermediateSteps = [
+                                ...(result.intermediateSteps ?? []),
+                                ...stepsWithNumbers,
+                            ];
+                        }
                     }
+                    result.rawText = currentOutput;
+                    result.parsed = currentOutput;
+                    result.metadata = {
+                        ...(result.metadata ?? {}),
+                        postSteps: postStepsMeta,
+                        ...(traceCollector && aggregatedSynthLlmCalls.length > 0
+                            ? { synthesizedContextLlmCalls: aggregatedSynthLlmCalls }
+                            : {}),
+                    };
+                    attachExecutionStateAndObservability(result, request, observability, knobs);
+                    return withTrace(result);
+                }
+                // MAIN path (direct / gateway skill). Narrix handler runs earlier when `narrixMode === "handler"`.
+                {
+                    const result = finalize(await runMainWithExecutionStrategies(request));
+                    attachExecutionStateAndObservability(result, request, {
+                        synthesisEnabled: false,
+                        synthesizedContextPresent: !!request.executionMemory?.synthesizedContext,
+                        mainContextSource: "unsynthesized",
+                    }, knobs);
+                    return withTrace(result);
                 }
-                result.rawText = currentOutput;
-                result.parsed = currentOutput;
-                result.metadata = {
-                    ...(result.metadata ?? {}),
-                    postSteps: postStepsMeta,
-                    ...(traceCollector && aggregatedSynthLlmCalls.length > 0
-                        ? { synthesizedContextLlmCalls: aggregatedSynthLlmCalls }
-                        : {}),
-                };
-                attachExecutionStateAndObservability(result, request, observability, knobs);
-                return withTrace(result);
             }
-            // MAIN path (direct / gateway skill). Narrix handler runs earlier when `narrixMode === "handler"`.
-            {
-                const result = finalize(await runMainWithExecutionStrategies(request));
-                attachExecutionStateAndObservability(result, request, {
-                    synthesisEnabled: false,
-                    synthesizedContextPresent: !!request.executionMemory?.synthesizedContext,
-                    mainContextSource: "unsynthesized",
-                }, knobs);
-                return withTrace(result);
+            catch (error) {
+                throw logAndEnrichRunTaskFailure({
+                    cause: error,
+                    ...failContext(),
+                });
             }
         });
     }